DeepAgents Code Agent Server: Production Design, Dynamic Model Switching & Middleware

The DeepAgents Code project separates client and server logic; the server (Agent Server) is the core of a production‑grade AI agent. After a high‑level overview, the article dives into the four essential problems any production agent must address:

Dynamic large‑model integration and switching.

Tool definition, registration, and safe execution.

Persistent session memory across turns.

Orchestrating multiple sub‑agents when a single agent’s capabilities are insufficient.

Model Provider – Dynamic Model Switching

The agent is created with create_deep_agent in agent.py. Although the model argument appears static, runtime switching is achieved in two steps.

Step 1: Pass a model‑swap instruction via the runtime context. The context_schema=CLIContextSchema defines fields such as model, model_params, and effective_model. When agent.stream() is called, a CLIContext instance is built (see app.py) and later forwarded to textual_adapter.py, where the desired model is attached to the request.

context = CLIContext(
    model=self._model_override,
    model_params=self._model_params_override or {},
    ...
)

Step 2: Replace the model at call time via ConfigurableModelMiddleware . The middleware reads the target model from runtime.context, checks compatibility with model_matches_spec, creates a new model instance with create_model() if needed, merges parameters (e.g., temperature, max_tokens), clears incompatible settings when switching providers (e.g., removes cache_control when moving from Anthropic to OpenAI), and updates the system prompt’s “### Model Identity” section.

class ConfigurableModelMiddleware(AgentMiddleware):
    """Swap the model or per‑call settings from `runtime.context`."""
    def wrap_model_call(self, request: ModelRequest, handler: Callable[[ModelRequest], ModelResponse]) -> ModelResponse:
        # read model spec from runtime.context
        # if mismatch, create new model
        # merge model_params
        # clean incompatible config
        # update system prompt
        ...

This design leverages LangChain’s runtime context and middleware to achieve seamless model switching without restarting the session.

Tool Registry – Unified Management of Three Tool Sources

Tools are the “hands” of an agent. DeepAgents Code classifies them into:

Built‑in tools defined in tools.py (e.g., fetch_url, web_search, get_current_thread_id).

MCP tools loaded from remote services via the MCP protocol (implemented in mcp_tools.py).

Middleware‑injected tools automatically added by the DeepAgents SDK (e.g., execute, read_file, write_file, edit_file).

The get_current_thread_id tool is highlighted for its dual role: linking LangSmith traces to a session and enabling external memory tools to associate state with a specific thread.

Sub‑agents – Delegation Mechanism

Sub‑agents are defined in agents_dir/{subagent_name}/AGENTS.md. The main agent loads these definitions and passes them to the subagents parameter of create_deep_agent. Both locally defined markdown files and remotely hosted agents (listed in config.toml as async_subagents) are supported, providing a “local definition + remote reuse” model that balances flexibility and extensibility.

all_subagents: list[SubAgent | CompiledSubAgent | AsyncSubAgent] = [
    *custom_subagents,
    *(async_subagents or []),
]

Middleware Extensions

LangChain 1.0 introduced a powerful middleware system. DeepAgents Code extends it with several specialized middlewares:

LocalContextMiddleware (in local_context.py) runs a Bash script before each model call to collect Git status, project structure, and package manager type, persisting this snapshot in the agent state and appending it to the system prompt.

ResumeStateMiddleware (in resume_state.py) records the token usage and effective model after each call, storing them in a ResumeState extension that is persisted with messages. On resume, it restores _context_tokens and _model_spec for lossless session recovery.

MemoryMiddleware (in memory.py) loads long‑term memory from AGENTS.md files under ~/.deepagents/ or .deepagents/, strips HTML comments, wraps the content in <agent_memory>, and injects it into the system prompt, enabling cross‑session continuity.

SkillsMiddleware (in skills.py) implements progressive disclosure. It scans SKILL.md files from built‑in, user, and project directories, extracts YAML front‑matter (name, description, trigger), and injects a concise skill list into the prompt. Full skill definitions are loaded only when the user explicitly calls /skill_name.

Backend Priority Mechanism (in agent.py) selects one of three backends based on configuration:

Remote sandbox (e.g., ModalSandbox, DaytonaSandbox) when sandbox is set.

Local shell backend ( LocalShellBackend) when enable_shell=True and no sandbox.

Pure filesystem backend ( FilesystemBackend) when enable_shell=False, providing read/write only.

All backends implement BackendProtocol, allowing middleware to remain agnostic to the concrete implementation.

These middleware components together give DeepAgents Code a production‑grade engineering foundation: dynamic model swapping, unified tool handling, sub‑agent orchestration, environment awareness, lossless session resume, long‑term memory, on‑demand skill loading, and flexible execution backends.