---
title: "Deep Agents"
description: "guardian_agent.deepagents: create_deep_agent, Deep Agents' agent described and routed through the proxy."
source: "Guardian Agent SDK"
---
{/* generated api guardian_agent.deepagents */}

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:

```python
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**](#deepagentscreate_deep_agent) – Deep Agents' `create_deep_agent`, described, and routed through the proxy.

## `deepagents.create_deep_agent`

```python
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.

{/* end generated */}