Struggling to get your AI agent to work reliably without constantly juggling API keys, network calls, or complex setup? Many developers waste time debugging provider configurations, handling async quirks, and writing boilerplate just to see if their tool‑calling loop behaves as expected. The result is slowed iteration, fragile scripts, and a steep learning curve when switching between OpenAI, local LLMs, or mock environments.
A practical solution is to abstract the provider behind a simple interface and ship a deterministic mock implementation that mirrors the real contract. By defining a base Provider class with an async complete method that returns a normalized LLMResponse, you can swap implementations with a single line change—no rewriting of agent logic. The mock provider reproduces the exact decision‑making flow: detecting math expressions, triggering tool calls like calculator or run_python, remembering user‑provided facts, and composing final answers from tool outputs. Because it returns the same data structures (ToolCall, Usage, finish_reason) as the OpenAI‑compatible provider, the agent loop cannot tell the difference, enabling full end‑to‑end testing offline.
To eliminate friction, wrap optional dependency installation in a helper that attempts imports, falls back to pip install, and logs failures silently. Use environment variables (e.g., NANOBOT_API_KEY) to toggle between live and mock modes, and apply nest_asyncio only when needed to avoid event‑loop conflicts in notebooks or scripts. This pattern gives you:
- Zero‑cost experimentation: run the agent without any API key or network access.
- Reliable CI/CD pipelines: deterministic outputs make tests predictable.
- Seamless provider migration: switch from Mock to OpenAI, OpenRouter, Ollama, or any OpenAI‑compatible endpoint by changing the constructor parameters.
- Clean dependency management: automatic installs keep the setup script short and robust.
Adopt this provider‑contract approach and spend your time building features, not fighting setup.