Deep Agents

Deep Agents’ create_deep_agent, as an agent that signs its own requests.

Change one import: create_deep_agent takes the same arguments as deepagents.create_deep_agent, plus the agent’s name. It describes the agent Deep Agents builds, routes its models (and each sub-agent’s) through the proxy, and returns Deep Agents’ agent, unchanged:

from guardian_agent.deepagents import create_deep_agent

desk = create_deep_agent(
    model=ChatAnthropic(model="claude-sonnet-5"),
    tools=[search_notes],
    system_prompt="You research incidents.",
    subagents=[
        {"name": "critic", "description": "Checks findings.", "system_prompt": "..."},
    ],
    name="desk",
)

Needs deepagents, and Python 3.11 or later: install the deepagents extra.

Functions:

• create_deep_agent – Deep Agents’ create_deep_agent, described, and routed through the proxy.

deepagents.create_deep_agent

create_deep_agent(model: str | BaseChatModel | None = None, tools: Sequence[BaseTool | Callable[..., Any] | dict[str, Any]] | None = None, *, name: str, system_prompt: str | SystemMessage | None = None, middleware: Sequence[AgentMiddleware[Any, Any]] = (), subagents: Sequence[DeepSubAgent | CompiledSubAgent | Mapping[str, Any]] | None = None, skills: list[str] | None = None, memory: list[str] | None = None, permissions: list[FilesystemPermission] | None = None, backend: BackendProtocol | None = None, interrupt_on: dict[str, bool | InterruptOnConfig] | None = None, response_format: ResponseFormat[Any] | type[Any] | dict[str, Any] | None = None, state_schema: type[Any] | None = None, context_schema: type[Any] | None = None, checkpointer: bool | BaseCheckpointSaver[Any] | None = None, store: BaseStore | None = None, debug: bool = False, cache: BaseCache[Any] | None = None, guardian: Guardian | None = None, description: str | None = None, version: str | None = None, exclude: Sequence[str] = ()) -> CompiledStateGraph[AgentState[Any], Any, InputAgentState, OutputAgentState[Any]]

Deep Agents’ create_deep_agent, described, and routed through the proxy.

The definition describes the agent Deep Agents builds, not only the arguments: the model its harness profile settles on, the filesystem and task tools, the summarization model, and every middleware it adds, as guardian_agent.langchain.create_agent records them. Each sub-agent, the general-purpose one Deep Agents adds included, is a full definition in subAgents. Its calls are signed as the agent and name the sub-agent (X-Viper-Subagent).

Parameters:

• model (str | BaseChatModel | None) – A chat model, or a model name Deep Agents resolves.
• tools (Sequence[BaseTool | Callable[..., Any] | dict[str, Any]] | None) – Tools, as Deep Agents takes them.
• name (str) – The agent’s name, as enrolled with viper agent add.
• system_prompt (str | SystemMessage | None) – The system prompt.
• middleware (Sequence[AgentMiddleware[Any, Any]]) – LangChain middleware, as Deep Agents takes it.
• subagents (Sequence[SubAgent | CompiledSubAgent | Mapping[str, Any]] | None) – Sub-agents, as Deep Agents takes them: declarative ones.
• skills (list[str] | None) – Skill sources, as Deep Agents takes them, on a FilesystemBackend(virtual_mode=True). Each skill is read when the agent is made, stored on the proxy and recorded by its files’ CID; the agent reads it as it was then.
• memory (list[str] | None) – Memory sources. One whose writes permissions denies is read, stored and recorded as skills are; the rest, which the agent writes as it runs, is recorded by where it lives and whose it is.
• permissions (list[FilesystemPermission] | None) – Filesystem permissions, as Deep Agents takes them.
• backend (BackendProtocol | None) – Deep Agents’ StateBackend (its default), a StoreBackend, a FilesystemBackend(virtual_mode=True), or a CompositeBackend of them. It’s recorded by its type and settings, never a filesystem’s root directory; what it holds is the agent’s to read and write as it runs.
• interrupt_on (dict[str, bool | InterruptOnConfig] | None) – Tools that need a person’s approval.
• response_format (ResponseFormat[Any] | type[Any] | dict[str, Any] | None) – A structured response format.
• state_schema (type[Any] | None) – As Deep Agents takes it, passed on; not recorded.
• context_schema (type[Any] | None) – As Deep Agents takes it, passed on; not recorded.
• checkpointer (bool | BaseCheckpointSaver[Any] | None) – As Deep Agents takes it, passed on; not recorded.
• store (BaseStore | None) – As Deep Agents takes it, passed on; not recorded.
• debug (bool) – As Deep Agents takes it, passed on; not recorded.
• cache (BaseCache[Any] | None) – As Deep Agents takes it, passed on; not recorded.
• guardian (Guardian | None) – The connection to the proxy; ga.Guardian(), from VIPER_PROXY_URL, by default.
• description (str | None) – What the agent is for.
• version (str | None) – Your own label for this version of the agent.
• exclude (Sequence[str]) – JSON Pointers to leave out of the definition, as for guardian_agent.Definition; a sub-agent’s fields are under /subAgents/<n>, sub-agents in order by name.

Returns:

• CompiledStateGraph[AgentState[Any], Any, InputAgentState, OutputAgentState[Any]] – Deep Agents’ compiled agent; guardian_agent.langchain.agent_of() gives the SDK’s guardian_agent.Agent.

Raises:

• TypeError – Skills, or memory the agent can’t change, on a backend that can’t be read when the agent is made; memory the agent writes on a backend of your own that changes how Deep Agents routes or keeps files; a SkillsMiddleware or MemoryMiddleware of your own; a backend that runs commands (a sandbox), a FilesystemBackend with virtual_mode=False or rooted at the filesystem’s root or above the home directory, a backend of another kind, a CompositeBackend whose routes were changed after it was made, RubricMiddleware, a CompiledSubAgent, a forked or an async sub-agent was given, for the agent or a sub-agent, or a harness profile adds one; or a model, or middleware’s, can’t be routed.
• CollectionInvalid – A skill or memory source is missing, holds a file the proxy refuses, leaves its filesystem’s root (..), or is spelled so a composite routes it elsewhere than its plain spelling; or memory is inside a skills source but in no skill.
• CollectionTooLarge – A skill or memory file is over the proxy’s limits.
• ValueError – A model name can’t be built into a chat model; a model sends a setting no definition can record, or middleware holds one JSON can’t carry and exclude doesn’t leave out; a sub-agent’s name isn’t one a definition takes (lowercase letters, digits, ., _ and -); or no guardian was given and VIPER_PROXY_URL isn’t set.
• RuntimeError – Deep Agents built the agent differently when asked twice, or in a way this SDK doesn’t know, such as reading other skills or memory than it was given.
• ModelNotRoutedThroughProxy – A model is aimed somewhere other than the proxy or its provider’s API.
• DefinitionError – The definition is invalid or holds a credential.

Each call is checked before it’s sent, as for create_agent. A task call that would build a sub-agent while the agent runs (for a per-call response schema) is refused, since it couldn’t be routed.