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 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-typescript

The 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 to ClaudeAgentAdapter.
  • src/app/api/copilotkit/[[...slug]]/route.ts - the CopilotKit runtime route. It registers the agent as default and reaches it with HttpAgent.
  • 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 .env

Then add your Anthropic API key to .env:

.env
ANTHROPIC_API_KEY=your_anthropic_api_key

The other values in .env.example are optional:

  • COPILOTKIT_AGENT_MODEL sets the Claude model as anthropic:<model>. The agent runs Anthropic models only.
  • AGENT_URL is the address the runtime route uses to reach the agent. The default is http://localhost:8000, where the starter's agent server listens.

Install dependencies

npm install

The postinstall script also installs the agent's own dependencies in agent/.

Start the development server

npm run dev

This 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.

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

npm install @ag-ui/core @ag-ui/encoder @ag-ui/claude-agent-sdk @anthropic-ai/claude-agent-sdk@^0.2.58 @anthropic-ai/sdk zod

Bridge 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.

claude-agent-sdk-adapter.ts
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,
  });
}
claude-agent-sdk-adapter.ts
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?