# pydantic-acp Examples

These maintained examples are executable ACP agents, not isolated snippets.
They use bounded workspaces, explicit projections, and persistent local session
state.

## Setup

From the repository root:

```bash
uv sync --extra dev --extra pydantic
```

For the harness example:

```bash
uv sync --extra dev --extra pydantic --extra codex
```

## Finance Agent

The finance example demonstrates mode-aware tool preparation, native structured
plans, approval-gated writes, persisted plan snapshots, and file projections.

Run offline with the deterministic Pydantic AI `TestModel`:

```bash
uv run python -m examples.pydantic.finance_agent
```

Use a real Pydantic AI model:

```bash
ACP_FINANCE_MODEL="openai:gpt-5.4-mini" \
uv run python -m examples.pydantic.finance_agent
```

The agent reads and writes only under `agent_demos/finance-agent/` in the server
working directory. The `trade` mode exposes the write tool, and every write still
requires ACP approval.

## Travel Agent

The travel example projects Pydantic AI hooks, handles image/audio-aware model
selection, and requires approval for trip-file writes:

```bash
ACP_TRAVEL_MODEL="openai:gpt-5.4-mini" \
ACP_TRAVEL_MEDIA_MODEL="openai:gpt-5.4" \
uv run python -m examples.pydantic.travel_agent
```

Without `ACP_TRAVEL_MODEL`, the example uses `TestModel` for an offline startup
check. Files stay inside `agent_demos/travel-agent/`.

## Harness Agent

The harness example uses real `pydantic-ai-harness` filesystem and shell
capabilities. Code mode is opt-in:

```bash
ACP_HARNESS_MODEL="openrouter:google/gemini-3-flash-preview" \
uv run python -m examples.pydantic.mock_harness_agent
```

```bash
ACP_HARNESS_CODEX_MODEL="gpt-5.4" \
uv run python -m examples.pydantic.mock_harness_agent --codemode
```

The shell bridge blocks destructive and network-oriented commands, disables
interactive processes, bounds runtime and output, and confines work to
`agent_demos/harness-agent/`. `--codemode` is the only path that enables
the code-mode bridge.

## Session MCP Agent

The session MCP example keeps MCP server choice client-owned. The ACP client
passes `session/new.mcpServers`; `SessionMcpBridge` converts those payloads into
Pydantic AI `MCPToolset` capabilities for that session:

```bash
uv run python -m examples.pydantic.session_mcp_agent
```

Use a real model when you want the model to call attached MCP tools:

```bash
ACP_SESSION_MCP_MODEL="openai:gpt-5.4-mini" \
uv run python -m examples.pydantic.session_mcp_agent
```

Example client payload shape:

```json
{
  "mcpServers": [
    {
      "name": "repo",
      "type": "http",
      "url": "https://repo.example/mcp",
      "headers": [{"name": "Authorization", "value": "Bearer ..."}]
    },
    {
      "name": "local-docs",
      "command": "python",
      "args": ["docs_mcp_server.py"],
      "env": [{"name": "DOCS_ROOT", "value": "agent_demos/docs"}]
    }
  ]
}
```

Without `SessionMcpBridge`, those payloads are still stored and visible through
`/mcp-servers`, but they are not connected as runnable Pydantic AI tools.

## Session Storage

All examples use `FileSessionStore` under `agent_demos/acp-sessions/`. Override
the parent directory when needed:

```bash
ACP_EXAMPLE_SESSION_DIR="/var/lib/acpkit/sessions" \
uv run python -m examples.pydantic.finance_agent
```

This file store is suitable for one process. Replace it with an
application-owned store before running multiple replicas.

## Production Boundaries

- Keep model credentials in environment variables or a secret manager.
- Treat approval callbacks as authorization boundaries, not UI decoration.
- Place remote ACP hosting behind TLS and authentication.
- Narrow filesystem and shell policies further for the deployed workload.

Detailed walkthroughs are available in the
[examples documentation](https://vcoderun.github.io/acpkit/examples/).
