### Practical AdapterConfig Implementation

Source: https://vcoderun.github.io/acpkit/pydantic-acp/adapter-config

A comprehensive example showing agent configuration, model selection, capability bridges, approval bridges, and session storage setup.

```python
from pathlib import Path

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

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

config = AdapterConfig(
    agent_name="configured-agent",
    agent_title="Configured Agent",
    agent_version="2026.04",
    allow_model_selection=True,
    available_models=[
        AdapterModel(
            model_id="fast",
            name="Fast",
            description="Lower-latency responses.",
            override="openai:gpt-5-mini",
        ),
        AdapterModel(
            model_id="smart",
            name="Smart",
            description="Higher-quality responses.",
            override="openai:gpt-5",
        ),
    ],
    capability_bridges=[ThinkingBridge()],
    approval_bridge=NativeApprovalBridge(enable_persistent_choices=True),
    session_store=FileSessionStore(root=Path(".acp-sessions")),
)

run_acp(agent=agent, config=config)
```

--------------------------------

### Run the LangChain graph example

Source: https://vcoderun.github.io/acpkit/examples/langchain-codex

Execute the example script using uv.

```bash
uv run python -m examples.langchain.codex_graph
```

--------------------------------

### Run via acpkit CLI

Source: https://vcoderun.github.io/acpkit/examples/deepagents

Launch the example through the root CLI to preserve session store, modes, native plans, compatibility bridge, and projections. Requires deepagents to be installed.

```bash
acpkit run examples.langchain.deepagents_graph:acp_agent

```

--------------------------------

### Minimal AdapterConfig example

Source: https://vcoderun.github.io/acpkit/langchain-acp/adapter-config

Shows a minimal AdapterConfig setup with identity, models, modes, session store, capability bridges, and projection maps. Uses FileSessionStore for persistence and DeepAgentsCompatibilityBridge for compatibility.

```python
from acp.schema import SessionMode
from langchain_acp import (
    AdapterConfig,
    AdapterModel,
    DeepAgentsCompatibilityBridge,
    DeepAgentsProjectionMap,
    FileSessionStore,
    StructuredEventProjectionMap,
)

config = AdapterConfig(
    agent_name="workspace-graph",
    available_models=[
        AdapterModel(model_id="fast", name="Fast"),
        AdapterModel(model_id="deep", name="Deep"),
    ],
    available_modes=[
        SessionMode(id="ask", name="Ask"),
        SessionMode(id="agent", name="Agent"),
    ],
    default_model_id="fast",
    default_mode_id="ask",
    session_store=FileSessionStore(root=".acpkit/langchain-sessions"),
    capability_bridges=[DeepAgentsCompatibilityBridge()],
    projection_maps=[DeepAgentsProjectionMap()],
    event_projection_maps=[StructuredEventProjectionMap()],
)

```

--------------------------------

### Use acpremote executable

Source: https://vcoderun.github.io/acpkit/getting-started/installation

Installs the `acpremote` executable. Examples show exposing an ACP server and mirroring a remote WebSocket endpoint.

```bash
acpremote expose --host 0.0.0.0 --port 8080 -- npx @zed-industries/codex-acp
acpremote mirror ws://remote.example.com:8080/acp/ws
```

--------------------------------

### Run the workspace graph example

Source: https://vcoderun.github.io/acpkit/examples/langchain-workspace

Runs the example locally using uv. Requires ~/.codex/auth.json for authentication.

```bash
uv run python -m examples.langchain.workspace_graph

```

--------------------------------

### Run deepagents_graph example

Source: https://vcoderun.github.io/acpkit/examples/deepagents

Run the DeepAgents compatibility example as a Python module.

```bash
uv run python -m examples.langchain.deepagents_graph

```

--------------------------------

### Install CodeMode tools using uv

Source: https://vcoderun.github.io/acpkit/pydantic-acp/harness-capabilities

Installation command for CodeMode tools using uv.

```bash
uv add "pydantic-ai-harness[code-mode]"
```

--------------------------------

### Install codex-auth-helper with LangChain support

Source: https://vcoderun.github.io/acpkit/examples/langchain-codex

Install the helper package using uv or pip.

```bash
uv add "codex-auth-helper[langchain]"
```

```bash
pip install "codex-auth-helper[langchain]"
```

--------------------------------

### Install LangChain ACP adapter

Source: https://vcoderun.github.io/acpkit

Install the root package with the LangChain adapter.

```bash
uv pip install "acpkit[langchain]"
```

--------------------------------

### Install stable v1 with all integrations

Source: https://vcoderun.github.io/acpkit/getting-started/installation

Installs every maintained integration with version constraint >=1.0.0,<2.0.0. Requires matching v1-generation adapter, helper, and transport packages.

```bash
uv add "acpkit[all]>=1.0.0,<2.0.0"
```

```bash
pip install "acpkit[all]>=1.0.0,<2.0.0"
```

--------------------------------

### Run the finance agent example

Source: https://vcoderun.github.io/acpkit/examples/finance

Execute the finance agent module using uv.

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

--------------------------------

### Docs preview command

Source: https://vcoderun.github.io/acpkit/getting-started/installation

Starts a local MkDocs server with the required extras for docs preview.

```bash
uv run --extra docs --extra pydantic --extra langchain --extra codex mkdocs serve --dev-addr 127.0.0.1:8080
```

--------------------------------

### CLI Alternative for Multiple Services

Source: https://vcoderun.github.io/acpkit/examples/remote-hosting

Example of running multiple services and connecting a local client via the root CLI.

```bash
acpkit serve examples.pydantic.finance_agent:acp_agent --host 0.0.0.0 --port 8080
acpkit serve examples.langchain.workspace_graph:acp_agent --host 0.0.0.0 --port 8081
acpkit run --addr ws://127.0.0.1:8080/acp/ws
```

--------------------------------

### Install missing adapter dependencies

Source: https://vcoderun.github.io/acpkit/cli

Commands to install required adapter extras when a MissingAdapterError occurs.

```bash
uv pip install "acpkit[pydantic]"
```

```bash
uv pip install "acpkit[langchain]"
```

--------------------------------

### Run the Session MCP Agent example

Source: https://vcoderun.github.io/acpkit/examples/session-mcp

Command to run the example module. Without `ACP_SESSION_MCP_MODEL`, it uses `TestModel` to avoid requiring credentials.

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

```

--------------------------------

### Verify Session and Permission Flow

Source: https://vcoderun.github.io/acpkit/integration-testing

A concise example demonstrating session creation, permission queuing, and verifying the final agent message output.

```python
session = asyncio.run(harness.new_session(cwd=str(tmp_path)))
harness.queue_permission_selected('allow_once')
response = asyncio.run(harness.prompt_text('Write the workspace note.'))

assert response.stop_reason == 'end_turn'
assert harness.agent_messages(session_id=session.session_id) == ['done']
```

--------------------------------

### Install pydantic-acp with harness support using uv

Source: https://vcoderun.github.io/acpkit/pydantic-acp/harness-capabilities

Production installation command for pydantic-acp with harness support using uv.

```bash
uv add "pydantic-acp[harness]"
```

--------------------------------

### Install Pydantic ACP adapter

Source: https://vcoderun.github.io/acpkit

Install the root package with the Pydantic adapter.

```bash
uv pip install "acpkit[pydantic]"
```

--------------------------------

### Install all integrations with pip

Source: https://vcoderun.github.io/acpkit/releases/acpkit-1.0.0

Installs every maintained integration using pip with the 'all' extra, requiring version >=1.0.0,<2.0.0.

```bash
pip install "acpkit[all]>=1.0.0,<2.0.0"
```

--------------------------------

### Development setup from repo root

Source: https://vcoderun.github.io/acpkit/getting-started/installation

Syncs development dependencies including docs, pydantic, langchain, codex, and remote extras.

```bash
uv sync --extra dev --extra docs --extra pydantic --extra langchain --extra codex --extra remote
```

```bash
pip install -e ".[dev,docs,pydantic,langchain,codex,remote]"
```

--------------------------------

### Complete one-file LangChain ACP example

Source: https://vcoderun.github.io/acpkit/getting-started/langchain-quickstart

Equivalent one-file example combining graph creation and ACP exposure. Runs `run_acp` when executed as the main module.

```python
from langchain.agents import create_agent
from langchain_acp import run_acp

graph = create_agent(
    model="openai:gpt-5",
    tools=[],
    system_prompt="Answer directly and keep responses short.",
)


if __name__ == "__main__":
    run_acp(graph=graph)

```

--------------------------------

### Prepare an AcpProvider with explicit session setup

Source: https://vcoderun.github.io/acpkit/pydantic-acp

Configure an AcpProvider for command-backed or in-process agents, including session mode selection.

```python
from acp.interfaces import Agent as AcpAgent
from pydantic_acp import AcpProvider


async def prepare_provider(acp_agent: AcpAgent) -> AcpProvider:
    provider = AcpProvider(
        acp_agent=acp_agent,
        cwd="/workspace",
        raise_on_empty_turn=True,
    )
    await provider.ensure_session()
    await provider.set_session_mode("review")
    return provider
```

--------------------------------

### Install pre-commit hook

Source: https://vcoderun.github.io/acpkit/testing

Installs the pre-commit hook to ensure lightweight config checks run on every commit.

```shell
uv run pre-commit install
```

--------------------------------

### Configure Mode-aware Tools with MCP Metadata and Thinking

Source: https://vcoderun.github.io/acpkit/bridges

Example demonstrating the integration of ThinkingBridge, PrepareToolsBridge with multiple modes, and McpBridge for server and tool definitions.

```python
from pydantic_acp import (
    AdapterConfig,
    McpBridge,
    McpServerDefinition,
    McpToolDefinition,
    PrepareToolsBridge,
    PrepareToolsMode,
    ThinkingBridge,
)
from pydantic_ai.tools import RunContext, ToolDefinition


def ask_tools(
    ctx: RunContext[None],
    tool_defs: list[ToolDefinition],
) -> list[ToolDefinition]:
    del ctx
    return [tool_def for tool_def in tool_defs if tool_def.name == "mcp_repo_search_paths"]


def agent_tools(
    ctx: RunContext[None],
    tool_defs: list[ToolDefinition],
) -> list[ToolDefinition]:
    del ctx
    return list(tool_defs)


config = AdapterConfig(
    capability_bridges=[
        ThinkingBridge(),
        PrepareToolsBridge(
            default_mode_id="ask",
            modes=[
                PrepareToolsMode(
                    id="ask",
                    name="Ask",
                    description="Read-only inspection mode.",
                    prepare_func=ask_tools,
                ),
                PrepareToolsMode(
                    id="agent",
                    name="Agent",
                    description="Full workspace mode.",
                    prepare_func=agent_tools,
                    plan_tools=True,
                ),
            ],
        ),
        McpBridge(
            servers=[
                McpServerDefinition(
                    server_id="repo",
                    name="Repository",
                    transport="http",
                    tool_prefix="mcp_repo_",
                    description="Repository inspection tools.",
                )
            ],
            tools=[
                McpToolDefinition(
                    tool_name="mcp_repo_search_paths",
                    server_id="repo",
                    kind="search",
                )
            ],
        ),
    ],
)
```

--------------------------------

### Minimal Code Example: Define and Validate a CompatibilityManifest

Source: https://vcoderun.github.io/acpkit/compatibility-matrix-template

Creates a manifest with multiple surface support entries, validates it, and prints the Markdown output.

```python
from acpkit import CompatibilityManifest, SurfaceSupport

manifest = CompatibilityManifest(
    integration_name='workspace-agent',
    adapter='pydantic-acp',
    surfaces={
        'session.load': SurfaceSupport(
            status='implemented',
            owner='adapter',
            mapping='FileSessionStore + load_session',
        ),
        'mode.switch': SurfaceSupport(
            status='partial',
            owner='bridge',
            mapping='PrepareToolsBridge dynamic modes',
            rationale='Only explicitly exposed runtime modes are surfaced.',
        ),
        'hooks.visible': SurfaceSupport(
            status='intentionally_not_used',
            rationale='The runtime keeps the hook seam but does not expose it to ACP clients.',
        ),
        'authenticate': SurfaceSupport(
            status='implemented',
            owner='provider',
            mapping='AcpProvider auth_required recovery',
            rationale='Agent-managed methods are automatic; env and terminal setup stays client-owned.',
        ),
    },
)

manifest.validate()
print(manifest.to_markdown())
```

--------------------------------

### Smallest Valid Example: Define and Validate a CompatibilityManifest

Source: https://vcoderun.github.io/acpkit/compatibility-matrix-template

Creates a minimal manifest with a single surface entry and validates it.

```python
from acpkit import CompatibilityManifest, SurfaceSupport

manifest = CompatibilityManifest(
    integration_name='workspace-agent',
    adapter='pydantic-acp',
    surfaces={
        'session.load': SurfaceSupport(
            status='implemented',
            owner='adapter',
            mapping='FileSessionStore + load_session',
        ),
    },
)

manifest.validate()
```

--------------------------------

### Install root CLI with Pydantic adapter

Source: https://vcoderun.github.io/acpkit/getting-started/installation

Use this path when you want `acpkit run ...` and `acpkit launch ...` for `pydantic_ai.Agent` targets.

```bash
uv add "acpkit[pydantic]"
```

```bash
pip install "acpkit[pydantic]"
```

--------------------------------

### Install CodeMode tools using pip

Source: https://vcoderun.github.io/acpkit/pydantic-acp/harness-capabilities

Installation command for CodeMode tools using pip.

```bash
pip install "pydantic-ai-harness[code-mode]"
```

--------------------------------

### Define ExampleState and Providers

Source: https://vcoderun.github.io/acpkit/providers

This example defines the state management class and several provider classes (ModelsProvider, ModesProvider, ConfigProvider, PlanProvider, ApprovalMetadataProvider) that implement the ACP interface, followed by the initialization of the AdapterConfig.

```python
from dataclasses import dataclass, field

from acp.schema import (
    PlanEntry,
    SessionConfigOptionBoolean,
    SessionMode,
)
from pydantic_acp import (
    AcpSessionContext,
    AdapterConfig,
    AdapterModel,
    ConfigOption,
    ModelSelectionState,
    ModeState,
    RuntimeAgent,
)


@dataclass(slots=True)
class ExampleState:
    config_values: dict[str, dict[str, str | bool]] = field(default_factory=dict)

    def config_for(self, session: AcpSessionContext) -> dict[str, str | bool]:
        return self.config_values.setdefault(session.session_id, {})


@dataclass(slots=True, kw_only=True)
class ModelsProvider:
    state: ExampleState

    def get_model_state(
        self,
        session: AcpSessionContext,
        _agent: RuntimeAgent,
    ) -> ModelSelectionState:
        config = self.state.config_for(session)
        return ModelSelectionState(
            available_models=[
                AdapterModel(
                    model_id="chat",
                    name="Chat",
                    description="Short conversational responses.",
                    override="openai:gpt-5-mini",
                ),
                AdapterModel(
                    model_id="review",
                    name="Review",
                    description="More deliberate review responses.",
                    override="openai:gpt-5",
                ),
            ],
            current_model_id=str(config.get("model_id", "chat")),
        )

    def set_model(
        self,
        session: AcpSessionContext,
        agent: RuntimeAgent,
        model_id: str,
    ) -> ModelSelectionState:
        config = self.state.config_for(session)
        config["model_id"] = model_id
        return self.get_model_state(session, agent)


@dataclass(slots=True, kw_only=True)
class ModesProvider:
    state: ExampleState

    def get_mode_state(
        self,
        session: AcpSessionContext,
        _agent: RuntimeAgent,
    ) -> ModeState:
        config = self.state.config_for(session)
        return ModeState(
            modes=[
                SessionMode(id="chat", name="Chat", description="General conversation."),
                SessionMode(id="review", name="Review", description="Tool-heavy review mode."),
            ],
            current_mode_id=str(config.get("mode_id", "chat")),
        )

    def set_mode(
        self,
        session: AcpSessionContext,
        agent: RuntimeAgent,
        mode_id: str,
    ) -> ModeState:
        config = self.state.config_for(session)
        config["mode_id"] = mode_id
        return self.get_mode_state(session, agent)


@dataclass(slots=True, kw_only=True)
class ConfigProvider:
    state: ExampleState

    def get_config_options(
        self,
        session: AcpSessionContext,
        _agent: RuntimeAgent,
    ) -> list[ConfigOption]:
        config = self.state.config_for(session)
        return [
            SessionConfigOptionBoolean(
                id="stream_enabled",
                name="Streaming",
                category="runtime",
                description="Enable streamed responses when the host supports them.",
                type="boolean",
                current_value=bool(config.get("stream_enabled", False)),
            )
        ]

    def set_config_option(
        self,
        session: AcpSessionContext,
        agent: RuntimeAgent,
        config_id: str,
        value: str | bool,
    ) -> list[ConfigOption] | None:
        if config_id != "stream_enabled" or not isinstance(value, bool):
            return None
        config = self.state.config_for(session)
        config["stream_enabled"] = value
        return self.get_config_options(session, agent)


@dataclass(slots=True, kw_only=True)
class PlanProvider:
    state: ExampleState

    def get_plan(
        self,
        session: AcpSessionContext,
        _agent: RuntimeAgent,
    ) -> list[PlanEntry]:
        config = self.state.config_for(session)
        return [
            PlanEntry(
                content=f"mode:{config.get('mode_id', 'chat')}",
                priority="high",
                status="in_progress",
            )
        ]


@dataclass(slots=True, kw_only=True)
class ApprovalMetadataProvider:
    state: ExampleState

    def get_approval_state(
        self,
        session: AcpSessionContext,
        _agent: RuntimeAgent,
    ) -> dict[str, str | bool]:
        config = self.state.config_for(session)
        return {
            "current_mode_id": str(config.get("mode_id", "chat")),
            "stream_enabled": bool(config.get("stream_enabled", False)),
        }


state = ExampleState()

config = AdapterConfig(
    models_provider=ModelsProvider(state=state),
    modes_provider=ModesProvider(state=state),
    config_options_provider=ConfigProvider(state=state),
    plan_provider=PlanProvider(state=state),
    approval_state_provider=ApprovalMetadataProvider(state=state),
)
```

--------------------------------

### Configure a production-shaped LangChain ACP adapter

Source: https://vcoderun.github.io/acpkit/langchain-acp

This example demonstrates a standard configuration using AdapterConfig, session stores, capability bridges, and projection maps to initialize the ACP runtime.

```python
from langchain.agents import create_agent
from langchain_acp import (
    AdapterConfig,
    AcpSessionContext,
    CompiledAgentGraph,
    DeepAgentsCompatibilityBridge,
    DeepAgentsProjectionMap,
    FileSessionStore,
    HttpRequestProjectionMap,
    StructuredEventProjectionMap,
    run_acp,
)


def graph_from_session(session: AcpSessionContext) -> CompiledAgentGraph:
    model_name = session.session_model_id or "openai:gpt-5-mini"
    return create_agent(
        model=model_name,
        tools=[],
        system_prompt=f"Work inside {session.cwd.name}.",
    )


config = AdapterConfig(
    session_store=FileSessionStore(root=".acpkit/langchain-sessions"),
    capability_bridges=[DeepAgentsCompatibilityBridge()],
    projection_maps=[
        DeepAgentsProjectionMap(),
        HttpRequestProjectionMap(),
    ],
    event_projection_maps=[StructuredEventProjectionMap()],
)

run_acp(graph_factory=graph_from_session, config=config)
```

--------------------------------

### Install langchain-acp[deepagents]

Source: https://vcoderun.github.io/acpkit/examples/deepagents

Install the optional deepagents dependency for langchain-acp using either uv or pip.

```bash
uv add "langchain-acp[deepagents]"

```

```bash
pip install "langchain-acp[deepagents]"

```

--------------------------------

### Run the travel agent example

Source: https://vcoderun.github.io/acpkit/examples/travel

Executes the travel agent module with uv, using the default credential-free TestModel unless ACP_TRAVEL_MODEL (and optionally ACP_TRAVEL_MEDIA_MODEL) are set.

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

--------------------------------

### Install pydantic-acp with harness support using pip

Source: https://vcoderun.github.io/acpkit/pydantic-acp/harness-capabilities

Production installation command for pydantic-acp with harness support using pip.

```bash
pip install "pydantic-acp[harness]"
```

--------------------------------

### Install only one adapter family with uv

Source: https://vcoderun.github.io/acpkit/releases/acpkit-1.0.0

Installs only one adapter family (pydantic or langchain) using uv, requiring version >=1.0.0,<2.0.0.

```bash
uv add "acpkit[pydantic]>=1.0.0,<2.0.0"
uv add "acpkit[langchain]>=1.0.0,<2.0.0"
```

--------------------------------

### Perform Typical Integration Test Workflow

Source: https://vcoderun.github.io/acpkit/integration-testing

Shows the standard usage pattern: creating a harness, queuing permissions, running a prompt, asserting on updates, and verifying session reload behavior.

```python
import asyncio

from pydantic_acp import AdapterConfig, BlackBoxHarness, FileSessionStore

harness = BlackBoxHarness.create(
    agent_factory=build_agent,
    config=AdapterConfig(session_store=FileSessionStore(tmp_path / 'sessions')),
)

session = asyncio.run(harness.new_session(cwd=str(tmp_path)))
harness.queue_permission_selected('allow_once')
response = asyncio.run(harness.prompt_text('Write the workspace note.'))

assert response.stop_reason == 'end_turn'
assert harness.tool_updates(session_id=session.session_id)
assert harness.agent_messages(session_id=session.session_id)

harness.clear_updates()
asyncio.run(harness.load_session(cwd=str(tmp_path), session_id=session.session_id))
assert harness.agent_messages(session_id=session.session_id)
```

--------------------------------

### acpkit run usage examples

Source: https://vcoderun.github.io/acpkit/cli

Examples of using acpkit run with different target forms: a module, a module:attribute, a module with a path, and an external agent with an absolute path.

```bash
acpkit run finance_agent
acpkit run finance_agent:agent
acpkit run app.agents.demo:agent -p ./examples
acpkit run external_agent -p /absolute/path/to/agents

```

--------------------------------

### Install root CLI with LangChain adapter

Source: https://vcoderun.github.io/acpkit/getting-started/installation

Use this path when you want `acpkit run ...` and `acpkit launch ...` for LangChain, LangGraph, or DeepAgents targets.

```bash
uv add "acpkit[langchain]"
```

```bash
pip install "acpkit[langchain]"
```

--------------------------------

### launch_command function

Source: https://vcoderun.github.io/acpkit/api/acpkit

Launches a Toad ACP session using uvx. Requires uvx to be installed; otherwise raises AcpKitError with installation instructions. Returns the subprocess return code.

```python
def launch_command(command: str) -> int:
    normalized_command = command.strip()
    if not normalized_command:
        raise TargetResolutionError("Launch command cannot be empty.")
    launch_command = [
        "uvx",
        "--python",
        "3.14",
        "--from",
        "batrachian-toad",
        "toad",
        "acp",
        normalized_command,
    ]
    try:
        completed = subprocess.run(launch_command, check=False)
    except FileNotFoundError as exc:
        raise AcpKitError(
            "`uvx` is required to launch Toad ACP sessions. "
            'Install it with: `uv pip install "acpkit[launch]"`.'
        ) from exc
    return completed.returncode
```

--------------------------------

### serve_stdio_command(command_options, *, host='127.0.0.1', port=0, mount_path='/acp', bearer_token=None, options=None, supported_agent_families=())

Source: https://vcoderun.github.io/acpkit/api/acpremote

Starts a WebSocket server that serves a command over the ACP protocol. It accepts command options and optional server configuration, and returns a Server object.

```APIDOC
## serve_stdio_command(command_options, *, host='127.0.0.1', port=0, mount_path='/acp', bearer_token=None, options=None, supported_agent_families=())

### Description
Starts a WebSocket server that serves a command over the ACP protocol. It accepts command options and optional server configuration, and returns a Server object.

### Signature
async def serve_stdio_command(command_options: CommandOptions, *, host: str = "127.0.0.1", port: int = 0, mount_path: str = "/acp", bearer_token: str | None = None, options: TransportOptions | None = None, supported_agent_families: tuple[str, ...] = ()) -> Server

### Parameters
- **command_options** (CommandOptions) - Required - Options for the command to be served.
- **host** (str) - Optional - The host interface to bind the server to. Defaults to "127.0.0.1".
- **port** (int) - Optional - The port to bind the server to. Defaults to 0 (auto-assign).
- **mount_path** (str) - Optional - The URL path to mount the ACP server on. Defaults to "/acp".
- **bearer_token** (str | None) - Optional - Bearer token for authentication. Defaults to None.
- **options** (TransportOptions | None) - Optional - Transport options for the server.
- **supported_agent_families** (tuple[str, ...]) - Optional - Tuple of supported agent family identifiers. Defaults to ().

### Returns
- **Server** - The started server instance.
```

--------------------------------

### Install langchain-acp adapter directly

Source: https://vcoderun.github.io/acpkit/getting-started/installation

Use when you only need the Python adapter API for LangChain, LangGraph, or DeepAgents runtimes. Minimum versions: `langchain>=1.3.11`, `langgraph>=1.2.7`, and `deepagents>=0.6.12` when the optional extra is installed.

```bash
uv add langchain-acp
```

```bash
pip install langchain-acp
```

--------------------------------

### Required local state: ~/.codex/auth.json

Source: https://vcoderun.github.io/acpkit/examples/deepagents

Required local state file for the example.

```text
~/.codex/auth.json

```

--------------------------------

### Smallest LangChain path

Source: https://vcoderun.github.io/acpkit

A minimal example of running a LangChain agent with the ACP adapter.

```python
from langchain.agents import create_agent
from langchain_acp import run_acp

graph = create_agent(model="openai:gpt-5", tools=[])

run_acp(graph=graph)
```

--------------------------------

### Configure Adapter Prompt Capabilities

Source: https://vcoderun.github.io/acpkit/langchain-acp

Use AdapterConfig and AdapterPromptCapabilities to explicitly enable or disable specific media and context capabilities.

```python
from langchain_acp import AdapterConfig, AdapterPromptCapabilities

config = AdapterConfig(
    prompt_capabilities=AdapterPromptCapabilities(
        audio=False,
        image=False,
        embedded_context=True,
    )
)
```

--------------------------------

### Smallest Pydantic path

Source: https://vcoderun.github.io/acpkit

A minimal example of running a Pydantic AI agent with the ACP adapter.

```python
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)
```

--------------------------------

### Initialize FileSystemProjectionMap

Source: https://vcoderun.github.io/acpkit/host-backends

Configures a projection map for file and shell-related tools, enabling specific rendering behaviors like diff-like previews for read tools and file diffs for write tools.

```python
from pydantic_acp import FileSystemProjectionMap

projection = FileSystemProjectionMap(
    read_tool_names=frozenset({"mcp_repo_read_file", "mcp_host_read_workspace_file"}),
    write_tool_names=frozenset({"mcp_host_write_workspace_file"}),
    bash_tool_names=frozenset({"mcp_host_run_command"}),
)
```

--------------------------------

### Complete one-file ACP integration

Source: https://vcoderun.github.io/acpkit/getting-started/pydantic-quickstart

Complete one-file example that defines an agent and runs it through ACP with run_acp.

```python
from pydantic_ai import Agent
from pydantic_acp import run_acp

agent = Agent(
    "openai:gpt-5",
    name="demo-agent",
    instructions="Answer directly and keep responses short.",
)


@agent.tool_plain
def describe_project() -> str:
    """Return a short summary of the current project."""

    return "This is a demo ACP-enabled project."


if __name__ == "__main__":
    run_acp(agent=agent)

```

--------------------------------

### Implementing ACP Provider Interfaces

Source: https://vcoderun.github.io/acpkit/langchain-acp/providers

This example demonstrates how to implement various provider classes (ModelsProvider, ModesProvider, ConfigProvider, and PlanProvider) that interact with a shared HostState to manage session-specific data.

```python
from dataclasses import dataclass, field

from acp.schema import (
    PlanEntry,
    SessionConfigSelectOption,
    SessionConfigOptionSelect,
    SessionMode,
)
from langchain_acp import (
    AcpSessionContext,
    AdapterModel,
    ConfigOption,
    ModelSelectionState,
    ModeState,
)


@dataclass(slots=True)
class HostState:
    values: dict[str, dict[str, str]] = field(default_factory=dict)

    def config_for(self, session: AcpSessionContext) -> dict[str, str]:
        return self.values.setdefault(session.session_id, {})


@dataclass(slots=True)
class ModelsProvider:
    state: HostState

    def get_model_state(self, session: AcpSessionContext) -> ModelSelectionState:
        config = self.state.config_for(session)
        return ModelSelectionState(
            available_models=[
                AdapterModel(model_id="fast", name="Fast"),
                AdapterModel(model_id="deep", name="Deep"),
            ],
            current_model_id=config.get("model_id", "fast"),
        )

    def set_model(self, session: AcpSessionContext, model_id: str) -> ModelSelectionState:
        self.state.config_for(session)["model_id"] = model_id
        return self.get_model_state(session)


@dataclass(slots=True)
class ModesProvider:
    state: HostState

    def get_mode_state(self, session: AcpSessionContext) -> ModeState:
        config = self.state.config_for(session)
        return ModeState(
            modes=[
                SessionMode(id="ask", name="Ask"),
                SessionMode(id="agent", name="Agent"),
            ],
            current_mode_id=config.get("mode_id", "ask"),
        )

    def set_mode(self, session: AcpSessionContext, mode_id: str) -> ModeState:
        self.state.config_for(session)["mode_id"] = mode_id
        return self.get_mode_state(session)


@dataclass(slots=True)
class ConfigProvider:
    state: HostState

    def get_config_options(self, session: AcpSessionContext) -> list[ConfigOption]:
        config = self.state.config_for(session)
        return [
            SessionConfigOptionSelect(
                type="select",
                id="team",
                name="Team",
                category="runtime",
                description="Which team context to use for this session.",
                current_value=config.get("team", "general"),
                options=[
                    SessionConfigSelectOption(value="general", name="General"),
                    SessionConfigSelectOption(value="research", name="Research"),
                ],
            )
        ]

    def set_config_option(
        self,
        session: AcpSessionContext,
        option_id: str,
        value: str,
    ) -> list[ConfigOption]:
        self.state.config_for(session)[option_id] = value
        return self.get_config_options(session)


@dataclass(slots=True)
class PlanProvider:
    state: HostState

    def get_plan(self, session: AcpSessionContext) -> list[PlanEntry]:
        config = self.state.config_for(session)
        return [
            PlanEntry(
                content=f"Audit workspace for team {config.get('team', 'general')}",
                priority="high",
                status="in_progress",
            )
        ]
```

--------------------------------

### Define ACP Prompt Blocks

Source: https://vcoderun.github.io/acpkit/langchain-acp/prompt-resources

Example showing the instantiation of TextContentBlock, ResourceContentBlock, and EmbeddedResourceContentBlock for use in a prompt.

```python
from acp.schema import EmbeddedResourceContentBlock, ResourceContentBlock, TextContentBlock

prompt = [
    TextContentBlock(text="Summarize the attached file."),
    ResourceContentBlock(uri="file:///workspace/notes.md", title="notes.md"),
    EmbeddedResourceContentBlock(
        text="Use this excerpt as source material.",
    ),
]
```