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 runs in a coding agent on your computer.
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+
uvfor Python dependency management- Your favorite JavaScript package manager
Getting started
Choose your starting point
Run the CLI
npx copilotkit@latest init --framework claude-sdk-pythonThe starter contains three pieces:
agent/main.py- the FastAPI server that serves the agent over AG-UIagent/src/agent.py- the agent: its backend tools and theClaudeAgentAdaptersrc/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:
ANTHROPIC_API_KEY=your_anthropic_api_key
ANTHROPIC_MODEL=claude-opus-4-8The runtime route defaults to AGENT_URL=http://localhost:8000, which is where the starter's FastAPI agent server listens.
Install dependencies
npm installStart the development server
npm run devThis 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.
- If the runtime cannot reach the agent, check that the FastAPI server is running on
http://localhost:8000or setAGENT_URLin the frontend. - If Claude returns an authentication error, make sure
ANTHROPIC_API_KEYis available to the Python process. - If a custom tool call stalls, add the backend tool bridge shown below instead of leaving
"tools": [].
Open Inspector and confirm setup
On localhost, click the Inspector button in the corner of the app.
- Open Inspect, then Agent. Your agent is listed.
- Send a chat message. Open Inspect, then AG-UI Events. Events are moving.
- 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-dotenvBridge 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.
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?