> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mirage.strukto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Pydantic AI

> Implement pydantic-ai-backend's SandboxProtocol so Pydantic AI agents can run inside a Mirage workspace.

[Pydantic AI](https://github.com/pydantic/pydantic-ai) agents can use [`pydantic-ai-backend`](https://pypi.org/project/pydantic-ai-backend/)'s `SandboxProtocol` for filesystem, shell, grep, and edit operations. Mirage's `PydanticAIWorkspace` is a drop-in implementation of that protocol and also works with higher-level harnesses such as [pydantic-deepagents](https://github.com/vstorm-co/pydantic-deepagents).

## Install

```bash theme={null}
uv add 'mirage-ai[pydantic-ai]'
```

This pulls in `pydantic-ai-slim[anthropic,openai]>=2.13.0` and `pydantic-ai-backend>=0.2.16`. To use it with [pydantic-deepagents](https://github.com/vstorm-co/pydantic-deepagents):

```bash theme={null}
uv add pydantic-deep
```

## Usage

```python theme={null}
from dataclasses import dataclass

from pydantic_ai import Agent
from pydantic_ai_backends import create_console_toolset

from mirage import MountMode, Workspace
from mirage.agents.pydantic_ai import PydanticAIWorkspace, build_system_prompt
from mirage.resource.ram import RAMResource

ws = Workspace({"/": RAMResource()}, mode=MountMode.WRITE)
backend = PydanticAIWorkspace(ws)


@dataclass
class Deps:
    backend: PydanticAIWorkspace


agent = Agent(
    "openai:gpt-4.1",
    system_prompt=build_system_prompt(
        mount_info={"/": "In-memory filesystem (read/write)"},
    ),
    deps_type=Deps,
    toolsets=[
        create_console_toolset(
            image_support=True,
            document_support=True,
        )
    ],
)

result = agent.run_sync(
    "Create /hello.txt with 'hi' and cat it.",
    deps=Deps(backend=backend),
)
print(result.output)
```

## Exports

| Symbol                | Purpose                                                              |
| --------------------- | -------------------------------------------------------------------- |
| `PydanticAIWorkspace` | `SandboxProtocol` implementation backed by a Mirage workspace.       |
| `build_system_prompt` | Generates a system prompt that describes mounted paths to the model. |

`PydanticAIWorkspace` routes file operations through the Ops layer directly and shell operations through `Workspace.execute()` for full pipe and flag support. Enable `image_support` and `document_support` on the console toolset to pass images and PDFs from any Mirage mount to multimodal models as native `BinaryContent`.

## Examples

* [`examples/python/agents/pydantic_ai/s3_agent.py`](https://github.com/strukto-ai/mirage/blob/main/examples/python/agents/pydantic_ai/s3_agent.py), read-only S3 exploration.
* [`examples/python/agents/pydantic_ai/s3_pdf_agent.py`](https://github.com/strukto-ai/mirage/blob/main/examples/python/agents/pydantic_ai/s3_pdf_agent.py), native PDF input from S3.
* [`examples/python/agents/pydantic_ai/slack_pdf_agent.py`](https://github.com/strukto-ai/mirage/blob/main/examples/python/agents/pydantic_ai/slack_pdf_agent.py), native image and PDF reads from Slack.