pydantic-acp 0.4.1

ACP adapter for pydantic-ai agents.

pydantic-acp

pydantic-acp adapts pydantic_ai.Agent instances to the ACP agent interface.

Entry Points

• run_acp(...)
• create_acp_agent(...)
• AdapterConfig
• AcpSessionContext
• MemorySessionStore
• FileSessionStore

What It Covers

pydantic-acp includes:

• ACP session lifecycle and replay
• session-local model control
• providers for host-owned models, modes, config options, and plans
• native deferred approval bridging
• projection maps for filesystem diffs and bash previews
• capability bridges for hooks, history processors, prepare-tools, and MCP metadata
• hook introspection and HookProjectionMap
• client-backed filesystem and terminal helpers

Slash commands are available for:

• /model
• /tools
• /hooks
• /mcp-servers

Quick Start

from pydantic_ai import Agent
from pydantic_acp import run_acp

agent = Agent("openai:gpt-5", name="demo-agent")
run_acp(agent=agent)

Configured Runtime

from pathlib import Path

from pydantic_ai import Agent
from pydantic_acp import (
    AdapterConfig,
    FileSessionStore,
    NativeApprovalBridge,
    run_acp,
)

agent = Agent("openai:gpt-5", name="configured-agent")

run_acp(
    agent=agent,
    config=AdapterConfig(
        session_store=FileSessionStore(base_dir=Path(".acp-sessions")),
        approval_bridge=NativeApprovalBridge(enable_persistent_choices=True),
    ),
)

Projection Maps

Filesystem projection:

from pydantic_acp import FileSystemProjectionMap, run_acp

run_acp(
    agent=agent,
    projection_maps=(
        FileSystemProjectionMap(
            default_read_tool="read_file",
            default_write_tool="write_file",
            default_bash_tool="execute",
        ),
    ),
)

Hook projection:

from pydantic_acp import HookProjectionMap, run_acp

run_acp(
    agent=agent,
    projection_maps=(
        HookProjectionMap(
            hidden_event_ids=frozenset({"after_model_request"}),
            event_labels={"before_tool_execute": "Starting Tool"},
        ),
    ),
)

Factories, Providers, And Host Backends

Use agent_factory or AgentSource when the session context should influence agent creation. Use providers when models, modes, config options, or plans belong to the host layer. Use ClientHostContext when tools should talk back to the ACP client's filesystem or terminal.

Examples

See examples/pydantic/README.md for focused SDK examples and the full runnable demo.

Key examples:

• examples/pydantic/static_agent.py
• examples/pydantic/hook_projection.py
• examples/pydantic/my_agent.py

For full workspace documentation, see:

• README.md
• docs/pydantic-acp.md