Pydantic AI

Pydantic AI gives every run a 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’s ConsoleCapability, read, write and run commands across every mount.

Install

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

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, read-only S3 exploration.
examples/python/agents/pydantic_ai/s3_pdf_agent.py, native PDF input from S3.
examples/python/agents/pydantic_ai/slack_pdf_agent.py, native image and PDF reads from Slack.

Getting Started

Access

AI Agents

VFS

CLIs

Watch

Runtimes

Install

Usage

Exports

Examples

​Install

​Usage

​Exports

​Examples

Install

Usage

Exports

Examples