281 Agent 2f63f722

# Agent API

## create_deep_agent

::: pydantic_deep.agent.create_deep_agent
    options:
      show_source: false

### Signature

```python
def create_deep_agent(
    model: str | None = None,
    instructions: str | None = None,
    tools: Sequence[Tool[DeepAgentDeps] | Any] | None = None,
    toolsets: Sequence[AbstractToolset[DeepAgentDeps]] | None = None,
    subagents: list[SubAgentConfig] | None = None,
    skills: list[Skill] | None = None,
    skill_directories: list[SkillDirectory] | None = None,
    backend: BackendProtocol | None = None,
    include_todo: bool = True,
    include_filesystem: bool = True,
    include_subagents: bool = True,
    include_skills: bool = True,
    include_general_purpose_subagent: bool = True,
    include_execute: bool | None = None,
    interrupt_on: dict[str, bool] | None = None,
    output_type: OutputSpec[OutputDataT] | None = None,
    history_processors: Sequence[HistoryProcessor[DeepAgentDeps]] | None = None,
    **agent_kwargs: Any,
) -> Agent[DeepAgentDeps, OutputDataT] | Agent[DeepAgentDeps, str]
```

### Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `model` | `str \| None` | `"openai:gpt-4.1"` | LLM model identifier |
| `instructions` | `str \| None` | Default instructions | System prompt for the agent |
| `tools` | `Sequence[Tool \| Any] \| None` | `None` | Additional custom tools |
| `toolsets` | `Sequence[AbstractToolset] \| None` | `None` | Additional toolsets |
| `subagents` | `list[SubAgentConfig] \| None` | `None` | Subagent configurations |
| `skills` | `list[Skill] \| None` | `None` | Pre-loaded skills |
| `skill_directories` | `list[SkillDirectory] \| None` | `None` | Directories to discover skills |
| `backend` | `BackendProtocol \| None` | `StateBackend()` | File storage backend |
| `include_todo` | `bool` | `True` | Include TodoToolset |
| `include_filesystem` | `bool` | `True` | Include Console Toolset |
| `include_subagents` | `bool` | `True` | Include SubAgentToolset |
| `include_skills` | `bool` | `True` | Include SkillsToolset |
| `include_general_purpose_subagent` | `bool` | `True` | Include general-purpose subagent |
| `include_execute` | `bool \| None` | `None` | Include execute tool. Auto-detected from backend type if None |
| `interrupt_on` | `dict[str, bool] \| None` | `None` | Tools requiring approval |
| `output_type` | `OutputSpec \| None` | `None` | Pydantic model for structured output |
| `history_processors` | `Sequence[HistoryProcessor] \| None` | `None` | History processors (e.g., summarization) |
| `**agent_kwargs` | `Any` | - | Additional Agent constructor args |

### Returns

`Agent[DeepAgentDeps, str]` or `Agent[DeepAgentDeps, OutputDataT]` - Configured Pydantic AI agent.

When `output_type` is provided, returns an agent typed with the output model.

### Example

```python
from pydantic_deep import create_deep_agent, SubAgentConfig

agent = create_deep_agent(
    model="openai:gpt-4.1",
    instructions="You are a coding assistant.",
    subagents=[
        SubAgentConfig(
            name="reviewer",
            description="Reviews code",
            instructions="Review code for issues.",
        ),
    ],
    skill_directories=[
        {"path": "~/.pydantic-deep/skills", "recursive": True},
    ],
    interrupt_on={"execute": True},
)
```

---

## create_default_deps

::: pydantic_deep.agent.create_default_deps
    options:
      show_source: false

### Signature

```python
def create_default_deps(
    backend: BackendProtocol | None = None,
) -> DeepAgentDeps
```

### Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `backend` | `BackendProtocol \| None` | `StateBackend()` | File storage backend |

### Returns

`DeepAgentDeps` - Configured dependencies instance.

### Example

```python
from pydantic_deep import create_default_deps
from pydantic_ai_backends import LocalBackend

# With default StateBackend
deps = create_default_deps()

# With custom backend
deps = create_default_deps(backend=LocalBackend("/workspace"))
```

---

## DeepAgentDeps

::: pydantic_deep.deps.DeepAgentDeps
    options:
      show_source: false

### Definition

```python
@dataclass
class DeepAgentDeps:
    backend: BackendProtocol = field(default_factory=StateBackend)
    files: dict[str, FileData] = field(default_factory=dict)
    todos: list[Todo] = field(default_factory=list)
    subagents: dict[str, Any] = field(default_factory=dict)
```

### Attributes

| Attribute | Type | Description |
|-----------|------|-------------|
| `backend` | `BackendProtocol` | File storage backend |
| `files` | `dict[str, FileData]` | In-memory file cache |
| `todos` | `list[Todo]` | Task list |
| `subagents` | `dict[str, Any]` | Pre-configured subagent instances |

### Methods

#### get_todo_prompt

```python
def get_todo_prompt(self) -> str
```

Generate system prompt section for current todos.

#### get_files_summary

```python
def get_files_summary(self) -> str
```

Generate summary of files in memory.

#### get_subagents_summary

```python
def get_subagents_summary(self) -> str
```

Generate summary of available subagents.

#### clone_for_subagent

```python
def clone_for_subagent(self) -> DeepAgentDeps
```

Create isolated dependencies for a subagent.

- Same backend (shared)
- Empty todos (isolated)
- Empty subagents (no nested delegation)
- Same files (shared reference)

### Example

```python
from pydantic_deep import DeepAgentDeps, StateBackend, Todo

deps = DeepAgentDeps(
    backend=StateBackend(),
    todos=[
        Todo(
            content="Review code",
            status="pending",
            active_form="Reviewing code",
        ),
    ],
)

# Access todo prompt
print(deps.get_todo_prompt())

# Clone for subagent
subagent_deps = deps.clone_for_subagent()
assert subagent_deps.todos == []  # Isolated
assert subagent_deps.backend is deps.backend  # Shared
```