> ## 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

> Give Pydantic AI runs a Mirage session as their workspace, so every file and shell tool runs in Mirage.

[Pydantic AI](https://github.com/pydantic/pydantic-ai) gives every run a [workspace](https://ai.pydantic.dev/workspace/): the environment its tools reach through `ctx.workspace`. Mirage's `MirageWorkspace` capability supplies a Mirage session as that workspace, so file and shell tools, such as [`pydantic-ai-backend`](https://pypi.org/project/pydantic-ai-backend/)'s `ConsoleCapability`, read, write and run commands across every mount.

## Install

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

The extra brings Pydantic AI and the console tools without a model provider; add the provider your agent uses (`openai`, `anthropic`, ...).

## Usage

```python theme={null}
import asyncio

from pydantic_ai import Agent
from pydantic_ai_backends import PERMISSIVE_RULESET, ConsoleCapability

from mirage import MountMode, Workspace
from mirage.agents.pydantic_ai import MirageWorkspace, build_system_prompt
from mirage.vfs.ram import RAMVFS

ws = Workspace({"/": RAMVFS()}, mode=MountMode.WRITE)


async def main() -> None:
    agent = Agent(
        "openai:gpt-4.1",
        system_prompt=await build_system_prompt(
            mount_info={"/": "In-memory filesystem (read/write)"},
        ),
        capabilities=[
            MirageWorkspace(ws),
            ConsoleCapability(permissions=PERMISSIVE_RULESET),
        ],
    )
    result = await agent.run("Create /hello.txt with 'hi' and cat it.")
    print(result.output)


asyncio.run(main())
```

`ConsoleCapability`'s default ruleset asks before every write and command. Mirage already judges each call through the session's mount modes and profile, so the example allows them in the console and leaves the policy to Mirage.

## Exports

| Symbol | Purpose |
| - | - |
| `MirageWorkspace` | Capability that gives runs a Mirage session as their workspace. |
| `MirageWorkspaceBackend` | The workspace backend itself, for code that builds one directly. |
| `build_system_prompt` | Generates a system prompt that describes mounted paths to the model. |

`MirageWorkspace(ws, session_id="agent")` acts as that session, so its profile judges every call. Commands run in Mirage's shell, each in a clone of the session at its working directory, as a subshell does: a `cd` or an `export` in one command does not reach the next. Files go through the session's op facade, and symlinks resolve through the namespace. The run's `WorkspaceRef` names the session; a ref in message history that names any other session is declined.

The backend passes Pydantic AI's workspace conformance suite, except the rules that need POSIX processes (`mkfifo`) or mode bits: Mirage's permissions are the session profile, not `chmod`.

## 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.