Agent Types

Two agent runtimes ship, and the difference between them is not size — it is who runs the tool loop. Both read the same tool registry and answer on the same POST /api/chat.

Choosing between them

	DeepAgent — you run the engine	BaseAgent — your model consumes ours
Tool loop runs	here, in your deployment	in the LLM provider, against /mcp over HTTP
Harness	LangChain create_agent + the deepagents middleware stack	none, on purpose
Virtual filesystem	yes, PostgreSQL-backed	no
Code execution	eval — in-process JavaScript REPL	no
Agent Skills	yes, through SkillsMiddleware	no
Charts	a fenced vis-chart block the client renders	none — the consuming client brings its own
Providers key	PROVIDERS_DEEP	PROVIDERS_BASE
Use it when	this is the default — pick it unless you have a reason not to	you are targeting Claude Desktop, Cursor, ChatGPT Apps or any MCP client

DeepAgent is the workhorse: file reading, computation and multi-step tool use all live there. BaseAgent is deliberately the thinnest possible derivation over the MCP tool surface, so its capability matches exactly what an external MCP client gets: anything BaseAgent cannot do unaided, an outside MCP client cannot do either.

Agent selection per turn

Agents are discovered the same way tools are — by scanning directories at startup.

1. 1
   Each directory in AGENT_DIRS is scanned for .py files subdirectories and names starting with _ are skipped
2. 2
   A class becomes an agent by defining generate_response its name minus a trailing Agent is the agent name — DeepAgent → Deep
3. 3
   If it also defines load_llm_clients, that runs now with PROVIDERS_{NAME} as its input, building one client per provider entry
4. 4
   An agent with zero clients is not offered so leaving PROVIDERS_BASE empty is how you switch BaseAgent off
5. 5
   GET /api/models returns the surviving agent/provider pairs and POST /api/chat takes agent and provider as separate fields

curl http://localhost:18080/api/models

response

{"success":true,"code":0,"msg":"ok","data":["Base/gemini-2.5-flash","Deep/claude-sonnet","Deep/gemini-3.5-flash"]}

The client therefore chooses both halves. Omit provider and DeepAgent falls back to DEFAULT_PROVIDER_DEEP, or to gemini-3.5-flash when that is unset; BaseAgent falls back to gemini-2.5-flash. An agent with zero usable clients is not offered at all, so emptying PROVIDERS_BASE is how you switch BaseAgent off.

DeepAgent

DeepAgent builds a deepagents agent per turn out of four things: the discovered tools, a system prompt, a PostgreSQL-backed filesystem and a middleware stack.

The virtual filesystem

With an authenticated user, the backend is a CompositeBackend of five mounts. The deepagents-native file tools — ls, read_file, write_file, edit_file, glob, grep — operate on it as if it were a disk:

Mount	Scope	Access	Holds
(default)	this session	read/write	scratch space for the turn
/memories/	cross-session	read/write	notes the agent chooses to keep
/uploads/	this session	read-only	the files attached to this request
/library/	cross-session	read-only	the user’s earlier parsed files
/skills/	packaged	read-only	the Agent Skills from SKILL_DIRS — the agent must never edit its own skills

/uploads/ and /library/ are mirrored from the th_files table as pointers — no bytes are copied into PostgreSQL. Parsed text is inlined so grep works; the raw bytes are surfaced multimodally when the model reads the file. An anonymous call gets an in-memory StateBackend instead, so nothing persists.

The middleware stack

Six middlewares wrap a DeepAgent turn, in the order they are applied:

1. 1
   ToolFaultMiddleware Outermost, so a tool that raises is contained instead of ending the turn.
2. 2
   InvalidToolCallRepairMiddleware A tool call whose JSON never parsed is repaired rather than dropped.
3. 3
   ModelCallLimitMiddleware The real per-turn budget: MODEL_CALL_LIMIT model calls (default 50), then the turn ends gracefully. RECURSION_LIMIT is a raw LangGraph ceiling kept only as a backstop.
4. 4
   CodeInterpreterMiddleware From langchain-quickjs: a persistent, in-process JavaScript REPL exposed as eval. If the package is missing the middleware is skipped with a warning and the turn runs without it.
5. 5
   SkillsMiddleware Injects every skill's frontmatter into the prompt at startup and serves the full SKILL.md through the /skills/ mount only when a task calls for it. Skipped for anonymous sessions, which have no mount to read from.
6. 6
   UniversalPromptCachingMiddleware(ttl="5m") Last, so its decision wins. Marks the prompt cacheable on providers that support it and is ignored on those that do not.

Two things deepagents would otherwise contribute are deliberately not present:

• No task subagent. Streaming a subagent run delays every event until it finishes, and here task would only ever be a no-op self-clone. It is disabled through a registered harness profile rather than through DISALLOWED_TOOLS_DEEP.
• No write_todos. deepagents 0.7 dropped TodoListMiddleware from its default stack, and DeepAgent does not add it back.

The delete file tool is also excluded by name: the PostgreSQL filesystem backend does not implement it, so it is not offered.

BaseAgent

BaseAgent has no LangChain agent loop, no middleware and no virtual filesystem. It renders a prompt, hands our MCP server to the provider, and streams the result — the tool loop belongs to the provider.

BaseAgent renders the prompt, hands over /mcp

The provider's agent loop OpenAI Responses · Gemini Interactions

Our MCP tools the same surface an outside client sees

The admission rule: BaseAgent clients speak Responses-style APIs only, because the whole point is handing our MCP server to someone else’s agent loop. A provider that offers only Chat Completions is consumed through DeepAgent’s LangChain stack instead — a local function-call loop here would just duplicate it.

Provider	Class	Default model	Server-side MCP	Stateful
OpenAI Responses	OpenAIResponsesClient	gpt-5-nano	yes	yes
Gemini Interactions	GeminiClient	gemini-2.5-flash	local function fallback	yes
DeepSeek Responses	DeepSeekResponsesClient	deepseek-v4-flash	no — function and server-side web_search only	no
DashScope Responses	DashScopeClient	qwen3.5-flash	no — its MCP accepts server_protocol: "sse", ours is streamable HTTP	yes

Two more consequences worth knowing before you choose it:

• It trims history to the last five user turns by default (user_message_threshold).
• Its provider entries carry no llm_type. The client class is picked from the prefix of the provider key — gemini…, gpt…, deepseek…, qwen…/dashscope…. A key matching no known prefix silently gets no client, and the provider then disappears from /api/models.

Note

PROMPTS_BASE is real: left empty, BaseAgent uses its packaged mirobody/agent/prompts/base.jinja; set a path and that path wins. Unlike PROMPTS_DEEP it is not selectable per request — the provider runs the tool loop, so there is nowhere to branch — and a deployment listing several templates gets the first. GET /api/prompts?agent=base advertises exactly what it resolved.

Charting

The same question produces a different artefact depending on which agent answered.

	DeepAgent	BaseAgent
Produced by	the model writing a fenced vis-chart block of pure-data JSON inline	nothing
Rendered by	the web client, interactively, from the JSON in that block	the consuming MCP client’s own visualization
Server round-trip	none — no tool call, no PNG	n/a

Note

The tool surface does not include chart-rendering tools. Charts are produced by DeepAgent writing a vis-chart data block, which the client renders directly; BaseAgent’s prompt directs the model to use text and tables instead. Historic chart PNGs are still served from the /charts volume.

The tools themselves are documented in Built-in Tools.

Configuring providers

Each agent reads its own PROVIDERS_ key, suffixed with the agent name in upper case:

config.localdb.yaml

PROVIDERS_DEEP:
  gemini-3.5-flash:
    llm_type: google-genai
    api_key: GOOGLE_API_KEY
    model: gemini-3.5-flash
    temperature: 1.0
  claude-sonnet:
    llm_type: openai
    api_key: OPENROUTER_API_KEY
    base_url: https://openrouter.ai/api/v1
    model: anthropic/claude-sonnet-4.6
    temperature: 0.1
  qwen-vl:
    llm_type: openai
    api_key: DASHSCOPE_API_KEY
    base_url: https://dashscope.aliyuncs.com/compatible-mode/v1
    model: qwen-vl-max
    supports_pdf: true
    supports_image: true

The key of each entry is the provider name the client asks for. Inside it:

llm_type string default: openai

Which LangChain integration to initialise — google-genai or openai. Anything reached over an OpenAI-compatible endpoint (OpenRouter, DashScope, Volcengine) is openai plus a base_url.

api_key string

The name of the key that holds the secret — not the secret. See the warning below.

base_url string

Endpoint for OpenAI-compatible providers. A literal URL works; a name that resolves to one in the environment or config is also accepted.

model string required

The upstream model id. An entry without it is skipped at startup with a warning.

temperature number

Passed straight through, as is any other key not listed here — include_thoughts, thinking_level and friends reach the LangChain constructor unchanged.

supports_pdf boolean

Declare only for OpenAI-compatible endpoints, whose capabilities the engine cannot infer. true sends PDFs as a native file block; unset serves them as pre-extracted text.

supports_image boolean

Same, for images.

Caution

api_key holds a key name, not a key value. The loader looks that name up in the environment first and then in the config, so pasting the secret itself leaves the provider broken — and it fails quietly: the entry still appears in /api/models, and the only symptom is Missing GOOGLE_API_KEY. Get API key from provider and set in .env or environment on the first turn that uses it. Put real secrets in your config.{env}.yaml, where values under keys whose name contains _KEY, _TOKEN, _SECRET and friends are encrypted at rest. See Configuration.

api_key: GOOGLE_API_KEY

$GOOGLE_API_KEY, else config key GOOGLE_API_KEY

api_key: sk-abc123…

looked up as a name, found nothing

Prompts

PROMPTS_{NAME} is a list of Jinja2 template paths. Each entry may pin the key the template is registered under with a path@key suffix; without one, the key is the file name minus .jinja:

config.yaml

PROMPTS_DEEP:
  - agent/prompts/deep.jinja

DeepAgent selects a template by the prompt_name sent with the request, falling back to the first one configured. A per-user prompt stored through the user-prompt API takes precedence over both.

Tool visibility

The same two keys as everywhere else, suffixed with the agent name in upper case:

Key	Effect
ALLOWED_TOOLS_{NAME}	whitelist — when set, only these tools are offered
DISALLOWED_TOOLS_{NAME}	blacklist — applied after the whitelist, so it always wins

The shipped config.yaml leaves every one of them empty, which means “all discovered tools”. It also carries ALLOWED_TOOLS_RTC / DISALLOWED_TOOLS_RTC / PROMPTS_RTC placeholders left behind by a removed agent — harmless, and a reminder that the suffix is just an agent name.

Writing your own agent

AGENT_DIRS is scanned the same way MCP_TOOL_DIRS is. It ships with one entry — the packaged mirobody/agent — so add your own directory and list it first:

config.{env}.yaml

AGENT_DIRS:
  - agents            # yours, scanned first
  - mirobody/agent    # the packaged default

The contract is small: one class per agent, an async generator called generate_response, and — if the agent has providers — a load_llm_clients that turns its PROVIDERS_ entry into clients. Subclassing DeepAgent inherits both.

agents/triage_agent.py

from typing import Any, AsyncGenerator

from mirobody.agent.deep_agent import DeepAgent


class TriageAgent(DeepAgent):
    """Registers as agent name "Triage"; configured with PROVIDERS_TRIAGE,
    ALLOWED_TOOLS_TRIAGE, DISALLOWED_TOOLS_TRIAGE and PROMPTS_TRIAGE."""

    async def generate_response(
        self, user_id: str, messages: list[Any], **kwargs
    ) -> AsyncGenerator[dict[str, Any], None]:
        async for event in super().generate_response(user_id, messages, **kwargs):
            yield event

Note

Agents loaded from PRIVATE_AGENT_DIRS instead are registered but kept out of /api/agents and /api/models — usable from your own code, invisible to clients.

Next steps

Tools & Agent Overview

How agents, tools, skills and /mcp fit together

→

Built-in Tools

What every agent can call, parameter by parameter

→

Agent Skills

Teach an agent a procedure without writing code

→

Configuration

Provider keys, prompts, and the three config layers

→