# Quickstart

> Run a Claude Agent SDK TypeScript agent behind CopilotKit.

## Start with your coding agent [#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.

<PageAgentPrompt />

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 [#prerequisites]

Before you begin, you'll need the following:

- An Anthropic API key
- Node.js 20.9+
- Your favorite package manager

## Getting started [#getting-started]

<Steps>
  <Step>
    ### Choose your starting point [#choose-your-starting-point]

    <TailoredContent className="step" id="agent">
      <TailoredContentOption
        id="starter"
        title="Start from scratch"
        description="Scaffold the canonical Claude Agent SDK TypeScript starter."
      >
        <Step>
          ### Run the CLI [#run-the-cli]

          ```bash
          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
        </Step>

        <Step>
          ### Configure your environment [#configure-your-environment]

          Copy the example file in the generated project root:

          ```bash
          cp .env.example .env
          ```

          Then add your Anthropic API key to `.env`:

          ```plaintext title=".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.
        </Step>

        <Step>
          ### Install dependencies [#install-dependencies]

          <Tabs groupId="package-manager" items={['npm', 'pnpm', 'yarn', 'bun']}>
            <Tab value="npm">
              ```bash
              npm install
              ```
            </Tab>
            <Tab value="pnpm">
              ```bash
              pnpm install
              ```
            </Tab>
            <Tab value="yarn">
              ```bash
              yarn install
              ```
            </Tab>
            <Tab value="bun">
              ```bash
              bun install
              ```
            </Tab>
          </Tabs>

          The `postinstall` script also installs the agent's own dependencies in `agent/`.
        </Step>

        <Step>
          ### Start the development server [#start-the-development-server]

          <Tabs groupId="package-manager" items={['npm', 'pnpm', 'yarn', 'bun']}>
            <Tab value="npm">
              ```bash
              npm run dev
              ```
            </Tab>
            <Tab value="pnpm">
              ```bash
              pnpm dev
              ```
            </Tab>
            <Tab value="yarn">
              ```bash
              yarn dev
              ```
            </Tab>
            <Tab value="bun">
              ```bash
              bun dev
              ```
            </Tab>
          </Tabs>

          This starts the Next.js app on `http://localhost:3000` and the agent server on `http://localhost:8000`.
        </Step>
      </TailoredContentOption>

      <TailoredContentOption
        id="bring-your-own"
        title="Use an existing agent"
        description="I already have a Claude Agent SDK TypeScript agent and want to add CopilotKit."
      >
        <Step>
          ### Install the required packages [#install-the-required-packages]

          Install the Claude Agent SDK adapter, AG-UI event packages, and Express server dependencies for the agent process:

          ```bash
          npm install @anthropic-ai/claude-agent-sdk@^0.2.58 @anthropic-ai/sdk @ag-ui/claude-agent-sdk @ag-ui/core @ag-ui/encoder express dotenv zod
          npm install -D typescript tsx @types/node @types/express
          ```
        </Step>

        <Step>
          ### Configure your agent environment [#configure-your-agent-environment]

          Create a `.env` file for the process that runs your Claude agent:

          ```plaintext title=".env"
          ANTHROPIC_API_KEY=your_anthropic_api_key
          CLAUDE_MODEL=claude-opus-4-8
          AGENT_PORT=8000
          ```
        </Step>

        <Step>
          ### Expose Claude Agent SDK over AG-UI [#expose-claude-agent-sdk-over-ag-ui]

          CopilotKit talks to agents over AG-UI. The small server below receives AG-UI run input, passes it to `ClaudeAgentAdapter`, and streams AG-UI events back to the runtime.

          ```ts title="src/agent-server.ts"
          import express from "express";
          import { randomUUID } from "node:crypto";
          import { EventType, type RunAgentInput } from "@ag-ui/core";
          import { EventEncoder } from "@ag-ui/encoder";
          import { ClaudeAgentAdapter } from "@ag-ui/claude-agent-sdk";
          import dotenv from "dotenv";

          dotenv.config();

          const app = express();
          app.use(express.json({ limit: "10mb" }));

          const agent = new ClaudeAgentAdapter({
            agentId: "claude-sdk-typescript",
            model: process.env.CLAUDE_MODEL ?? "claude-opus-4-8",
            systemPrompt: "You are a helpful assistant embedded in a CopilotKit app.",
            tools: [],
            permissionMode: "dontAsk",
            maxTurns: 10,
          });

          app.post("/", (req, res) => {
            const input = req.body as RunAgentInput;
            const runId = input.runId ?? randomUUID();
            const threadId = input.threadId ?? randomUUID();
            const encoder = new EventEncoder();

            res.setHeader("Content-Type", "text/event-stream");
            res.setHeader("Cache-Control", "no-cache");
            res.setHeader("Connection", "keep-alive");

            agent.run({ ...input, runId, threadId }).subscribe({
              next: (event) => res.write(encoder.encodeSSE(event)),
              error: (error) => {
                const message = error instanceof Error ? error.message : String(error);
                res.write(
                  encoder.encodeSSE({
                    type: EventType.RUN_ERROR,
                    runId,
                    threadId,
                    message,
                  }),
                );
                res.end();
              },
              complete: () => res.end(),
            });
          });

          app.get("/health", (_req, res) => {
            res.json({ status: "ok" });
          });

          const port = Number(process.env.AGENT_PORT ?? 8000);
          app.listen(port, () => {
            console.log(`Claude Agent SDK listening on http://localhost:${port}`);
          });
          ```

          Start the agent server:

          ```bash
          npx tsx src/agent-server.ts
          ```

          In a second terminal, check it. The response is `{"status":"ok"}`:

          ```bash
          curl http://localhost:8000/health
          ```
        </Step>

        <Step>
          ### Create your frontend [#create-your-frontend]

          CopilotKit works with any React app. This example uses Next.js App Router:

          ```bash
          npx create-next-app@latest frontend
          cd frontend
          npm install @copilotkit/runtime @copilotkit/react-core @ag-ui/client@1.0.2
          ```
        </Step>

        <Step>
          ### Add the CopilotKit runtime route [#add-the-copilotkit-runtime-route]

          Create `app/api/copilotkit/route.ts` in your Next.js app. It registers the Claude agent server as an AG-UI `HttpAgent` under the name `default`, the same name the starter uses.

          ```ts title="app/api/copilotkit/route.ts"
          import { HttpAgent } from "@ag-ui/client";
          import {
            CopilotRuntime,
            createCopilotRuntimeHandler,
          } from "@copilotkit/runtime/v2";
          import type { NextRequest } from "next/server";

          const runtime = new CopilotRuntime({
            agents: {
              default: new HttpAgent({
                url: process.env.AGENT_URL ?? "http://localhost:8000",
              }),
            },
          });

          const handler = createCopilotRuntimeHandler({
            runtime,
            basePath: "/api/copilotkit",
            mode: "single-route",
          });

          export const POST = (req: NextRequest) => handler(req);
          ```
        </Step>

        <Step>
          ### Mount CopilotKit in React [#mount-copilotkit-in-react]

          Wrap your app with `CopilotKit` and target the agent name you registered in the runtime route.

          ```tsx title="app/providers.tsx"
          "use client";

          import { CopilotKit } from "@copilotkit/react-core/v2";

          export function Providers({ children }: { children: React.ReactNode }) {
            return (
              <CopilotKit runtimeUrl="/api/copilotkit" agent="default">
                {children}
              </CopilotKit>
            );
          }
          ```

          Render `Providers` in `app/layout.tsx`:

          ```tsx title="app/layout.tsx"
          import { Providers } from "./providers";
          import "@copilotkit/react-core/v2/styles.css";
          import "./globals.css";

          export default function RootLayout({ children }: { children: React.ReactNode }) {
            return (
              <html lang="en">
                <body>
                  <Providers>
                    {children}
                  </Providers>
                </body>
              </html>
            );
          }
          ```

          Not using Next.js? See [React SPA](/claude-sdk-typescript/react-spa), [Vue](/vue), [Angular](/angular), or [React Native](/react-native).

          Add a chat surface:

          ```tsx title="app/page.tsx"
          "use client";

          import { CopilotSidebar } from "@copilotkit/react-core/v2";

          export default function Page() {
            return (
              <main>
                <CopilotSidebar />
              </main>
            );
          }
          ```
        </Step>

        <Step>
          ### Start the UI [#start-the-ui]

          Keep the agent server running, then start the frontend in a second terminal:

          ```bash
          npm run dev
          ```
        </Step>
      </TailoredContentOption>
    </TailoredContent>
  </Step>

  <Step>
    ### Verify the integration [#verify-the-integration]

    Open `http://localhost:3000` and ask:

    ```plaintext
    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.

    <Accordions className="mb-4">
      <Accordion title="Troubleshooting">
        - If the runtime cannot reach the agent, check that the agent server is running on `http://localhost:8000` or set `AGENT_URL` in the frontend.
        - If Claude returns an authentication error, make sure `ANTHROPIC_API_KEY` is available to the agent server process.
        - If a custom tool call stalls, add the backend tool bridge shown below instead of leaving `tools: []`.
      </Accordion>
    </Accordions>
  </Step>

    <Step>
        ### Open Inspector and confirm setup [#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](/claude-sdk-typescript/inspector).
    </Step>

</Steps>

## Backend tools and state [#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:

<Steps>
  <Step>
    ### Install the Claude Agent SDK packages

    ```bash
    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
    ```
  </Step>

  <Step>
    ### 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.

~~~~typescript title="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,
  });
}
~~~~

~~~~typescript title="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(),
    });
  });
}
~~~~

  </Step>
</Steps>
