Quickstart

Run a Claude Agent SDK Python agent behind CopilotKit.

Start with your coding agent

Use this prompt to connect your Claude Agent SDK for Python agent to CopilotKit and verify a working conversation. Your coding agent will follow this guide in your project, or you can work through the manual steps below.

Open your coding agent in your project's folder, or in an empty folder for a new app.

This quickstart gives you two working paths:

  • Start from scratch to scaffold the Claude Agent SDK Python starter app.
  • Use an existing agent to expose your own Claude Agent SDK process over AG-UI and connect it to a React app.

Prerequisites

Before you begin, you'll need the following:

  • An Anthropic API key
  • Python 3.12 or 3.13
  • Node.js 20.9+
  • uv for Python dependency management
  • Your favorite JavaScript package manager

Getting started

Choose your starting point

Run the CLI

npx copilotkit@latest init --framework claude-sdk-python

The starter contains three pieces:

  • agent/main.py - the FastAPI server that serves the agent over AG-UI
  • agent/src/agent.py - the agent: its backend tools and the ClaudeAgentAdapter
  • src/app/api/copilotkit/[[...slug]]/route.ts - the CopilotKit runtime route that proxies to the agent

Configure your environment

Create a .env file in the generated project root:

.env
ANTHROPIC_API_KEY=your_anthropic_api_key
ANTHROPIC_MODEL=claude-opus-4-8

The runtime route defaults to AGENT_URL=http://localhost:8000, which is where the starter's FastAPI agent server listens.

Install dependencies

npm install

Start the development server

npm run dev

This starts both the Next.js app and the Python agent server.

Verify the integration

Open http://localhost:3000 and ask:

Tell me in one sentence what this app can do.

If the chat streams a Claude response, CopilotKit is connected to your Claude Agent SDK Python agent.

Open Inspector and confirm setup

On localhost, click the Inspector button in the corner of the app.

  1. Open Inspect, then Agent. Your agent is listed.
  2. Send a chat message. Open Inspect, then AG-UI Events. Events are moving.
  3. Open Rich Threads. The list is unlocked (Intelligence is on), or locked with Copy setup prompt (Intelligence is off).

More detail: Inspector.

Backend tools and state

The minimal server above is enough for text chat. To support backend tools, shared state snapshots, and richer demos, expose your tool schemas through the Claude SDK MCP bridge and emit AG-UI state events:

Install the Claude Agent SDK packages

uv add claude-agent-sdk ag-ui-claude-sdk ag-ui-protocol anthropic fastapi uvicorn python-dotenv

Bridge Claude Agent SDK to AG-UI

Use ClaudeAgentAdapter from ag_ui_claude_sdk. The adapter receives the AG-UI run input, emits AG-UI events back to CopilotKit, and can expose backend tools through an in-process Claude SDK MCP server.

claude_agent_sdk_adapter.py
async def run_with_claude_agent_sdk(
    input_data: RunAgentInput,
    *,
    system_prompt: str,
    tools: list[dict[str, Any]],
    state: Any,
    model: str,
    execute_tool: ExecuteTool,
    max_turns: int = 10,
) -> AsyncIterator[str]:
    """Run through the official AG-UI Claude adapter and emit SSE chunks."""

    encoder = EventEncoder()
    state_box = {"state": state}
    pending_state_snapshots: list[Any] = []
    sdk_tools = _build_sdk_tools(
        tools,
        execute_tool=execute_tool,
        get_state=lambda: state_box["state"],
        set_state=lambda next_state: _set_state(
            next_state,
            state_box,
            pending_state_snapshots,
        ),
    )

    options: dict[str, Any] = {
        "model": _normalize_claude_agent_sdk_model(model),
        "system_prompt": system_prompt,
        "tools": [],
        "permission_mode": "dontAsk",
        "max_turns": max_turns,
    }

    if sdk_tools:
        options["mcp_servers"] = {
            COPILOTKIT_MCP_SERVER_NAME: create_sdk_mcp_server(
                COPILOTKIT_MCP_SERVER_NAME,
                "1.0.0",
                tools=sdk_tools,
            )
        }
        options["allowed_tools"] = [
            f"{COPILOTKIT_TOOL_PREFIX}{schema['name']}" for schema in tools
        ]

    adapter = ClaudeAgentAdapter(
        name="claude-sdk-python",
        options=options,
    )
    run_input = _with_initial_state(input_data, state)

    async for event in adapter.run(run_input):
        if event.type == EventType.TOOL_CALL_RESULT and pending_state_snapshots:
            yield encoder.encode(
                StateSnapshotEvent(
                    type=EventType.STATE_SNAPSHOT,
                    snapshot=pending_state_snapshots.pop(0),
                )
            )
        yield encoder.encode(event)

How is this guide?