BotCircuits has dropped an open-source agent framework that takes a fundamentally different approach to multi-step AI automation. Rather than letting an LLM drive everything—which leads to the famous "deviation" problem where models wander off-task or burn through tokens chasing tangents—botcircuits-agent splits responsibilities between two layers: LLMs handle per-step reasoning and tool calls, while a deterministic state machine controls overall flow.

The Core Innovation

The architecture separates concerns in a way that's been missing from most agent frameworks. When you define a workflow as a JSON file under .botcircuits/workflows/, you're not just writing prompts—you're defining a finite state machine with explicit transitions. Each step can be an "agentAction" that invokes the LLM for context-specific reasoning, but branching logic gets compiled into typed conditions (is, >=, contains) that the engine evaluates without calling the model again. That's the token savings right there: your conditional logic runs deterministic code instead of spinning up another completion. The setup experience reflects this dual nature. You configure provider and model through an interactive wizard (supports Anthropic Claude, OpenAI GPT models, and Google Gemini), but once running, workflows become tools the model can invoke by name—meaning it decides when to use a scripted workflow versus handling something ad-hoc. The /workflow slash command lets you author these from natural language: describe what you want, get a preview, confirm, and it's immediately callable without restart.

Tools and Skills

Built-in tools cover filesystem operations (read_file, write_file, edit_file), shell execution with argv parsing (no dangerous shell expansion), regex/glob search, TODO management, plan_and_confirm gates for human approval, and persistent memory. Every gated action pauses for y/N confirmation unless you run in --auto mode or configure per-tool settings.json overrides. You can disable tools entirely by setting them to null—useful for locked-down deployments. Skills extend this with reusable instruction folders containing a SKILL.md file that defines the skill's purpose (used by the model to decide when to invoke it) and optional allowed-tools restrictions. Drop a skills/ folder into your project or .botcircuits/skills/, reference it via /skills, and you've got repeatable patterns like "how we answer support questions" without polluting your system prompt.

External Integration

MCP (Model Context Protocol) servers integrate through mcp.json configuration at user/project/local layers. Add filesystem tools with npx @modelcontextprotocol/server-filesystem, wire up GitHub Copilot for repo operations, or connect custom servers—all discovered automatically across CLI sessions and gateway requests. The local mode works with every provider including Gemini; hosted mode (where the provider runs the server) is Anthropic/OpenAI only. The Message Gateway extends this into a FastAPI service that routes WhatsApp, Slack Socket Mode, generic webhooks, and cron jobs through the same agent and conversation store. Each channel gets independent session history keyed by {channel}:{external_chat_id}. Cron jobs accept standard 5-field expressions in UTC and can deliver results to Slack channels or log them—perfect for daily standups or hourly health checks without external schedulers.

Key Takeaways

  • Hybrid architecture (LLM reasoning + deterministic state machine) directly targets the deviation problem plaguing autonomous agents
  • Workflow compilation step transforms natural-language conditions into typed operators, eliminating LLM calls for simple branching logic
  • Multi-layer configuration system (user/project/local) balances shared settings with personal overrides and gitignored secrets
  • MCP integration and built-in tools provide extensibility without vendor lock-in across Anthropic, OpenAI, and Gemini providers

The Bottom Line

This is the architecture I've been waiting to see—finally someone acknowledged that trusting LLMs to manage their own control flow is expensive and unreliable. BotCircuits doesn't fight the model's strengths; it delegates reasoning while keeping execution predictable. If you're building production agents today, this hybrid approach is worth serious evaluation over pure prompt-based orchestration.