Quickstart
Run a Claude Agent SDK TypeScript agent behind CopilotKit.
Start with your coding agent
Use this prompt to connect your Claude Agent SDK for TypeScript 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 full Claude Agent SDK TypeScript showcase.
- 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
- Node.js 20.9+
- Your favorite package manager
Getting started
Choose your starting point
Run the CLI
npx copilotkit@latest init --framework claude-sdk-typescriptThe starter contains these pieces:
agent/src/server.ts- the AG-UI server for the agent. It listens on port 8000.agent/src/agent.ts- the agent. It passes the system prompt and the backend tools toClaudeAgentAdapter.src/app/api/copilotkit/[[...slug]]/route.ts- the CopilotKit runtime route. It registers the agent asdefaultand reaches it withHttpAgent.src/app/page.tsx- the starter UI to inspect first
Configure your environment
Copy the example file in the generated project root:
cp .env.example .envThen add your Anthropic API key to .env:
ANTHROPIC_API_KEY=your_anthropic_api_keyThe other values in .env.example are optional:
COPILOTKIT_AGENT_MODELsets the Claude model asanthropic:<model>. The agent runs Anthropic models only.AGENT_URLis the address the runtime route uses to reach the agent. The default ishttp://localhost:8000, where the starter's agent server listens.
Install dependencies
npm installThe postinstall script also installs the agent's own dependencies in agent/.
Start the development server
npm run devThis starts the Next.js app on http://localhost:3000 and the agent server on http://localhost:8000.
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 TypeScript agent.
- If the runtime cannot reach the agent, check that the agent 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 agent server 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
npm install @ag-ui/core @ag-ui/encoder @ag-ui/claude-agent-sdk @anthropic-ai/claude-agent-sdk@^0.2.58 @anthropic-ai/sdk zodBridge Claude Agent SDK to AG-UI
Use ClaudeAgentAdapter from @ag-ui/claude-agent-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.
function createClaudeAgentAdapter({
toolSchemas,
emit,
getState,
setState,
executeTool,
model,
systemPrompt,
}: {
toolSchemas: Anthropic.Tool[];
emit: Emit;
getState: () => Record<string, unknown>;
setState: (state: Record<string, unknown>) => void;
executeTool: ExecuteTool;
model: string;
systemPrompt: string;
}) {
const backendToolServer = buildBackendToolServer({
toolSchemas,
emit,
getState,
setState,
executeTool,
});
return new ClaudeAgentAdapter({
agentId: "claude-sdk-typescript",
model: normalizeClaudeAgentSdkModel(model),
systemPrompt,
tools: [],
mcpServers: backendToolServer.mcpServers,
allowedTools: backendToolServer.allowedTools,
permissionMode: "dontAsk",
maxTurns: 10,
});
}export async function runWithClaudeAgentSdk({
input,
emit,
runId,
threadId,
systemPrompt,
toolSchemas,
initialState,
model,
executeTool,
forwardedHeaders,
}: {
input: RunAgentInput;
emit: Emit;
runId: string;
threadId: string;
systemPrompt: string;
toolSchemas: Anthropic.Tool[];
initialState: Record<string, unknown>;
model: string;
executeTool: ExecuteTool;
forwardedHeaders?: Record<string, string>;
}): Promise<void> {
let state = { ...initialState };
const pendingStateSnapshots: Record<string, unknown>[] = [];
const adapter = createClaudeAgentAdapter({
toolSchemas,
emit,
getState: () => state,
setState: (nextState) => {
state = nextState;
pendingStateSnapshots.push(state);
},
executeTool,
systemPrompt,
model,
});
if (forwardedHeaders && Object.keys(forwardedHeaders).length > 0) {
adapter.headers = forwardedHeaders;
}
const runInput: RunAgentInput = {
...input,
runId,
threadId,
state: input.state ?? initialState,
};
await new Promise<void>((resolve) => {
adapter.run(runInput).subscribe({
next: (event) => {
if (event.type === EventType.TOOL_CALL_RESULT) {
const snapshot = pendingStateSnapshots.shift();
if (snapshot) {
emit({ type: EventType.STATE_SNAPSHOT, snapshot });
}
}
emit(event);
},
error: (error) => {
const message =
error instanceof Error ? error.stack || error.message : String(error);
emit({ type: EventType.RUN_ERROR, runId, threadId, message });
resolve();
},
complete: () => resolve(),
});
});
}How is this guide?