Skip to content

ACP Kit

ACP adapters for production Python agents

Expose Pydantic AI through ACP without lying about the runtime.

ACP Kit keeps models, modes, plans, approvals, MCP metadata, host tools, and session state aligned with what your agent can actually support.

Read the quickstart Explore the workspace agent

ACP Kit is a Python SDK and CLI for exposing agent runtimes through ACP.

Today the primary production surface is pydantic-acp: an adapter that lets you keep writing normal pydantic_ai.Agent code while exposing ACP-native session state, plans, approvals, slash commands, MCP metadata, and host-backed tooling.

pydantic-acp is designed for truthful ACP exposure: if the runtime cannot really support a model picker, mode switch, plan state, approval flow, or MCP surface, the adapter does not pretend that it can.

Three ideas drive the SDK:

  • truthful ACP exposure instead of optimistic UI surface
  • host-owned state through explicit providers and bridges
  • runnable examples that map directly to maintained code in examples/pydantic/

Package Map

Package Purpose Start here
acpkit CLI target resolution, launch helpers, adapter dispatch If you want acpkit run ... or acpkit launch ...
pydantic-acp ACP adapter for pydantic_ai.Agent If you are exposing agents through ACP
codex-auth-helper Codex auth and Responses model factory If you want Codex-backed models in Pydantic AI

What ACP Kit Covers

ACP Kit is not a new agent framework. It sits at the boundary between an existing runtime and ACP clients.

That boundary includes:

  • session creation, loading, forking, replay, and close
  • session-local model and mode state
  • ACP config options and slash commands
  • native plan state and provider-backed plan state
  • approval workflows and remembered policy metadata
  • MCP server metadata and tool classification
  • host-backed filesystem and terminal helpers
  • projection of reads, writes, and shell commands into ACP-friendly updates

Quickstart

Install the root package with the Pydantic adapter:

uv pip install "acpkit[pydantic]"

Build a normal Pydantic AI agent and expose it:

from pydantic_ai import Agent
from pydantic_acp import run_acp

agent = Agent(
    "openai:gpt-5",
    name="weather-agent",
    instructions="Answer briefly and ask for clarification when location is missing.",
)


@agent.tool_plain
def lookup_weather(city: str) -> str:
    """Return a canned weather response for demos."""

    return f"Weather in {city}: sunny"


run_acp(agent=agent)

From there you can layer in:

A Good Reading Order

New to ACP Kit

Start with Installation, then Quickstart, then the minimal example.

Building a real product integration

Read Pydantic ACP Overview, Providers, Bridges, and the workspace agent showcase.

Why This Adapter Feels Different

Most ACP adapters can stream text. The hard part is preserving the rest of the runtime honestly.

pydantic-acp is designed around that harder requirement:

  • if a session supports switching models, the adapter exposes model selection
  • if a session does not, the adapter does not fake a model picker
  • if a plan exists, the ACP plan state is updated and can be resumed
  • if a tool call needs approval, ACP permission semantics are preserved
  • if the host owns mode state, plan persistence, or config options, that ownership stays explicit

That design keeps the adapter predictable for clients and maintainable for hosts.