# Copilot SDK - Full Documentation

> Open-source SDK for building AI assistants with App Context Awareness.

---

## Deploy
URL: https://copilot-sdk.yourgpt.ai/docs/deploy
Description: Deploy your Copilot backend to any platform

Your Copilot backend uses standard Web APIs (`fetch`, `Response`, `ReadableStream`), so the **same code runs everywhere** — Vercel, Cloudflare, Deno, AWS, or your own servers.

<Cards>
  <Card title="Vercel" href="#vercel" />
  <Card title="Cloudflare Workers" href="#cloudflare-workers" />
  <Card title="Deno Deploy" href="#deno-deploy" />
  <Card title="AWS Lambda" href="#aws-lambda" />
  <Card title="Express / Node.js" href="#express--nodejs" />
  <Card title="Docker" href="#docker" />
</Cards>

---

## Vercel

Deploy to Vercel with Next.js. Supports both Serverless and Edge runtimes.

<Tabs items={['Serverless (Default)', 'Edge Runtime']}>
  <Tab value="Serverless (Default)">
    ```ts title="app/api/chat/route.ts"
    import { createRuntime } from '@yourgpt/llm-sdk';
    import { createOpenAI } from '@yourgpt/llm-sdk/openai';

    const runtime = createRuntime({
      provider: createOpenAI({ apiKey: process.env.OPENAI_API_KEY }),
      model: 'gpt-4o',
      systemPrompt: 'You are a helpful assistant.',
    });

    export async function POST(req: Request) {
      const body = await req.json();
      return runtime.stream(body).toResponse();
    }
    ```
  </Tab>
  <Tab value="Edge Runtime">
    Edge functions have faster cold starts (~25ms vs ~250ms) and run closer to users.

    ```ts title="app/api/chat/route.ts"
    import { createRuntime } from '@yourgpt/llm-sdk';
    import { createOpenAI } from '@yourgpt/llm-sdk/openai';

    export const runtime = 'edge'; // Enable Edge Runtime

    const rt = createRuntime({
      provider: createOpenAI({ apiKey: process.env.OPENAI_API_KEY }),
      model: 'gpt-4o',
      systemPrompt: 'You are a helpful assistant.',
    });

    export async function POST(req: Request) {
      const body = await req.json();
      return rt.stream(body).toResponse();
    }
    ```

    <Callout type="info">
    Edge functions have a 30-second execution limit. For long-running agent loops, use Serverless.
    </Callout>
  </Tab>
</Tabs>

### Non-Streaming

```ts title="app/api/chat/route.ts"
export async function POST(req: Request) {
  const body = await req.json();
  const result = await runtime.chat(body);
  return Response.json(result);
}
```

### Deploy

```bash
npm i -g vercel
vercel
```

Set your environment variable in the Vercel dashboard or CLI:

```bash
vercel env add OPENAI_API_KEY
```

---

## Cloudflare Workers

Deploy to Cloudflare's edge network with Workers. Runs in 300+ locations worldwide.

<Tabs items={['Streaming', 'Non-Streaming']}>
  <Tab value="Streaming">
    ```ts title="src/index.ts"
    import { createRuntime, createHonoApp } from '@yourgpt/llm-sdk';
    import { createOpenAI } from '@yourgpt/llm-sdk/openai';

    export interface Env {
      OPENAI_API_KEY: string;
    }

    export default {
      async fetch(request: Request, env: Env): Promise<Response> {
        const runtime = createRuntime({
          provider: createOpenAI({ apiKey: env.OPENAI_API_KEY }),
          model: 'gpt-4o',
          systemPrompt: 'You are a helpful assistant.',
        });

        return createHonoApp(runtime).fetch(request, env);
      },
    };
    ```
  </Tab>
  <Tab value="Non-Streaming">
    ```ts title="src/index.ts"
    import { createRuntime } from '@yourgpt/llm-sdk';
    import { createOpenAI } from '@yourgpt/llm-sdk/openai';

    export interface Env {
      OPENAI_API_KEY: string;
    }

    export default {
      async fetch(request: Request, env: Env): Promise<Response> {
        const runtime = createRuntime({
          provider: createOpenAI({ apiKey: env.OPENAI_API_KEY }),
          model: 'gpt-4o',
          systemPrompt: 'You are a helpful assistant.',
        });

        if (request.method !== 'POST') {
          return new Response('Method not allowed', { status: 405 });
        }

        const body = await request.json();
        const result = await runtime.chat(body);
        return Response.json(result);
      },
    };
    ```
  </Tab>
</Tabs>

### Configuration

```toml title="wrangler.toml"
name = "my-copilot-api"
main = "src/index.ts"
compatibility_date = "2024-01-01"
compatibility_flags = ["nodejs_compat"]
```

### Deploy

```bash
npm i -g wrangler

# Add your API key as a secret
wrangler secret put OPENAI_API_KEY

# Deploy
wrangler deploy
```

<Callout>
Your API will be available at `https://my-copilot-api.<your-subdomain>.workers.dev`
</Callout>

---

## Deno Deploy

Deploy to Deno's global edge network with zero configuration.

<Tabs items={['Streaming', 'Non-Streaming']}>
  <Tab value="Streaming">
    ```ts title="main.ts"
    import { createRuntime, createHonoApp } from '@yourgpt/llm-sdk';
    import { createOpenAI } from '@yourgpt/llm-sdk/openai';

    const runtime = createRuntime({
      provider: createOpenAI({ apiKey: Deno.env.get('OPENAI_API_KEY') }),
      model: 'gpt-4o',
      systemPrompt: 'You are a helpful assistant.',
    });

    Deno.serve(createHonoApp(runtime).fetch);
    ```
  </Tab>
  <Tab value="Non-Streaming">
    ```ts title="main.ts"
    import { createRuntime } from '@yourgpt/llm-sdk';
    import { createOpenAI } from '@yourgpt/llm-sdk/openai';

    const runtime = createRuntime({
      provider: createOpenAI({ apiKey: Deno.env.get('OPENAI_API_KEY') }),
      model: 'gpt-4o',
      systemPrompt: 'You are a helpful assistant.',
    });

    Deno.serve(async (req: Request) => {
      if (req.method !== 'POST') {
        return new Response('Method not allowed', { status: 405 });
      }

      const body = await req.json();
      const result = await runtime.chat(body);
      return Response.json(result);
    });
    ```
  </Tab>
</Tabs>

### Deploy

```bash
# Install Deno Deploy CLI
deno install -Arf jsr:@deno/deployctl

# Deploy
deployctl deploy --project=my-copilot main.ts
```

Set environment variables in the Deno Deploy dashboard.

---

## AWS Lambda

Deploy to AWS Lambda using SST, Serverless Framework, or AWS CDK.

<Tabs items={['SST', 'Serverless Framework']}>
  <Tab value="SST">
    ```ts title="packages/functions/src/chat.ts"
    import { createRuntime } from '@yourgpt/llm-sdk';
    import { createOpenAI } from '@yourgpt/llm-sdk/openai';
    import { Resource } from 'sst';

    const runtime = createRuntime({
      provider: createOpenAI({ apiKey: Resource.OpenAIApiKey.value }),
      model: 'gpt-4o',
      systemPrompt: 'You are a helpful assistant.',
    });

    export async function handler(event: any) {
      const body = JSON.parse(event.body);

      // Non-streaming (Lambda default)
      const result = await runtime.chat(body);

      return {
        statusCode: 200,
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(result),
      };
    }
    ```

    ```ts title="sst.config.ts"
    export default $config({
      app(input) {
        return { name: 'my-copilot', region: 'us-east-1' };
      },
      async run() {
        const api = new sst.aws.Function('Chat', {
          handler: 'packages/functions/src/chat.handler',
          url: true,
        });

        return { url: api.url };
      },
    });
    ```
  </Tab>
  <Tab value="Serverless Framework">
    ```ts title="handler.ts"
    import { createRuntime } from '@yourgpt/llm-sdk';
    import { createOpenAI } from '@yourgpt/llm-sdk/openai';
    import type { APIGatewayProxyHandler } from 'aws-lambda';

    const runtime = createRuntime({
      provider: createOpenAI({ apiKey: process.env.OPENAI_API_KEY }),
      model: 'gpt-4o',
      systemPrompt: 'You are a helpful assistant.',
    });

    export const chat: APIGatewayProxyHandler = async (event) => {
      const body = JSON.parse(event.body || '{}');
      const result = await runtime.chat(body);

      return {
        statusCode: 200,
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(result),
      };
    };
    ```

    ```yaml title="serverless.yml"
    service: my-copilot

    provider:
      name: aws
      runtime: nodejs20.x
      environment:
        OPENAI_API_KEY: ${env:OPENAI_API_KEY}

    functions:
      chat:
        handler: handler.chat
        events:
          - http:
              path: /chat
              method: post
    ```
  </Tab>
</Tabs>

### Streaming on Lambda

<Callout type="warn">
AWS Lambda requires **Function URL with streaming** for SSE responses. Standard API Gateway does not support streaming.
</Callout>

```ts title="packages/functions/src/chat-stream.ts"

const runtime = createRuntime({
  provider: createOpenAI({ apiKey: process.env.OPENAI_API_KEY }),
  model: 'gpt-4o',
});

export const handler = streamHandle(createHonoApp(runtime));
```

### Deploy

```bash
# SST
npx sst deploy

# Serverless
serverless deploy
```

---

## Express / Node.js

Deploy to any Node.js hosting (Railway, Render, Fly.io, DigitalOcean, etc.).

<Tabs items={['Streaming', 'Non-Streaming', 'Both']}>
  <Tab value="Streaming">
    ```ts title="server.ts"
    import express from 'express';
    import { createRuntime } from '@yourgpt/llm-sdk';
    import { createOpenAI } from '@yourgpt/llm-sdk/openai';

    const app = express();
    app.use(express.json());

    const runtime = createRuntime({
      provider: createOpenAI({ apiKey: process.env.OPENAI_API_KEY }),
      model: 'gpt-4o',
      systemPrompt: 'You are a helpful assistant.',
    });

    app.post('/api/chat', async (req, res) => {
      await runtime.stream(req.body).pipeToResponse(res);
    });

    app.listen(3000, () => {
      console.log('Server running on http://localhost:3000');
    });
    ```
  </Tab>
  <Tab value="Non-Streaming">
    ```ts title="server.ts"
    import express from 'express';
    import { createRuntime } from '@yourgpt/llm-sdk';
    import { createOpenAI } from '@yourgpt/llm-sdk/openai';

    const app = express();
    app.use(express.json());

    const runtime = createRuntime({
      provider: createOpenAI({ apiKey: process.env.OPENAI_API_KEY }),
      model: 'gpt-4o',
      systemPrompt: 'You are a helpful assistant.',
    });

    app.post('/api/chat', async (req, res) => {
      const result = await runtime.chat(req.body);
      res.json(result);
    });

    app.listen(3000, () => {
      console.log('Server running on http://localhost:3000');
    });
    ```
  </Tab>
  <Tab value="Both">
    ```ts title="server.ts"
    import express from 'express';
    import { createRuntime } from '@yourgpt/llm-sdk';
    import { createOpenAI } from '@yourgpt/llm-sdk/openai';

    const app = express();
    app.use(express.json());

    const runtime = createRuntime({
      provider: createOpenAI({ apiKey: process.env.OPENAI_API_KEY }),
      model: 'gpt-4o',
      systemPrompt: 'You are a helpful assistant.',
    });

    // Streaming endpoint
    app.post('/api/chat/stream', async (req, res) => {
      await runtime.stream(req.body).pipeToResponse(res);
    });

    // Non-streaming endpoint
    app.post('/api/chat', async (req, res) => {
      const result = await runtime.chat(req.body);
      res.json(result);
    });

    app.listen(3000, () => {
      console.log('Server running on http://localhost:3000');
    });
    ```
  </Tab>
</Tabs>

### Deploy to Popular Platforms

<Accordions type="single">
  <Accordion title="Railway" id="railway">
    ```bash
    npm i -g @railway/cli
    railway login
    railway init
    railway up
    ```

    Set `OPENAI_API_KEY` in Railway dashboard → Variables.
  </Accordion>
  <Accordion title="Render" id="render">
    1. Push to GitHub
    2. Create new **Web Service** on Render
    3. Set build command: `npm install && npm run build`
    4. Set start command: `npm start`
    5. Add `OPENAI_API_KEY` in Environment
  </Accordion>
  <Accordion title="Fly.io" id="flyio">
    ```bash
    npm i -g flyctl
    fly launch
    fly secrets set OPENAI_API_KEY=sk-...
    fly deploy
    ```
  </Accordion>
</Accordions>

---

## Docker

Self-host your Copilot backend with Docker.

<Tabs items={['Streaming', 'Non-Streaming']}>
  <Tab value="Streaming">
    ```ts title="server.ts"
    import { serve } from '@hono/node-server';
    import { createRuntime, createHonoApp } from '@yourgpt/llm-sdk';
    import { createOpenAI } from '@yourgpt/llm-sdk/openai';

    const runtime = createRuntime({
      provider: createOpenAI({ apiKey: process.env.OPENAI_API_KEY }),
      model: 'gpt-4o',
      systemPrompt: 'You are a helpful assistant.',
    });

    const port = Number(process.env.PORT) || 3000;

    serve({ fetch: createHonoApp(runtime).fetch, port }, (info) => {
      console.log(`Server running on http://localhost:${info.port}`);
    });
    ```
  </Tab>
  <Tab value="Non-Streaming">
    ```ts title="server.ts"
    import { serve } from '@hono/node-server';
    import { Hono } from 'hono';
    import { createRuntime } from '@yourgpt/llm-sdk';
    import { createOpenAI } from '@yourgpt/llm-sdk/openai';

    const runtime = createRuntime({
      provider: createOpenAI({ apiKey: process.env.OPENAI_API_KEY }),
      model: 'gpt-4o',
      systemPrompt: 'You are a helpful assistant.',
    });

    const app = new Hono();

    app.post('/api/chat', async (c) => {
      const body = await c.req.json();
      const result = await runtime.chat(body);
      return c.json(result);
    });

    const port = Number(process.env.PORT) || 3000;
    serve({ fetch: app.fetch, port });
    ```
  </Tab>
</Tabs>

### Dockerfile

```dockerfile title="Dockerfile"
FROM node:20-slim AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM node:20-slim
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/package.json ./

ENV NODE_ENV=production
EXPOSE 3000

CMD ["node", "dist/server.js"]
```

### Docker Compose

```yaml title="docker-compose.yml"
services:
  copilot:
    build: .
    ports:
      - "3000:3000"
    environment:
      - OPENAI_API_KEY=${OPENAI_API_KEY}
    restart: unless-stopped
```

### Run

```bash
# Build and run
docker compose up -d

# Or without compose
docker build -t my-copilot .
docker run -p 3000:3000 -e OPENAI_API_KEY=sk-... my-copilot
```

---

## Bun

Deploy with Bun for faster startup and better performance.

```ts title="server.ts"

const runtime = createRuntime({
  provider: createOpenAI({ apiKey: Bun.env.OPENAI_API_KEY }),
  model: 'gpt-4o',
  systemPrompt: 'You are a helpful assistant.',
});

const app = createHonoApp(runtime);

export default {
  port: 3000,
  fetch: app.fetch,
};
```

### Run

```bash
bun run server.ts
```

---

## Connect Frontend

Point your Copilot SDK frontend to your deployed API:

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


export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <CopilotProvider
      runtimeUrl="https://your-api.example.com/api/chat"
      // For non-streaming:
      // streaming={false}
    >
      {children}
    </CopilotProvider>
  );
}
```

| Mode | Server Method | CopilotProvider |
|------|---------------|-----------------|
| Streaming | `.stream(body).toResponse()` | `streaming={true}` (default) |
| Non-streaming | `await runtime.chat(body)` | `streaming={false}` |

---

## CORS

If your frontend and backend are on different domains, add CORS headers:

<Tabs items={['Next.js', 'Hono', 'Express']}>
  <Tab value="Next.js">
    ```ts title="app/api/chat/route.ts"
    const corsHeaders = {
      'Access-Control-Allow-Origin': '*',
      'Access-Control-Allow-Methods': 'POST, OPTIONS',
      'Access-Control-Allow-Headers': 'Content-Type',
    };

    export async function OPTIONS() {
      return new Response(null, { headers: corsHeaders });
    }

    export async function POST(req: Request) {
      const body = await req.json();
      const response = runtime.stream(body).toResponse();

      // Add CORS headers
      Object.entries(corsHeaders).forEach(([key, value]) => {
        response.headers.set(key, value);
      });

      return response;
    }
    ```
  </Tab>
  <Tab value="Hono">
    ```ts
    import { cors } from 'hono/cors';

    const app = createHonoApp(runtime);
    app.use('*', cors());
    ```
  </Tab>
  <Tab value="Express">
    ```ts
    import cors from 'cors';

    app.use(cors());
    ```
  </Tab>
</Tabs>

---

## Next Steps

- [Server Setup](/docs/server) — Full runtime configuration and options
- [Tools](/docs/tools) — Add function calling to your Copilot
- [Providers](/docs/providers) — Configure different LLM providers

---

## Examples
URL: https://copilot-sdk.yourgpt.ai/docs/examples
Description: Real-world Copilot SDK implementations

<ExamplesShowcase />

---

## Generative UI
URL: https://copilot-sdk.yourgpt.ai/docs/generative-ui
Description: Render rich React components from AI tool results — per-tool custom renderers or AI-driven built-in components

Instead of showing raw JSON or plain text from tool calls, render interactive UI directly inside the chat — from your own branded React components per tool, to fully AI-generated dashboards, charts, and layouts running in a sandboxed iframe.

---

## Two Approaches

| | `toolRenderers` | `useGenerativeUI` (experimental) |
|---|---|---|
| **What it does** | Your React component renders per tool result | AI writes full HTML + Tailwind + Chart.js, runs in a sandboxed iframe — or picks a typed renderer (table, stat, card, chart) |
| **Who decides the UI** | You — one renderer per tool | The AI — generates or selects based on the data |
| **Setup** | Pass `toolRenderers` to `<CopilotChat>` | One `useGenerativeUI()` call + backend `generativeUITool()` |
| **Best for** | Domain-specific, branded components | Dashboards, charts, tables, any data layout you haven't pre-built |
| **Customization** | Full control | Override any built-in renderer |

---

## Approach 1 — `toolRenderers`

Map tool names to React components. Each component receives the tool's args and result as props.

### Basic example

```tsx

function WeatherCard({ data, status }) {
  if (status === "executing") {
    return <div className="animate-pulse">Loading weather...</div>;
  }
  return (
    <div className="p-4 rounded-lg bg-gradient-to-br from-blue-400 to-blue-600 text-white">
      <h3 className="text-xl font-bold">{data.city}</h3>
      <p className="text-4xl">{data.temp}°F</p>
      <p>{data.conditions}</p>
    </div>
  );
}

<CopilotChat
  toolRenderers={{
    get_weather: WeatherCard,
    get_chart: ChartCard,
    search_products: ProductGrid,
  }}
/>
```

### ToolRendererProps

Every renderer receives these props:

```typescript
interface ToolRendererProps {
  status: "pending" | "executing" | "completed" | "error" | "failed" | "rejected";
  args: Record<string, unknown>;   // arguments passed to the tool
  data?: unknown;                  // result (when completed)
  error?: string;                  // error message (when failed)
  executionId: string;
  toolName: string;
}
```

### Handling all states

```tsx
function ChartCard({ status, data, error, args }: ToolRendererProps) {
  if (status === "pending" || status === "executing") {
    return (
      <div className="p-4 border rounded-lg">
        <div className="animate-spin h-6 w-6 border-2 border-primary rounded-full border-t-transparent" />
        <p className="text-sm text-muted-foreground mt-2">
          Generating {args.metric} chart...
        </p>
      </div>
    );
  }

  if (status === "error" || status === "failed") {
    return (
      <div className="p-4 border border-destructive rounded-lg">
        <p className="text-destructive">Failed to load chart</p>
        <p className="text-sm text-muted-foreground">{error}</p>
      </div>
    );
  }

  if (status === "rejected") {
    return (
      <div className="p-4 border rounded-lg bg-muted">
        <p className="text-muted-foreground">Chart request was declined</p>
      </div>
    );
  }

  return (
    <div className="p-4 border rounded-lg">
      <h3 className="font-semibold mb-4">{data.title}</h3>
      <ResponsiveContainer width="100%" height={300}>
        <LineChart data={data.chartData}>
          <XAxis dataKey="date" />
          <YAxis />
          <Line type="monotone" dataKey="value" stroke="#8884d8" />
        </LineChart>
      </ResponsiveContainer>
    </div>
  );
}
```

### Interactive components

Renderers can be fully interactive and call back into the chat:

```tsx
function ProductCard({ data }: ToolRendererProps) {
  const [quantity, setQuantity] = useState(1);
  const { sendMessage } = useCopilot();

  return (
    <div className="p-4 border rounded-lg">
      <img src={data.image} alt={data.name} />
      <h3>{data.name}</h3>
      <p>${data.price}</p>
      <div className="flex items-center gap-2 mt-4">
        <input
          type="number"
          value={quantity}
          onChange={(e) => setQuantity(Number(e.target.value))}
          className="w-16 border rounded px-2 py-1"
        />
        <button
          onClick={() => sendMessage(`Add ${quantity} of ${data.name} to my cart`)}
          className="btn-primary"
        >
          Add to Cart
        </button>
      </div>
    </div>
  );
}
```

### Control AI response verbosity

Return `_aiResponseMode: "brief"` from your tool handler to prevent the AI from describing what the UI already shows:

```tsx
handler: async ({ timeRange }) => {
  const data = await fetchDashboardData(timeRange);
  return {
    success: true,
    data,
    _aiResponseMode: "brief",
    _aiContext: `Dashboard for ${timeRange}`,
  };
},
```

<Callout type="info">
Use `_aiResponseMode: "brief"` when your UI component is self-explanatory. The AI gives a short acknowledgment instead of narrating the data.
</Callout>

---

## Approach 2 — AI-Generated UI (Experimental)

<Callout type="warn">
`@yourgpt/copilot-sdk/experimental` — APIs may change without a semver major bump.
</Callout>

The AI calls a single `render_ui` tool and generates the UI itself. The standout capability is `type: "html"` — the AI writes full HTML with Tailwind CSS and Chart.js, rendered in a sandboxed iframe. No pre-built component needed. For structured data it can also pick typed renderers (`table`, `stat`, `card`, `chart`) automatically.

```
User: "Show Q1 revenue by region"
     ↓
AI calls: render_ui({ type: "chart", chartType: "bar", labels: ["NA","EU","APAC"], datasets: [...] })
     ↓
UI renders: [Bar chart]

User: "Build an analytics dashboard"
     ↓
AI calls: render_ui({ type: "html", html: "<div class='grid grid-cols-3 gap-4'>...</div>", height: "600px" })
     ↓
UI renders: [Full dashboard in sandboxed iframe with Tailwind + Chart.js]
```

### Setup

<Tabs items={['Backend', 'Frontend']}>
  <Tab value="Backend">

Register `generativeUITool()` in your route. The key becomes the tool name.

```typescript

export async function POST(req: Request) {
  const { messages } = await req.json();

  const result = await streamText({
    model: openai("gpt-4o"),
    system: "Use render_ui for any data, charts, or structured results.",
    messages,
    tools: {
      render_ui: generativeUITool(),
    },
  });

  return result.toDataStreamResponse();
}
```

  </Tab>
  <Tab value="Frontend">

Call `useGenerativeUI()` once in your component tree — it registers the renderer automatically.

```tsx

function App() {
  useGenerativeUI({
    chartRenderer: MyChartComponent, // required for chart type
  });

  return <CopilotChat />;
}
```

  </Tab>
</Tabs>

### Built-in component types

| Type | When the AI uses it | Renderer |
|------|-------------------|----------|
| `html` | Dashboards, custom layouts, anything freeform | `HtmlRenderer` — sandboxed `<iframe>` with Tailwind CDN + Chart.js CDN pre-loaded |
| `table` | Structured rows — comparisons, records, lists | `TableRenderer` |
| `stat` | KPI metrics, numbers with change deltas | `StatRenderer` |
| `card` | Entity summaries — profiles, products, key-value info | `CardRenderer` |
| `chart` | Bar, line, pie, area, scatter graphs | Requires `chartRenderer` prop |

### `html` type — AI-generated iframe UI

When the AI uses `type: "html"`, it can write full HTML with Tailwind utility classes and inline Chart.js canvases. The SDK renders it in a sandboxed `<iframe>` so it's fully isolated from your app.

The iframe automatically loads:
- **Tailwind CSS** Play CDN — any utility class works
- **Chart.js** — create charts with `<canvas>` + `new Chart(...)`

```tsx
// The AI generates something like this:
render_ui({
  type: "html",
  height: "520px",
  html: `
    <div class="grid grid-cols-3 gap-4 p-6">
      <div class="bg-white rounded-xl border border-gray-200 shadow-sm p-6">
        <p class="text-sm text-gray-500">Monthly Revenue</p>
        <p class="text-3xl font-bold text-gray-900 mt-1">$84,200</p>
        <span class="text-xs bg-green-50 text-green-700 px-2 py-0.5 rounded-full">+12%</span>
      </div>
      <!-- more cards... -->
    </div>
    <canvas id="chart" height="220"></canvas>
    <script>
    new Chart(document.getElementById('chart'), {
      type: 'bar',
      data: { labels: ['Jan','Feb','Mar'], datasets: [{ data: [65,80,84], backgroundColor: '#6366f1' }] }
    });
    </script>
  `
})
```

### Chart renderer

Charts require a user-supplied renderer since the SDK doesn't bundle a charting library:

```tsx

function MyChart({ payload }: ChartRendererProps) {
  const data = payload.labels.map((label, i) => ({
    name: label,
    ...Object.fromEntries(payload.datasets.map((d) => [d.label, d.data[i]])),
  }));

  return (
    <ResponsiveContainer width="100%" height={300}>
      <BarChart data={data}>
        <XAxis dataKey="name" />
        <YAxis />
        <Tooltip />
        {payload.datasets.map((d) => (
          <Bar key={d.label} dataKey={d.label} fill={d.color ?? "#6366f1"} />
        ))}
      </BarChart>
    </ResponsiveContainer>
  );
}

useGenerativeUI({ chartRenderer: MyChart });
```

### Override built-in renderers

Replace any built-in renderer with your own component:

```tsx
useGenerativeUI({
  overrideRenderers: {
    card: MyCustomCardRenderer,
    table: MyCustomTableRenderer,
  },
});
```

### Custom tool name

If you use a key other than `render_ui` in `tools`, pass the same name to `useGenerativeUI`:

```typescript
// Backend
tools: { show_component: generativeUITool() }

// Frontend
useGenerativeUI({ name: "show_component" });
```

---

## Getting Started
URL: https://copilot-sdk.yourgpt.ai/docs/getting-started
Description: Get up and running in 2 minutes

<Callout type="info">
**Prerequisites:** Node 18+, an LLM API key (OpenAI, Anthropic, etc.)
</Callout>

<Callout title="Starting fresh?" type="info">
Use the CLI to scaffold a complete project: `npx create-ai-copilot`
</Callout>

---

## 1. Install Dependencies

<Tabs items={['Anthropic', 'OpenAI / Google / xAI']}>
  <Tab value="Anthropic">
    ```bash
    pnpm add @yourgpt/copilot-sdk @yourgpt/llm-sdk @anthropic-ai/sdk zod
    ```
  </Tab>
  <Tab value="OpenAI / Google / xAI">
    ```bash
    pnpm add @yourgpt/copilot-sdk @yourgpt/llm-sdk openai zod
    ```

    <Callout type="info">
    The `openai` package works with OpenAI, Google Gemini, and xAI (all OpenAI-compatible APIs).
    </Callout>
  </Tab>
</Tabs>

---

## 2. Create API Route

<Tabs items={['Anthropic', 'OpenAI', 'Google']}>
  <Tab value="Anthropic">
    ```ts title="app/api/chat/route.ts"
    import { streamText } from '@yourgpt/llm-sdk';
    import { anthropic } from '@yourgpt/llm-sdk/anthropic';

    export async function POST(req: Request) {
      const { messages } = await req.json();

      const result = await streamText({
        model: anthropic('claude-sonnet-4-20250514'),
        system: 'You are a helpful assistant.',
        messages,
      });

      return result.toTextStreamResponse();
    }
    ```

    ```bash title=".env.local"
    ANTHROPIC_API_KEY=sk-ant-...
    ```
  </Tab>
  <Tab value="OpenAI">
    ```ts title="app/api/chat/route.ts"
    import { streamText } from '@yourgpt/llm-sdk';
    import { openai } from '@yourgpt/llm-sdk/openai';

    export async function POST(req: Request) {
      const { messages } = await req.json();

      const result = await streamText({
        model: openai('gpt-4o'),
        system: 'You are a helpful assistant.',
        messages,
      });

      return result.toTextStreamResponse();
    }
    ```

    ```bash title=".env.local"
    OPENAI_API_KEY=sk-...
    ```
  </Tab>
  <Tab value="Google">
    ```ts title="app/api/chat/route.ts"
    import { streamText } from '@yourgpt/llm-sdk';
    import { google } from '@yourgpt/llm-sdk/google';

    export async function POST(req: Request) {
      const { messages } = await req.json();

      const result = await streamText({
        model: google('gemini-2.0-flash'),
        system: 'You are a helpful assistant.',
        messages,
      });

      return result.toTextStreamResponse();
    }
    ```

    ```bash title=".env.local"
    GOOGLE_API_KEY=...
    ```
  </Tab>
</Tabs>

<Callout type="info">
See [Providers](/docs/providers) for more providers and configuration options.
</Callout>

---

## 3. Add Provider

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


export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <CopilotProvider runtimeUrl="/api/chat">
      {children}
    </CopilotProvider>
  );
}
```

Wrap your app with the provider:

```tsx title="app/layout.tsx"

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  );
}
```

---

## 4. Add Chat Component

```tsx title="app/page.tsx"

export default function Home() {
  return (
    <div className="h-screen p-4">
      <CopilotChat className="h-full rounded-xl border" />
    </div>
  );
}
```

---

## 5. Configure Tailwind

The SDK uses Tailwind CSS utility classes. Add the SDK source path based on your CSS file location:

| CSS file location | @source path |
|-------------------|--------------|
| `app/globals.css` | `@source "../node_modules/@yourgpt/copilot-sdk/dist/**/*.{js,ts,jsx,tsx}";` |
| `src/app/globals.css` | `@source "../../node_modules/@yourgpt/copilot-sdk/dist/**/*.{js,ts,jsx,tsx}";` |
| `globals.css` (root) | `@source "node_modules/@yourgpt/copilot-sdk/dist/**/*.{js,ts,jsx,tsx}";` |

```css title="app/globals.css"
@import "tailwindcss";

/* Include SDK package for Tailwind class detection */
@source "../node_modules/@yourgpt/copilot-sdk/dist/**/*.{js,ts,jsx,tsx}";

@custom-variant dark (&:is(.dark *));

/* Your existing shadcn/ui @theme and variables... */
```

The SDK works automatically with your existing shadcn/ui CSS variables.

<Accordions type="single">
  <Accordion title="Without shadcn/ui (Manual Setup)" id="without-shadcn">
    If you don't have shadcn/ui, you need to add both the `@theme inline` block and CSS variables:

    ```css title="app/globals.css"
    @import "tailwindcss";

    @source "../node_modules/@yourgpt/copilot-sdk/dist/**/*.{js,ts,jsx,tsx}";

    @custom-variant dark (&:is(.dark *));

    /* Map CSS variables to Tailwind theme (required for Tailwind v4) */
    @theme inline {
      --color-background: var(--background);
      --color-foreground: var(--foreground);
      --color-card: var(--card);
      --color-card-foreground: var(--card-foreground);
      --color-popover: var(--popover);
      --color-popover-foreground: var(--popover-foreground);
      --color-primary: var(--primary);
      --color-primary-foreground: var(--primary-foreground);
      --color-secondary: var(--secondary);
      --color-secondary-foreground: var(--secondary-foreground);
      --color-muted: var(--muted);
      --color-muted-foreground: var(--muted-foreground);
      --color-accent: var(--accent);
      --color-accent-foreground: var(--accent-foreground);
      --color-destructive: var(--destructive);
      --color-border: var(--border);
      --color-input: var(--input);
      --color-ring: var(--ring);
      --radius-sm: calc(var(--radius) - 4px);
      --radius-md: calc(var(--radius) - 2px);
      --radius-lg: var(--radius);
      --radius-xl: calc(var(--radius) + 4px);
    }

    /* Define CSS variables */
    :root {
      --background: hsl(0 0% 100%);
      --foreground: hsl(240 10% 3.9%);
      --card: hsl(0 0% 100%);
      --card-foreground: hsl(240 10% 3.9%);
      --popover: hsl(0 0% 100%);
      --popover-foreground: hsl(240 10% 3.9%);
      --primary: hsl(240 5.9% 10%);
      --primary-foreground: hsl(0 0% 98%);
      --secondary: hsl(240 4.8% 95.9%);
      --secondary-foreground: hsl(240 5.9% 10%);
      --muted: hsl(240 4.8% 95.9%);
      --muted-foreground: hsl(240 3.8% 46.1%);
      --accent: hsl(240 4.8% 95.9%);
      --accent-foreground: hsl(240 5.9% 10%);
      --destructive: hsl(0 84.2% 60.2%);
      --border: hsl(240 5.9% 90%);
      --input: hsl(240 5.9% 90%);
      --ring: hsl(240 5.9% 10%);
      --radius: 0.5rem;
    }

    .dark {
      --background: hsl(240 10% 3.9%);
      --foreground: hsl(0 0% 98%);
      --card: hsl(240 10% 3.9%);
      --card-foreground: hsl(0 0% 98%);
      --popover: hsl(240 10% 3.9%);
      --popover-foreground: hsl(0 0% 98%);
      --primary: hsl(0 0% 98%);
      --primary-foreground: hsl(240 5.9% 10%);
      --secondary: hsl(240 3.7% 15.9%);
      --secondary-foreground: hsl(0 0% 98%);
      --muted: hsl(240 3.7% 15.9%);
      --muted-foreground: hsl(240 5% 64.9%);
      --accent: hsl(240 3.7% 15.9%);
      --accent-foreground: hsl(0 0% 98%);
      --destructive: hsl(0 62.8% 30.6%);
      --border: hsl(240 3.7% 15.9%);
      --input: hsl(240 3.7% 15.9%);
      --ring: hsl(240 4.9% 83.9%);
    }

    @layer base {
      * {
        @apply border-border;
      }
      body {
        @apply bg-background text-foreground;
      }
    }
    ```

    <Callout type="info">
    The `@theme inline` block is **required** for Tailwind v4 to map CSS variables to utility classes like `bg-background`.
    </Callout>
  </Accordion>

  <Accordion title="Using Tailwind CSS v3?" id="tailwind-v3">
    Add the SDK package to your Tailwind config content paths:

    ```js title="tailwind.config.js"
    /** @type {import('tailwindcss').Config} */
    module.exports = {
      content: [
        './app/**/*.{js,ts,jsx,tsx,mdx}',
        './components/**/*.{js,ts,jsx,tsx,mdx}',
        './node_modules/@yourgpt/copilot-sdk/dist/**/*.{js,ts,jsx,tsx}',
      ],
      theme: {
        extend: {},
      },
      plugins: [],
    };
    ```
  </Accordion>
</Accordions>

---

## Done!

Run `pnpm dev` and you have a working AI chat.

---

## Next Steps

- [Copilot UI](/docs/ui) - Themes and styling
- [Add AI Tools](/docs/tools) - Give AI capabilities
- [Switch Providers](/docs/providers) - Use different LLMs

---

## Overview
URL: https://copilot-sdk.yourgpt.ai/docs/overview
Description: What is Copilot SDK

Copilot SDK lets you add AI chat to any React app. Tools execute on the frontend, giving the AI real capabilities in your app.

---

## How It Works

<ArchitectureDiagram />

---

## Key Concepts

<Cards>
  <Card title="Chat" href="/docs/chat">
    Pre-built chat UI component with streaming, markdown, and code highlighting.
  </Card>
  <Card title="Tools" href="/docs/tools">
    Give the AI abilities - search, navigate, fetch data, show UI.
  </Card>
  <Card title="Providers" href="/docs/providers">
    Use OpenAI, Anthropic, Google, xAI, and more.
  </Card>
</Cards>

---

## Why Frontend Tools?

Unlike server-side tool execution, frontend tools can:

- **Access browser APIs** - DOM, localStorage, navigation
- **Show rich UI** - Render React components as tool results
- **Use app state** - Read/write your React state directly
- **Real-time updates** - Stream results as they happen

<Callout type="info">
Tools run in the browser where your app lives. The AI decides what to call, your code executes it.
</Callout>

---

## Quick Example

```tsx
// Register a tool
useTools({
  search_products: {
    description: 'Search product catalog',
    parameters: z.object({ query: z.string() }),
    handler: async ({ query }) => {
      const results = await searchAPI(query);
      return { products: results };
    },
  },
});

// That's it - AI can now search your products
```

User says: *"Find wireless headphones under $100"*

AI calls `search_products({ query: "wireless headphones" })` → Shows results.

---

## Features

| Feature | Description |
|---------|-------------|
| [**Chat UI**](/docs/chat) | Pre-built chat with streaming, markdown, code blocks |
| [**Frontend Tools**](/docs/tools/frontend-tools) | Give AI abilities in your app |
| [**Generative UI**](/docs/generative-ui) | Render React components as tool results |
| [**Smart AI Context**](/docs/skills) | AI understands your app state |
| [**Agentic Loop**](/docs/tools/agentic-loop) | Multi-step reasoning and tool chains |
| [**Attachments**](/docs/attachments) | Images, PDFs, and files in chat |
| [**4+ Providers**](/docs/providers) | OpenAI, Anthropic, Google, xAI... |
| [**Backend Tools**](/docs/tools/backend-tools) | Secure backend tool execution |
| [**Chat History**](/docs/chat-history) | Persist conversations across sessions |

---

## Next Steps

- [Getting Started](/docs/getting-started) - 5 minute setup
- [Chat](/docs/chat) - Chat component docs
- [Frontend Tools](/docs/tools/frontend-tools) - Build AI capabilities

---

## Playground
URL: https://copilot-sdk.yourgpt.ai/docs/playground
Description: Interactive sandbox to experiment with Copilot SDK features

<PlaygroundShowcase
  videoUrl="https://assets.yourgpt.ai/web/copilot-sdk/smart-banking-assistant.mp4"
  posterUrl="/images/copilot-sdk-playground.webp"
/>

---

## Why Copilot SDK
URL: https://copilot-sdk.yourgpt.ai/docs/why-copilot-sdk
Description: Build production-ready AI copilots in minutes, not months. Self-hosted, enterprise-grade, zero lock-in.

export const Yes = () => <Check1 className="text-green-500 inline-block" width={18} height={18} />;
export const No = () => <X className="text-red-400 inline-block" size={18} />;
export const Partial = () => <span className="text-yellow-500 text-sm">Partial</span>;

Building AI assistants shouldn't require a team of ML engineers and months of development. Yet that's exactly what most solutions demand.

<Callout type="info">
**Ship in hours, not months.** From zero to production-ready AI copilot with 3 lines of code.
</Callout>

---

## What Makes Us Different

<Cards>
  <Card title="Ship in Minutes" icon={<RocketIcon className="size-full" />}>
    3 lines of code to a working AI copilot. Not an exaggeration. Provider, chat component, done.
  </Card>
  <Card title="100% Self-Hosted" icon={<Computer className="size-full" />}>
    Your servers, your data, your rules. Full source code access. Zero vendor lock-in.
  </Card>
  <Card title="Context-Aware AI" icon={<MessageCircleMore className="size-full" />}>
    Built-in screenshot capture, console monitoring, network inspection. AI actually sees what users see.
  </Card>
  <Card title="Prebuilt Copilot" icon={<Bot className="size-full" />}>
    Ready-to-use chat UI, tools, and backend. Just install and deploy.
  </Card>
</Cards>

---

## vs Competitors

| Feature | Copilot SDK | Vercel AI SDK | CopilotKit | assistant-ui |
|---------|:-------:|:-------------:|:----------:|:------------:|
| **Copilot UI** | <Yes /> | <No /> | <Yes /> | <Yes /> |
| **Complete Stack** | <Yes /> | <No /> | <Partial /> | <No /> |
| **100% Self-Hosted** | <Yes /> | <Yes /> | <Partial /> | <Yes /> |
| **Smart Context** | <Yes /> | <No /> | <No /> | <No /> |
| **Your Knowledgebase** | <Yes /> | <No /> | <Partial /> | <No /> |
| **Generative UI** | <Yes /> | <No /> | <Partial /> | <No /> |
| **MCP Support** | <Yes/> | <No /> | <No /> | <No /> |

<Callout type="info">
**CopilotKit Pricing**: $1,000/seat/month for teams, 50 MAU free tier limit with $100/100 MAU overage charges.
</Callout>

---

## Built for Speed

### What Takes Others Weeks, Takes You Minutes

```tsx
// Step 1: Wrap your app (30 seconds)
<CopilotProvider runtimeUrl="/api/chat">
  <App />
</CopilotProvider>

// Step 2: Add the chat (30 seconds)
<CopilotChat />

// Step 3: You're done. Ship it.
```

**That's a production-ready AI copilot.** With streaming, conversation history, and beautiful UI.

Want more? Add context awareness in one line:

```tsx
<CopilotProvider
  tools={{ screenshot: true, console: true }}
/>
```

Now your AI can see screenshots and read console errors.

---

## Ready to Build?

<Cards>
  <Card title="Getting Started" href="/docs/getting-started" icon={<Zap className="size-full" />}>
    Go from zero to AI copilot in 5 minutes
  </Card>
  <Card title="See Features" href="/docs/overview" icon={<Search className="size-full" />}>
    Explore everything the SDK can do
  </Card>
  <Card title="Browse Providers" href="/docs/providers" icon={<Plug className="size-full" />}>
    OpenAI, Anthropic, Google, and more
  </Card>
</Cards>

---

## Conversation Branching
URL: https://copilot-sdk.yourgpt.ai/docs/advanced/branching
Description: Edit messages to create parallel conversation paths, just like ChatGPT and Claude.ai

Edit any user message to create a parallel conversation path, preserving the original. Navigate between variants with `← N/M →` — the same UX as ChatGPT, Claude.ai, and Gemini.

---

## Zero-Config Usage

If you use `<CopilotChat />`, branching is **already active**. No code changes needed.

- Edit button (✏) appears on hover over any user message
- `← 1/2 →` navigator appears below user messages when variants exist
- Regenerate creates a new branch instead of overwriting

```tsx
// Nothing to add — branching works out of the box
<CopilotChat className="h-[600px]" />
```

---

## API

### `useCopilot()`

```typescript
const {
  switchBranch,   // (messageId: string) => void
  getBranchInfo,  // (messageId: string) => BranchInfo | null
  editMessage,    // (messageId: string, newContent: string) => Promise<void>
  hasBranches,    // boolean — true if any fork exists
  getAllMessages,  // () => UIMessage[] — all branches, not just visible path
} = useCopilot();
```

### `BranchInfo`

```typescript
interface BranchInfo {
  siblingIndex: number;    // 0-based — which variant this is
  totalSiblings: number;   // how many variants exist at this fork
  siblingIds: string[];    // ordered oldest-first
  hasPrevious: boolean;
  hasNext: boolean;
}
```

### `BranchNavigator` component

Standalone navigator for custom message renderers:

```tsx

<BranchNavigator
  siblingIndex={info.siblingIndex}
  totalSiblings={info.totalSiblings}
  hasPrevious={info.hasPrevious}
  hasNext={info.hasNext}
  onPrevious={() => switchBranch(info.siblingIds[info.siblingIndex - 1])}
  onNext={() => switchBranch(info.siblingIds[info.siblingIndex + 1])}
/>
```

### `MessageTree` (framework-agnostic)

```typescript

const tree = new MessageTree(messages);
tree.getVisibleMessages(); // active path only (sent to AI)
tree.getAllMessages();     // all branches (for persistence)
tree.getBranchInfo(messageId); // BranchInfo | null
tree.switchBranch(messageId);
tree.hasBranches; // boolean
```

---

## Custom Message Renderers

Use `getBranchInfo` + `BranchNavigator` in your own message components:

```tsx
function MyMessage({ message }) {
  const { switchBranch, getBranchInfo } = useCopilot();
  const info = message.role === "user" ? getBranchInfo(message.id) : null;

  return (
    <div>
      <p>{message.content}</p>
      {info && (
        <BranchNavigator
          {...info}
          onPrevious={() => switchBranch(info.siblingIds[info.siblingIndex - 1])}
          onNext={() => switchBranch(info.siblingIds[info.siblingIndex + 1])}
        />
      )}
    </div>
  );
}
```

---

## Programmatic Branching

```typescript
// Edit a message (creates new branch from same parent)
await editMessage("msg-abc", "Updated question text");

// Navigate between variants
switchBranch("msg-xyz");

// Check if branches exist
if (hasBranches) {
  const info = getBranchInfo("msg-abc");
  console.log(info.totalSiblings, info.siblingIndex);
}

// Persist all branches (not just visible path)
const allMessages = getAllMessages();
await saveToServer(allMessages);
```

---

## Persistence

### Optional DB columns

```sql
ALTER TABLE messages
  ADD COLUMN parent_id TEXT REFERENCES messages(id),
  ADD COLUMN children_ids JSONB DEFAULT '[]';
```

<Callout type="info">
These columns are **optional**. Existing rows without them are auto-migrated to a linear tree on load — no data loss, no migration required.
</Callout>

When `onMessagesChange` fires, the payload contains **all messages across all branches**:

```json
{
  "id": "msg-abc",
  "role": "assistant",
  "content": "...",
  "parent_id": "msg-xyz",
  "children_ids": []
}
```

Use upsert-by-ID when saving — a simple overwrite will lose inactive branches:

```typescript
// ✅ Safe for branching
await db.messages.upsert({ id: msg.id, ...msg });

// ⚠️ Loses inactive branches
await db.threads.update({ messages: visibleMessages });
```

---

## Message History Compaction
URL: https://copilot-sdk.yourgpt.ai/docs/advanced/compaction
Description: Auto-summarize old messages to keep long conversations within the AI's context window

<Callout type="warn">
**Experimental** — This feature is under active development. APIs may change before stable release.
</Callout>

Keep long conversations alive without hitting token limits. The SDK maintains two parallel views of message history — a full display layer for the UI, and a compacted layer sent to the model.

---

## How It Works

Every conversation maintains two parallel views:

| Layer | Type | Purpose |
|-------|------|---------|
| **Display layer** | `DisplayMessage[]` | Full immutable history. Rendered in the UI. Never shrinks. |
| **LLM context layer** | `LLMMessage[]` | Compacted/pruned form sent to the model on each request. |

When compaction fires, a `CompactionMarker` is injected into the display layer so users can see where summarization happened — but the full history is never deleted.

### Types

```typescript
interface DisplayMessage extends UIMessage {
  timestamp: number;
}

interface CompactionMarker extends DisplayMessage {
  role: "system";
  type: "compaction-marker";
  content: string;
  summarizedMessageIds: string[];
  tokensSaved: number;
}

interface LLMMessage {
  role: "system" | "user" | "assistant" | "tool";
  content: string;
  tool_calls?: ToolCall[];
  tool_call_id?: string;
}
```

### Conversion Helpers

```typescript
import {
  toDisplayMessage,
  toLLMMessage,
  toLLMMessages,
  keepToolPairsAtomic,
} from "@yourgpt/copilot-sdk/react";
```

`keepToolPairsAtomic` ensures that when you slice a window, an `assistant` message with `tool_calls` is never separated from its corresponding tool-result messages.

---

## useMessageHistory

```typescript

function MyChat() {
  const {
    displayMessages,      // Full UI history
    llmMessages,          // Compacted LLM context
    tokenUsage,           // Live token estimate
    isCompacting,         // true while auto-compaction runs
    compactionState,      // Metadata & rolling summary
    compactSession,       // Manual trigger
    addToWorkingMemory,
    clearWorkingMemory,
    resetSession,
  } = useMessageHistory({
    strategy: "summary-buffer",
    maxContextTokens: 128000,
    compactionThreshold: 0.75,
    compactionUrl: "/api/compact",
    persistSession: true,
  });
}
```

---

## Compaction Strategies

### `"none"` (default)

No compaction. Zero-config, 100% backward-compatible.

```typescript
useMessageHistory({ strategy: "none" });
```

### `"sliding-window"`

Keeps only the most recent N tokens of history. Oldest messages are dropped when the token budget is exceeded.

```typescript
useMessageHistory({
  strategy: "sliding-window",
  maxContextTokens: 128000,
  reserveForResponse: 4096,
  recentBuffer: 10,        // Always keep at least 10 recent messages
  toolResultMaxChars: 10000, // Truncate large tool results
});
```

### `"selective-prune"`

Removes old tool-result messages while keeping the user/assistant conversation skeleton. Lighter than sliding-window — no token counting required.

```typescript
useMessageHistory({
  strategy: "selective-prune",
  recentBuffer: 10,
});
```

### `"summary-buffer"`

Summarizes old messages into a rolling summary when usage exceeds `compactionThreshold`. The summary is injected as a system message. Requires a `/api/compact` endpoint.

```typescript
useMessageHistory({
  strategy: "summary-buffer",
  compactionThreshold: 0.75, // Compact at 75% of maxContextTokens
  compactionUrl: "/api/compact",
  recentBuffer: 10,
  onCompaction: (event) => {
    console.log(`Compacted ${event.messagesSummarized} messages, saved ~${event.tokensSaved} tokens`);
  },
});
```

Custom summarizer (skip the HTTP round-trip):

```typescript
useMessageHistory({
  strategy: "summary-buffer",
  summarizer: async (messages) => {
    const res = await myLLM.summarize(messages);
    return res.text;
  },
});
```

---

## Provider-level Config

Set defaults once in `<CopilotProvider>`:

```tsx
<CopilotProvider
  messageHistory={{
    strategy: "summary-buffer",
    maxContextTokens: 128000,
    compactionUrl: "/api/compact",
    persistSession: true,
  }}
>
  <App />
</CopilotProvider>
```

---

## Working Memory

Pin facts that survive all future compactions:

```typescript
const { addToWorkingMemory, clearWorkingMemory } = useMessageHistory({ ... });

// Survives compaction
addToWorkingMemory("User is on the Pro plan. Account ID: acct_123");

// Remove all pinned facts
clearWorkingMemory();
```

---

## Config Reference

```typescript
interface MessageHistoryConfig {
  strategy?: "none" | "sliding-window" | "summary-buffer" | "selective-prune";
  maxContextTokens?: number;       // default: 128000
  reserveForResponse?: number;     // default: 4096
  compactionThreshold?: number;    // default: 0.75
  recentBuffer?: number;           // default: 10
  toolResultMaxChars?: number;     // default: 10000 (0 = no cap)
  compactionUrl?: string;          // required for summary-buffer
  persistSession?: boolean;        // default: false
  storageKey?: string;             // default: "copilot-session"
  onCompaction?: (event: CompactionEvent) => void;
  onTokenUsage?: (usage: TokenUsage) => void;
}
```

---

## Server: `/api/compact` Endpoint

The `compactSession` utility powers the compaction endpoint. It calls Claude (defaults to `claude-haiku-4-5`) to produce a structured summary.

```typescript
// app/api/compact/route.ts

export async function POST(req: Request) {
  const { messages, existingSummary, workingMemory } = await req.json();

  const { summary } = await compactSession({
    messages,
    existingSummary,  // For rolling summaries on subsequent compactions
    workingMemory,    // User-pinned facts (addToWorkingMemory)
    model: "claude-haiku-4-5",
    maxSummaryTokens: 1024,
    apiKey: process.env.ANTHROPIC_API_KEY,
  });

  return Response.json({ summary });
}
```

<Callout type="info">
The summary preserves: user goals, technical decisions, tool call outcomes, errors and resolutions, pending tasks.
</Callout>

---

## Message Grouping

`groupConsecutiveMessages` groups consecutive messages of the same role into visual clusters — useful for custom chat UIs where adjacent user or assistant messages should appear as one block.

```typescript
```

Tool-call pairs are always kept atomic: an assistant message with `tool_calls` is never separated from its corresponding tool-result messages during windowing or pruning.

---

## Token Tracking
URL: https://copilot-sdk.yourgpt.ai/docs/advanced/token-tracking
Description: Monitor context window usage in real time with useContextStats

<Callout type="warn">
**Experimental** — This feature is under active development. APIs may change before stable release.
</Callout>

Monitor how much of the AI's context window is being used — broken down by message history, system prompt, tools, and injected context.

---

## useContextStats

```typescript

function ContextMonitor() {
  const {
    contextUsage,       // Full breakdown by bucket
    totalTokens,        // Convenience: total estimated tokens
    usagePercent,       // Convenience: window fill 0–1
    contextChars,       // Characters contributed by AI context injections
    toolCount,          // Number of currently registered tools
    messageCount,       // Visible (non-system) messages
    lastResponseUsage,  // Token usage from last assistant message
  } = useContextStats();

  return (
    <div>
      <p>{Math.round(usagePercent * 100)}% of context used</p>
      <p>{totalTokens} tokens / {toolCount} tools</p>
      {lastResponseUsage && (
        <p>Last turn: {lastResponseUsage.total_tokens} tokens</p>
      )}
    </div>
  );
}
```

### Return type

```typescript
interface ContextStats {
  contextUsage: ContextUsage | null;        // null until first message
  totalTokens: number;
  usagePercent: number;                     // 0 until first message
  contextChars: number;
  toolCount: number;
  messageCount: number;
  lastResponseUsage: MessageTokenUsage | null;
}

interface MessageTokenUsage {
  prompt_tokens: number;
  completion_tokens: number;
  total_tokens: number;
}
```

---

## Token Counting Utilities

Two tiers — pick the right trade-off between speed and accuracy.

### Tier 1: Fast (zero dependencies)

Uses a `chars / 3.5` heuristic. ~85–90% accurate for English. Always available, no bundle cost.

```typescript
import {
  estimateTokensFast,
  estimateMessageTokens,
  estimateMessagesTokens,
} from "@yourgpt/copilot-sdk/react";

const tokens = estimateTokensFast("Hello world");        // fast, synchronous
const msgTokens = estimateMessagesTokens(llmMessages);
```

### Tier 2: Accurate (lazy-loaded)

Uses `gpt-tokenizer` with the `o200k_base` encoding. Lazy-loaded only when called — no upfront bundle cost.

```typescript
import {
  countTokensAccurate,
  countMessagesTokensAccurate,
} from "@yourgpt/copilot-sdk/react";

// Only loads gpt-tokenizer on first call
const tokens = await countTokensAccurate("Hello world");
const msgTokens = await countMessagesTokensAccurate(llmMessages);
```

### Set estimation mode in `useMessageHistory`

```typescript
useMessageHistory({ tokenEstimation: "accurate" }); // "fast" | "accurate" | "off"
```

---

## Context Budget Enforcement

<Callout type="warn">
**Experimental** — APIs may change before stable release.
</Callout>

Automatically enforce per-bucket token limits so the prompt never overflows. Configured via `optimization.contextBudget` on `<CopilotProvider>`.

```tsx
<CopilotProvider
  optimization={{
    contextBudget: {
      enabled: true,
      budget: {
        contextWindowTokens: 128000,   // Total window size
        inputHeadroomRatio: 0.75,      // Use 75% for input, reserve rest for output
        systemPromptShare: 0.15,       // 15% of input budget for system prompt
        historyShare: 0.50,            // 50% for conversation history
        toolResultsShare: 0.30,        // 30% for tool results
        toolDefinitionsShare: 0.05,    // 5% for tool definitions
      },
      enforcement: {
        mode: "truncate",              // "warn" | "truncate" | "error"
        onBudgetExceeded: (usage) => {
          console.warn("Budget exceeded", usage.total.percent);
        },
      },
      monitoring: {
        enabled: true,
        onUsageUpdate: (usage) => trackMetrics(usage),
      },
    },
  }}
>
```

| `enforcement.mode` | Behaviour |
|--------------------|-----------|
| `"warn"` | Logs a warning, sends full payload |
| `"truncate"` | Trims content to fit — history first, then tool results |
| `"error"` | Throws before sending if budget is exceeded |

---

## Tool Result Truncation

<Callout type="warn">
**Experimental** — APIs may change before stable release.
</Callout>

Prevent a single large tool response from consuming the entire context. Configure under `optimization.toolResultConfig`:

```tsx
<CopilotProvider
  optimization={{
    toolResultConfig: {
      truncation: {
        enabled: true,
        strategy: "head-tail",     // Keep first + last chunk, drop middle
        maxContextShare: 0.3,      // Tool results can use at most 30% of context
        hardMaxChars: 40000,       // Absolute cap regardless of context size
        minKeepChars: 2000,        // Always keep at least this much per result
        preserveErrors: true,      // Never truncate error results
      },
    },
  }}
>
```

| `strategy` | Behaviour |
|------------|-----------|
| `"head-tail"` | Keeps the beginning and end of the result; drops the middle |
| `"head"` | Keeps only the beginning |
| `"tail"` | Keeps only the end |

A truncation notice is appended so the model knows the result was trimmed.

---

## Example: Context Usage Indicator

```tsx

export function ChatPanel() {
  const { tokenUsage, isCompacting, compactSession } = useMessageHistory();
  const { usagePercent, toolCount } = useContextStats();

  return (
    <div>
      <p>
        {Math.round(usagePercent * 100)}% context used · {toolCount} tools
      </p>
      {tokenUsage.isApproaching && (
        <button onClick={() => compactSession()}>Compact now</button>
      )}
      {isCompacting && <span>Summarizing history…</span>}
    </div>
  );
}
```

---

## Chat
URL: https://copilot-sdk.yourgpt.ai/docs/api-reference/chat
Description: Chat UI component and customization

Pre-built chat UI component with full customization support.

```bash
npm install @yourgpt/copilot-sdk/react
```

---

## CopilotChat

The main chat component.

```tsx

<CopilotChat
  title="AI Assistant"
  placeholder="Ask anything..."
  suggestions={['Help me', 'Search']}
  className="h-full"
/>
```

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `title` | `string` | `"AI Assistant"` | Header title |
| `placeholder` | `string` | `"Type a message..."` | Input placeholder |
| `suggestions` | `string[]` | `[]` | Quick action buttons |
| `className` | `string` | - | Additional CSS classes |
| `toolRenderers` | `Record<string, Component>` | `{}` | Custom tool result renderers |
| `attachmentsEnabled` | `boolean` | `false` | Enable file attachments |
| `voiceEnabled` | `boolean` | `false` | Enable voice input |

---

## toolRenderers

Render custom UI for tool results:

```tsx
<CopilotChat
  toolRenderers={{
    weather: ({ result, status }) => (
      <WeatherCard data={result} loading={status === 'executing'} />
    ),
    chart: ({ result }) => (
      <BarChart data={result.data} />
    ),
  }}
/>
```

### ToolRendererProps

```tsx
interface ToolRendererProps<T = unknown> {
  name: string;
  args: Record<string, unknown>;
  result: T;
  status: 'pending' | 'executing' | 'completed' | 'error';
  error?: string;
}
```

---

## Theming

```tsx
<CopilotChat
  theme={{
    mode: 'dark',
    primaryColor: '#6366f1',
    backgroundColor: '#1f2937',
    borderRadius: '12px',
  }}
/>
```

---

## Custom Styling

```tsx
<CopilotChat
  classNames={{
    container: 'my-container',
    header: 'my-header',
    messages: 'my-messages',
    input: 'my-input',
  }}
/>
```

---

## Core
URL: https://copilot-sdk.yourgpt.ai/docs/api-reference/core
Description: Core utilities, built-in tools, and types

Core utilities, built-in tools, and shared types.

```bash
npm install @yourgpt/copilot-sdk/core
```

---

## Built-in Tools

```tsx

// Available tools
builtinTools.capture_screenshot  // Screenshot tool
builtinTools.capture_console     // Console logs tool
```

---

## Types

### UIMessage

```tsx
interface UIMessage {
  id: string;
  role: 'user' | 'assistant' | 'tool' | 'system';
  content: string;
  createdAt: Date;
  toolCalls?: ToolCall[];
  toolCallId?: string;
  thinking?: string;
  attachments?: Attachment[];
}
```

### ToolExecution

```tsx
interface ToolExecution {
  id: string;
  name: string;
  args: Record<string, unknown>;
  status: 'pending' | 'executing' | 'completed' | 'error' | 'failed' | 'rejected';
  result?: unknown;
  error?: string;
  approvalStatus?: 'required' | 'approved' | 'rejected';
}
```

| Status | Description |
|--------|-------------|
| `pending` | Waiting to start |
| `executing` | Currently running |
| `completed` | Finished successfully |
| `error` | Failed with error |
| `failed` | Handler threw exception |
| `rejected` | User rejected approval |

### ToolDefinition

```tsx
interface ToolDefinition {
  name: string;
  description: string;
  parameters: ZodSchema;
  handler: (params: any) => Promise<any>;
  requiresApproval?: boolean;
}
```

### Attachment

```tsx
interface Attachment {
  id: string;
  type: 'image' | 'file' | 'audio' | 'video';
  name: string;
  url?: string;
  base64?: string;
  mimeType: string;
  size?: number;
}
```

### ToolCall

```tsx
interface ToolCall {
  id: string;
  type: 'function';
  function: {
    name: string;
    arguments: string;  // JSON string
  };
}
```

---

## API Reference
URL: https://copilot-sdk.yourgpt.ai/docs/api-reference
Description: Complete API documentation

Complete reference for all SDK packages and exports.

---

<Cards>
  <Card title="Core" href="/docs/api-reference/core">
    Core utilities, built-in tools, and types.
  </Card>
  <Card title="Chat" href="/docs/api-reference/chat">
    Chat UI component and customization.
  </Card>
  <Card title="React" href="/docs/api-reference/react">
    React hooks, provider, and components.
  </Card>
  <Card title="Vue" href="/docs/api-reference/vue">
    Vue.js integration (coming soon).
  </Card>
  <Card title="Angular" href="/docs/api-reference/angular">
    Angular integration (coming soon).
  </Card>
</Cards>

---

## Packages

| Package | Description |
|---------|-------------|
| `@yourgpt/copilot-sdk/core` | Core utilities, types, built-in tools |
| `@yourgpt/copilot-sdk/react` | Chat UI component |
| `@yourgpt/copilot-sdk/react` | React integration (hooks, provider) |
| `@yourgpt/llm-sdk` | Multi-provider LLM integration |

---

## Installation

```bash
npm install @yourgpt/copilot-sdk/react @yourgpt/llm-sdk
```

---

## Attachments
URL: https://copilot-sdk.yourgpt.ai/docs/chat/attachments
Description: Send images, PDFs, and files alongside chat messages

Send images, PDFs, and files alongside chat messages for AI analysis.

---

## Overview

```
User: [Attaches screenshot.png]
User: "What's wrong with this error?"
AI: "I can see a TypeError in your console. The issue is..."
```

---

## Enable Attachments

```tsx
<CopilotChat
  attachmentsEnabled={true}
/>
```

---

## Send Message with Attachment

```tsx
const { sendMessage } = useCopilot();

// Send with image
await sendMessage("Analyze this chart", [
  {
    type: 'image',
    data: base64ImageData,
    mimeType: 'image/png',
    filename: 'chart.png',
  },
]);

// Send with file
await sendMessage("Summarize this document", [
  {
    type: 'file',
    data: base64PdfData,
    mimeType: 'application/pdf',
    filename: 'report.pdf',
  },
]);
```

---

## Attachment Types

```typescript
interface MessageAttachment {
  type: 'image' | 'file' | 'audio' | 'video';
  data: string;        // Base64 encoded or URL
  mimeType: string;    // MIME type
  filename?: string;   // Display name
  url?: string;        // If stored in cloud
}
```

### Supported Types

| Type | MIME Types | Notes |
|------|------------|-------|
| `image` | `image/png`, `image/jpeg`, `image/gif`, `image/webp` | AI can analyze visually |
| `file` | `application/pdf`, `text/plain`, `text/csv` | AI extracts text content |
| `audio` | `audio/mp3`, `audio/wav` | Transcription (model dependent) |
| `video` | `video/mp4` | Frame extraction (model dependent) |

---

## Configuration

```tsx
<CopilotChat
  attachmentsEnabled={true}
  maxFileSize={10 * 1024 * 1024}  // 10MB
  allowedFileTypes={[
    'image/*',
    'application/pdf',
    '.csv',
    '.txt',
  ]}
/>
```

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `attachmentsEnabled` | `boolean` | `false` | Enable attachment button |
| `maxFileSize` | `number` | `5MB` | Maximum file size in bytes |
| `allowedFileTypes` | `string[]` | All | Allowed MIME types or extensions |
| `upload` | `string \| object \| function` | - | Upload handler (see below) |

---

## The `upload` Prop

One prop, three modes — from simple to full control:

```tsx
// 1. URL string — server handles the upload
<CopilotChat upload="/api/copilot/upload" />

// 2. Object — URL + custom headers/body
<CopilotChat upload={{
  url: "/api/copilot/upload",
  headers: () => ({ Authorization: `Bearer ${token}` }),
  body: { projectId: "abc" },
}} />

// 3. Function — full custom logic
<CopilotChat upload={async (file) => {
  const url = await myS3Upload(file);
  return { type: 'image', url, mimeType: file.type, filename: file.name };
}} />
```

Without `upload`, files are embedded as base64 in the message body (works but heavier payload).

---

## Server Upload (Recommended)

Point `upload` to your server endpoint. Files are uploaded there, and the returned URL is sent with the message.

```tsx
<CopilotChat
  attachmentsEnabled={true}
  upload="/api/copilot/upload"
/>
```

### With YourGPT

If your server uses the YourGPT adapter, the upload endpoint uses the same credentials:

```ts title="server.ts"

const yourgpt = createYourGPT({ apiKey, widgetUid });

app.post('/api/copilot/upload', async (req, res) => {
  const result = await yourgpt.uploadFile(req.body);
  res.json(result);
});
```

### With Custom Storage

```ts title="server.ts"
app.post('/api/copilot/upload', async (req, res) => {
  const { data, mimeType, filename } = req.body;
  const url = await myStorage.upload(Buffer.from(data, 'base64'), mimeType);
  res.json({ url });
});
```

### With Auth Headers

```tsx
<CopilotChat
  upload={{
    url: "/api/copilot/upload",
    headers: () => ({ Authorization: `Bearer ${getToken()}` }),
  }}
/>
```

---

## Custom Upload Function

For complete control — handle the file however you want:

```tsx
<CopilotChat
  attachmentsEnabled={true}
  upload={async (file: File) => {
    const formData = new FormData();
    formData.append('file', file);

    const response = await fetch('/api/upload', {
      method: 'POST',
      body: formData,
    });
    const { url } = await response.json();

    return {
      type: 'image',
      url,
      mimeType: file.type,
      filename: file.name,
    };
  }}
/>
```

<Callout type="info">
Cloud storage is recommended for production. Base64 embedding works but increases message size significantly.
</Callout>

---

## Programmatic Attachments

### From File Input

```tsx
function FileUploader() {
  const { sendMessage } = useCopilot();

  const handleFileSelect = async (e: React.ChangeEvent<HTMLInputElement>) => {
    const file = e.target.files?.[0];
    if (!file) return;

    // Convert to base64
    const base64 = await fileToBase64(file);

    await sendMessage("Please analyze this file", [{
      type: file.type.startsWith('image/') ? 'image' : 'file',
      data: base64,
      mimeType: file.type,
      filename: file.name,
    }]);
  };

  return <input type="file" onChange={handleFileSelect} />;
}

// Helper function
function fileToBase64(file: File): Promise<string> {
  return new Promise((resolve, reject) => {
    const reader = new FileReader();
    reader.onload = () => {
      const result = reader.result as string;
      // Remove data URL prefix
      resolve(result.split(',')[1]);
    };
    reader.onerror = reject;
    reader.readAsDataURL(file);
  });
}
```

### From Canvas/Screenshot

```tsx
async function sendScreenshot() {
  const { sendMessage } = useCopilot();

  // Capture using html2canvas or similar
  const canvas = await html2canvas(document.body);
  const base64 = canvas.toDataURL('image/png').split(',')[1];

  await sendMessage("What do you see on this screen?", [{
    type: 'image',
    data: base64,
    mimeType: 'image/png',
    filename: 'screenshot.png',
  }]);
}
```

### From URL

```tsx
await sendMessage("Analyze this image", [{
  type: 'image',
  url: 'https://example.com/chart.png',
  mimeType: 'image/png',
}]);
```

---

## Display Attachments

Attachments appear in message history:

```tsx
function MessageAttachments({ attachments }) {
  if (!attachments?.length) return null;

  return (
    <div className="flex gap-2 mt-2">
      {attachments.map((attachment, i) => (
        <AttachmentPreview key={i} attachment={attachment} />
      ))}
    </div>
  );
}

function AttachmentPreview({ attachment }) {
  if (attachment.type === 'image') {
    const src = attachment.url || `data:${attachment.mimeType};base64,${attachment.data}`;
    return (
      <img
        src={src}
        alt={attachment.filename}
        className="max-w-xs rounded-lg"
      />
    );
  }

  return (
    <div className="flex items-center gap-2 p-2 bg-muted rounded">
      <FileIcon className="w-4 h-4" />
      <span className="text-sm">{attachment.filename}</span>
    </div>
  );
}
```

---

## Image Analysis

AI can analyze images when using vision-capable models:

```tsx
// Works with: GPT-4o, Claude 3, Gemini Pro Vision
await sendMessage("What's in this image?", [{
  type: 'image',
  data: imageBase64,
  mimeType: 'image/png',
}]);
```

### Use Cases

- **Bug reports**: Attach screenshots of errors
- **Design feedback**: Upload mockups for AI review
- **Data analysis**: Send charts for interpretation
- **Document processing**: PDF extraction and summarization

---

## Best Practices

### 1. Compress Images

```tsx
async function compressImage(file: File): Promise<string> {
  const bitmap = await createImageBitmap(file);
  const canvas = document.createElement('canvas');

  // Resize if too large
  const maxSize = 1920;
  let { width, height } = bitmap;
  if (width > maxSize || height > maxSize) {
    const ratio = Math.min(maxSize / width, maxSize / height);
    width *= ratio;
    height *= ratio;
  }

  canvas.width = width;
  canvas.height = height;

  const ctx = canvas.getContext('2d')!;
  ctx.drawImage(bitmap, 0, 0, width, height);

  return canvas.toDataURL('image/jpeg', 0.8).split(',')[1];
}
```

### 2. Validate Before Upload

```tsx
function validateAttachment(file: File): string | null {
  const maxSize = 10 * 1024 * 1024; // 10MB

  if (file.size > maxSize) {
    return `File too large. Maximum size is ${maxSize / 1024 / 1024}MB`;
  }

  const allowedTypes = ['image/png', 'image/jpeg', 'application/pdf'];
  if (!allowedTypes.includes(file.type)) {
    return `File type not supported. Allowed: ${allowedTypes.join(', ')}`;
  }

  return null; // Valid
}
```

### 3. Show Upload Progress

```tsx
function UploadProgress({ progress }) {
  return (
    <div className="w-full bg-muted rounded-full h-2">
      <div
        className="bg-primary h-2 rounded-full transition-all"
        style={{ width: `${progress}%` }}
      />
    </div>
  );
}
```

---

## Full Example

```tsx
function ChatWithAttachments() {
  const { sendMessage } = useCopilot();
  const [uploading, setUploading] = useState(false);
  const fileInputRef = useRef<HTMLInputElement>(null);

  const handleAttachment = async (e: React.ChangeEvent<HTMLInputElement>) => {
    const file = e.target.files?.[0];
    if (!file) return;

    // Validate
    const error = validateAttachment(file);
    if (error) {
      toast.error(error);
      return;
    }

    setUploading(true);

    try {
      // Process image
      let data: string;
      if (file.type.startsWith('image/')) {
        data = await compressImage(file);
      } else {
        data = await fileToBase64(file);
      }

      // Send with message
      await sendMessage(`Please analyze this ${file.type.split('/')[0]}`, [{
        type: file.type.startsWith('image/') ? 'image' : 'file',
        data,
        mimeType: file.type,
        filename: file.name,
      }]);
    } catch (err) {
      toast.error('Upload failed');
    } finally {
      setUploading(false);
    }
  };

  return (
    <div>
      <input
        ref={fileInputRef}
        type="file"
        className="hidden"
        accept="image/*,application/pdf"
        onChange={handleAttachment}
      />

      <button
        onClick={() => fileInputRef.current?.click()}
        disabled={uploading}
        className="btn-secondary"
      >
        {uploading ? 'Uploading...' : 'Attach File'}
      </button>
    </div>
  );
}
```

---

## Next Steps

- [Streaming](/docs/llm-sdk/stream-text) - Real-time responses
- [AI Context](/docs/skills) - Provide app context
- [Custom Tools](/docs/tools/frontend-tools) - Build tools that use attachments

---

## Chat
URL: https://copilot-sdk.yourgpt.ai/docs/chat
Description: Pre-built chat component

Drop-in chat UI with streaming, markdown rendering, and tool execution display.

---

## Basic Usage

```tsx

function App() {
  return (
    <CopilotChat
      className="h-[600px] border rounded-xl"
    />
  );
}
```

---

## Props

| Prop | Type | Description |
|------|------|-------------|
| `title` | `string` | Header title |
| `placeholder` | `string` | Input placeholder text |
| `suggestions` | `string[]` | Quick suggestion chips |
| `className` | `string` | Container class |
| `toolRenderers` | `Record<string, Component>` | Custom tool result renderers |

---

## With Suggestions

```tsx
<CopilotChat
  title="AI Assistant"
  placeholder="Ask me anything..."
  suggestions={[
    "What can you help me with?",
    "Search for products",
    "Show my recent orders",
  ]}
/>
```

---

## Custom Tool Renderers

Render tool results as custom UI instead of JSON:

```tsx
// Define a custom renderer
function WeatherCard({ data }) {
  return (
    <div className="p-4 rounded-lg bg-blue-50">
      <h3>{data.city}</h3>
      <p className="text-3xl">{data.temperature}°</p>
      <p>{data.conditions}</p>
    </div>
  );
}

// Use it
<CopilotChat
  toolRenderers={{
    get_weather: WeatherCard,
  }}
/>
```

<Callout type="info">
Tool renderers receive the tool result `data` as props. Return any React component.
</Callout>

---

## Compound Components

For full layout control, use the compound component pattern:

### Basic Structure

```tsx

<CopilotChat.Root className="h-[600px]">
  {/* Custom home screen */}
  <CopilotChat.HomeView className="gap-6 p-6">
    <h1>Welcome!</h1>
    <CopilotChat.Input placeholder="Ask anything..." />
    <CopilotChat.Suggestions items={["Help", "Pricing"]} />
  </CopilotChat.HomeView>

  {/* Chat view uses default UI */}
  <CopilotChat.ChatView />
</CopilotChat.Root>
```

### Available Components

| Component | Description |
|-----------|-------------|
| `CopilotChat.Root` | Root container (alias for CopilotChat) |
| `CopilotChat.HomeView` | Shows when no messages (home screen) |
| `CopilotChat.ChatView` | Shows when there are messages |
| `CopilotChat.Header` | Header slot (view-specific when nested) |
| `CopilotChat.Footer` | Footer slot |
| `CopilotChat.Input` | Auto-connected input |
| `CopilotChat.Suggestions` | Suggestion buttons |
| `CopilotChat.BackButton` | Starts new chat (requires persistence) |
| `CopilotChat.ThreadPicker` | Thread switcher (requires persistence) |

### View-Specific Headers

Place `Header` inside `ChatView` to show it only in chat view:

```tsx
<CopilotChat.Root persistence={true}>
  {/* Home - no header */}
  <CopilotChat.HomeView>
    <h1>Welcome!</h1>
    <CopilotChat.Input />
  </CopilotChat.HomeView>

  {/* Chat - header with navigation */}
  <CopilotChat.ChatView>
    <CopilotChat.Header className="flex items-center justify-between p-3 border-b">
      <CopilotChat.BackButton />
      <span>Conversation</span>
      <CopilotChat.ThreadPicker />
    </CopilotChat.Header>
    {/* Default messages + input render automatically */}
  </CopilotChat.ChatView>
</CopilotChat.Root>
```

### Custom BackButton

```tsx
<CopilotChat.BackButton>
  ← Back to Home
</CopilotChat.BackButton>
```

### Context Hook

Access chat context in custom components:

```tsx

function CustomComponent() {
  const { view, send, isLoading } = useCopilotChatContext();
  return <button onClick={() => send("Hello!")}>Say Hi</button>;
}
```

---

## Build Your Own Chat

Use hooks for full control:

```tsx

function CustomChat() {
  const {
    messages,
    isLoading,
    sendMessage,
    toolExecutions,
  } = useCopilot();

  return (
    <div>
      {messages.map(msg => (
        <div key={msg.id}>
          <strong>{msg.role}:</strong> {msg.content}
        </div>
      ))}

      <input
        onKeyDown={(e) => {
          if (e.key === 'Enter') {
            sendMessage(e.currentTarget.value);
            e.currentTarget.value = '';
          }
        }}
        placeholder="Type a message..."
      />
    </div>
  );
}
```

---

## Error Handling

When the server returns a non-2xx response, the SDK removes the loading placeholder and surfaces the error via `state.error`. The built-in `CopilotChat` shows a dismissible banner — errors are **never written into message history**.

Handle errors via `CopilotProvider` props:

```tsx
<CopilotProvider
  runtimeUrl="/api/chat"
  onError={(error) => toast.error(error.message)}
  parseError={(status, body: any) => {
    // Return null to fall back to SDK default (body.message or body.error)
    return body?.errors?.[0]?.message ?? body?.detail ?? null;
  }}
>
```

Or read error state directly from `useCopilot()`:

```tsx
const { error, status } = useCopilot();
// error → null when idle, Error object on failure
// status → 'ready' | 'streaming' | 'submitted' | 'error'
```

The error clears automatically when the user sends the next message.

---

## Styling

The chat component uses Tailwind CSS. Override styles with className:

```tsx
<CopilotChat
  className="
    h-full
    rounded-xl
    border-2
    border-primary
    bg-background
  "
/>
```

---

## Next Steps

- [Tools](/docs/tools) - Add AI capabilities
- [Branching](/docs/chat/branching) - Conversation branching like ChatGPT
- [Message Actions](/docs/chat/message-actions) - Add copy, edit, feedback buttons

---

## Storage
URL: https://copilot-sdk.yourgpt.ai/docs/chat/storage
Description: Persist chat sessions, threads, and conversation history across reloads and devices

---

## Session Persistence

<Callout type="warn">
**Beta** — This feature is in **alpha**. APIs may change before stable release.
</Callout>

Persist the full conversation state — including compaction metadata and message history — across page reloads with zero extra code.

### Basic Setup

```typescript
useMessageHistory({
  persistSession: true,
  storageKey: "my-app-chat", // default: "copilot-session"
});
```

### What gets persisted

| Data | Where | Notes |
|------|-------|-------|
| `compactionState` (small metadata) | `localStorage` | Sync, available immediately on cold start |
| `displayMessages` (can be large) | `IndexedDB` | Async, avoids localStorage quota issues |

Both are keyed by `storageKey`. Multiple chat instances can coexist with different keys.

### Clear Everything

```typescript
const { resetSession } = useMessageHistory({ persistSession: true });

// Clears state AND storage
await resetSession();
```

### Multiple Chat Instances

```tsx
// Support chat — separate session
<CopilotProvider widgetToken="...">
  <SupportChat>
    {/* useMessageHistory({ storageKey: "support-chat" }) */}
  </SupportChat>
</CopilotProvider>

// Sales chat — separate session
<CopilotProvider widgetToken="...">
  <SalesChat>
    {/* useMessageHistory({ storageKey: "sales-chat" }) */}
  </SalesChat>
</CopilotProvider>
```

### Full Setup Example

```tsx
// app/layout.tsx

export default function RootLayout({ children }) {
  return (
    <CopilotProvider
      widgetToken="YOUR_TOKEN"
      messageHistory={{
        strategy: "summary-buffer",
        maxContextTokens: 128000,
        compactionThreshold: 0.75,
        compactionUrl: "/api/compact",
        persistSession: true,
        storageKey: "my-app",
        onCompaction: (e) => console.log("Compacted:", e),
      }}
    >
      {children}
    </CopilotProvider>
  );
}
```

---

## Chat History

Save and persist chat threads and messages so users can continue conversations across browser sessions, devices, or after logging out.

### Browser Storage

For simple browser-level persistence without server setup:

```tsx
<CopilotChat
  persistence={true}
  showThreadPicker={true}
/>
```

Data is stored in localStorage (~5MB limit, single device only).

#### Storage quota and auto-eviction

When the browser's localStorage quota is exceeded (typically after many long conversations), the SDK automatically evicts the oldest threads to make room for new ones. The most recent threads are always preserved.

This eviction happens silently — users won't see an error. If you need to monitor or control this behavior, you can listen to the `onStorageEviction` callback:

```tsx
<CopilotChat
  persistence={true}
  onStorageEviction={(evictedThreadIds) => {
    console.log('Evicted old threads:', evictedThreadIds);
  }}
/>
```

<Callout type="info">
  Auto-eviction only applies to browser localStorage. Server persistence has no such limit — use it when conversation history must be retained long-term.
</Callout>

### Server Persistence

Store threads in your own database for cross-device sync and user accounts.

```tsx
<CopilotChat
  persistence={{
    type: "server",
    endpoint: "/api/threads",
    headers: { Authorization: `Bearer ${token}` },
  }}
  showThreadPicker={true}
/>
```

#### API Contract

Your endpoint must implement these routes:

| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/api/threads` | List threads |
| `POST` | `/api/threads` | Create thread |
| `GET` | `/api/threads/:id` | Get thread with messages |
| `PATCH` | `/api/threads/:id` | Update thread |
| `DELETE` | `/api/threads/:id` | Delete thread |

#### Implementation

<Tabs items={['Next.js', 'Express']}>
<Tab value="Next.js">
```typescript
// app/api/threads/route.ts
export async function GET() {
  const threads = await db.thread.findMany({
    orderBy: { updatedAt: 'desc' },
  });
  return Response.json({ threads, total: threads.length, hasMore: false });
}

export async function POST(request: Request) {
  const body = await request.json();
  const thread = await db.thread.create({ data: body });
  return Response.json(thread, { status: 201 });
}
```

```typescript
// app/api/threads/[id]/route.ts

export async function GET(
  request: NextRequest,
  { params }: { params: Promise<{ id: string }> }
) {
  const { id } = await params;
  const thread = await db.thread.findUnique({ where: { id } });
  if (!thread) return Response.json({ error: 'Not found' }, { status: 404 });
  return Response.json(thread);
}

export async function PATCH(
  request: NextRequest,
  { params }: { params: Promise<{ id: string }> }
) {
  const { id } = await params;
  const updates = await request.json();
  const thread = await db.thread.update({ where: { id }, data: updates });
  return Response.json(thread);
}

export async function DELETE(
  request: NextRequest,
  { params }: { params: Promise<{ id: string }> }
) {
  const { id } = await params;
  await db.thread.delete({ where: { id } });
  return new Response(null, { status: 204 });
}
```
</Tab>

<Tab value="Express">
```typescript
const router = Router();

router.get('/', async (req, res) => {
  const threads = await db.thread.findMany();
  res.json({ threads, total: threads.length, hasMore: false });
});

router.post('/', async (req, res) => {
  const thread = await db.thread.create({ data: req.body });
  res.status(201).json(thread);
});

router.get('/:id', async (req, res) => {
  const thread = await db.thread.findUnique({ where: { id: req.params.id } });
  if (!thread) return res.status(404).json({ error: 'Not found' });
  res.json(thread);
});

router.patch('/:id', async (req, res) => {
  const thread = await db.thread.update({
    where: { id: req.params.id },
    data: req.body,
  });
  res.json(thread);
});

router.delete('/:id', async (req, res) => {
  await db.thread.delete({ where: { id: req.params.id } });
  res.status(204).send();
});

export default router;
```
</Tab>
</Tabs>

---

## useThreadManager Hook

Access thread management functions directly for custom UIs:

```tsx

function CustomThreadList() {
  const {
    threads,           // All threads
    currentThread,     // Currently active thread
    currentThreadId,   // Current thread ID
    isLoading,         // Loading state
    createThread,      // Create new thread
    switchThread,      // Switch to a thread
    deleteThread,      // Delete a thread
    updateCurrentThread, // Update current thread
  } = useThreadManager();

  return (
    <div>
      {threads.map(thread => (
        <div key={thread.id}>
          <span onClick={() => switchThread(thread.id)}>
            {thread.title || 'Untitled'}
          </span>
          <button onClick={() => deleteThread(thread.id)}>Delete</button>
        </div>
      ))}
      <button onClick={() => createThread()}>New Thread</button>
    </div>
  );
}
```

### Thread Object

```typescript
interface Thread {
  id: string;
  title?: string;
  preview?: string;
  messageCount?: number;
  createdAt?: Date;
  updatedAt?: Date;
  messages?: Message[];
}
```

---

## Custom Adapters

Create custom storage adapters for any backend:

```tsx

const customAdapter: ThreadStorageAdapter = {
  async getThreads() {
    const response = await fetch('/api/my-threads');
    return response.json();
  },
  async getThread(id) {
    const response = await fetch(`/api/my-threads/${id}`);
    return response.json();
  },
  async createThread(thread) {
    const response = await fetch('/api/my-threads', {
      method: 'POST',
      body: JSON.stringify(thread),
    });
    return response.json();
  },
  async updateThread(id, updates) {
    const response = await fetch(`/api/my-threads/${id}`, {
      method: 'PATCH',
      body: JSON.stringify(updates),
    });
    return response.json();
  },
  async deleteThread(id) {
    await fetch(`/api/my-threads/${id}`, { method: 'DELETE' });
  },
};

// Use with hook
const threadManager = useThreadManager({ adapter: customAdapter });

// Or use built-in server adapter

const serverAdapter = createServerAdapter({
  endpoint: '/api/threads',
  headers: { Authorization: `Bearer ${token}` },
});
```

---

## ChatWelcome Component

Display a welcome screen when starting a new conversation, with suggestions and recent chat history:

```tsx

function WelcomeScreen() {
  const { sendMessage, threads, switchThread } = useCopilot();

  return (
    <ChatWelcome
      config={{
        title: "How can I help you today?",
        subtitle: "Ask anything and get it done.",
        logo: "/logo.png",
        showRecentChats: true,
        maxRecentChats: 3,
      }}
      suggestions={[
        "Help me write an email",
        "Explain this code",
        "Create a marketing plan",
      ]}
      recentThreads={threads}
      onSendMessage={sendMessage}
      onSelectThread={switchThread}
    />
  );
}
```

### ChatWelcome Props

| Prop | Type | Description |
|------|------|-------------|
| `config` | `WelcomeConfig` | Title, subtitle, logo, and display settings |
| `suggestions` | `string[]` | Clickable suggestion prompts |
| `recentThreads` | `Thread[]` | Recent conversations to display |
| `onSendMessage` | `(message, attachments?) => void` | Called when user sends a message |
| `onSelectThread` | `(threadId) => void` | Called when user selects a thread |
| `onDeleteThread` | `(threadId) => void` | Called when user deletes a thread |
| `attachmentsEnabled` | `boolean` | Enable file attachments (default: true) |

### WelcomeConfig

```typescript
interface WelcomeConfig {
  title?: string;           // Main heading
  subtitle?: string;        // Subheading
  logo?: string;            // Logo image URL
  showRecentChats?: boolean; // Show recent threads
  recentChatsLabel?: string; // Label for recent chats section
  maxRecentChats?: number;   // Max threads to show (default: 3)
  suggestionsLabel?: string; // Label for suggestions
}
```

---

## Related

- [Compaction](/docs/context/compaction) — how the session is summarized
- [Token Tracking](/docs/context/token-tracking) — monitor context window usage

---

## Copilot UI
URL: https://copilot-sdk.yourgpt.ai/docs/chat/ui
Description: Pre-built chat components and styling setup

The SDK provides production-ready chat UI components that work out of the box. This page covers the base setup and available themes.

---

## Quick Setup

```tsx

export default function App() {
  return <CopilotChat className="h-full" />;
}
```

---

## Configure Tailwind

The SDK uses Tailwind CSS utility classes. Add the SDK source path to your CSS based on your project structure:

| CSS file location | @source path |
|-------------------|--------------|
| `app/globals.css` | `@source "../node_modules/@yourgpt/copilot-sdk/dist/**/*.{js,ts,jsx,tsx}";` |
| `src/app/globals.css` | `@source "../../node_modules/@yourgpt/copilot-sdk/dist/**/*.{js,ts,jsx,tsx}";` |
| `globals.css` (root) | `@source "node_modules/@yourgpt/copilot-sdk/dist/**/*.{js,ts,jsx,tsx}";` |

---

## Styling Options

Choose the approach that fits your project:

<Tabs items={['With shadcn/ui', 'Without shadcn/ui', 'Tailwind v3']}>
  <Tab value="With shadcn/ui">
    If you have shadcn/ui configured, just add the SDK source path. The SDK works automatically with your existing CSS variables.

    ```css title="app/globals.css"
    @import "tailwindcss";

    @source "../node_modules/@yourgpt/copilot-sdk/dist/**/*.{js,ts,jsx,tsx}";

    @custom-variant dark (&:is(.dark *));

    /* Your existing shadcn/ui @theme and variables... */
    ```

    ```tsx
    import { CopilotChat } from "@yourgpt/copilot-sdk/ui";

    // Works automatically with your shadcn/ui variables
    <CopilotChat />
    ```
  </Tab>

  <Tab value="Without shadcn/ui">
    If you don't have shadcn/ui, import the SDK's base styles and add the theme mapping:

    **1. Import base styles:**

    ```tsx
    import "@yourgpt/copilot-sdk/ui/styles.css";
    import { CopilotChat } from "@yourgpt/copilot-sdk/ui";

    <CopilotChat />
    ```

    **2. Add Tailwind config:**

    ```css title="app/globals.css"
    @import "tailwindcss";

    @source "../node_modules/@yourgpt/copilot-sdk/dist/**/*.{js,ts,jsx,tsx}";

    @custom-variant dark (&:is(.dark *));

    /* Map CSS variables to Tailwind theme (required for Tailwind v4) */
    @theme inline {
      --color-background: var(--background);
      --color-foreground: var(--foreground);
      --color-card: var(--card);
      --color-card-foreground: var(--card-foreground);
      --color-popover: var(--popover);
      --color-popover-foreground: var(--popover-foreground);
      --color-primary: var(--primary);
      --color-primary-foreground: var(--primary-foreground);
      --color-secondary: var(--secondary);
      --color-secondary-foreground: var(--secondary-foreground);
      --color-muted: var(--muted);
      --color-muted-foreground: var(--muted-foreground);
      --color-accent: var(--accent);
      --color-accent-foreground: var(--accent-foreground);
      --color-destructive: var(--destructive);
      --color-border: var(--border);
      --color-input: var(--input);
      --color-ring: var(--ring);
      --radius-sm: calc(var(--radius) - 4px);
      --radius-md: calc(var(--radius) - 2px);
      --radius-lg: var(--radius);
      --radius-xl: calc(var(--radius) + 4px);
    }

    @layer base {
      * {
        @apply border-border;
      }
      body {
        @apply bg-background text-foreground;
      }
    }
    ```

    <Callout type="info">
    The `@theme inline` block is **required** for Tailwind v4 to map CSS variables to utility classes like `bg-background`.
    </Callout>
  </Tab>

  <Tab value="Tailwind v3">
    Add the SDK package to your Tailwind config content paths:

    ```js title="tailwind.config.js"
    /** @type {import('tailwindcss').Config} */
    module.exports = {
      content: [
        './app/**/*.{js,ts,jsx,tsx,mdx}',
        './components/**/*.{js,ts,jsx,tsx,mdx}',
        './node_modules/@yourgpt/copilot-sdk/dist/**/*.{js,ts,jsx,tsx}',
      ],
      theme: {
        extend: {},
      },
      plugins: [],
    };
    ```

    Then import base styles:

    ```tsx
    import "@yourgpt/copilot-sdk/ui/styles.css";
    import { CopilotChat } from "@yourgpt/copilot-sdk/ui";

    <CopilotChat />
    ```
  </Tab>
</Tabs>

---

## Theme Presets

The SDK includes 8 pre-built themes. Import a theme CSS file and wrap your component:

```tsx

<div className="csdk-theme-claude">
  <CopilotChat />
</div>
```

### Available Themes

| Theme | Import | Class | Style |
|-------|--------|-------|-------|
| **Claude** | `themes/claude.css` | `csdk-theme-claude` | Warm terra cotta, earthy |
| **Vercel** | `themes/vercel.css` | `csdk-theme-vercel` | Monochrome, minimal |
| **Supabase** | `themes/supabase.css` | `csdk-theme-supabase` | Green, developer-focused |
| **Twitter** | `themes/twitter.css` | `csdk-theme-twitter` | Bold blue, rounded |
| **Linear** | `themes/linear.css` | `csdk-theme-linear` | Purple, sophisticated |
| **PostHog** | `themes/posthog.css` | `csdk-theme-posthog` | Yellow NeoBrutalism |
| **Catppuccin** | `themes/catppuccin.css` | `csdk-theme-catppuccin` | Pastel community theme |
| **Modern** | `themes/modern-minimal.css` | `csdk-theme-modern` | Clean tech blue |

---

## Dark Mode

Themes automatically support dark mode when the `dark` class is on an ancestor element:

```tsx
// Works with next-themes, etc.
<html className="dark">
  <body>
    <div className="csdk-theme-claude">
      <CopilotChat />
    </div>
  </body>
</html>
```

---

## Loader Variants

Customize the loading indicator shown when AI is generating a response:

```tsx
<CopilotChat loaderVariant="typing" />
```

### Available Variants

| Variant | Description |
|---------|-------------|
| `typing` | Typing indicator dots (default) |
| `dots` | Bouncing dots |
| `wave` | Wave animation |
| `terminal` | Terminal cursor blink |
| `text-blink` | Blinking "Thinking" text |
| `text-shimmer` | Shimmer effect "Thinking" text |
| `loading-dots` | "Thinking..." with animated dots |

### Text-based Loaders

The text-based variants (`text-blink`, `text-shimmer`, `loading-dots`) display "Thinking" text with animations:

```tsx
// Blinking text
<CopilotChat loaderVariant="text-blink" />

// Shimmer effect
<CopilotChat loaderVariant="text-shimmer" />

// "Thinking..." with animated dots
<CopilotChat loaderVariant="loading-dots" />
```

---

## Avatars

Customize the avatars shown next to messages:

### Basic Usage

```tsx
<CopilotChat
  assistantAvatar={{
    src: "/bot-avatar.png",
    fallback: "AI"
  }}
  userAvatar={{
    src: "/user-avatar.png",
    fallback: "U"
  }}
  showUserAvatar  // Enable user avatar display
/>
```

### Custom Avatar Component

Pass a custom React component for full control:

```tsx
<CopilotChat
  assistantAvatar={{
    component: (
      <img
        src="/custom-bot.svg"
        className="size-full rounded-full"
      />
    )
  }}
  userAvatar={{
    component: <MyUserAvatar />
  }}
  showUserAvatar
/>
```

### Avatar Props

| Prop | Type | Description |
|------|------|-------------|
| `src` | `string` | Image URL |
| `fallback` | `string` | Text shown while image loads or if it fails |
| `component` | `ReactNode` | Custom component (overrides src/fallback) |

<Callout type="info">
User avatars are hidden by default. Set `showUserAvatar` to display them.
</Callout>

---

## Pre-built Components

The SDK exports these ready-to-use components:

| Component | Description |
|-----------|-------------|
| `CopilotChat` | Full chat interface with messages, input, and history |
| `CopilotChatCompound` | Composable chat with slots for header, footer, etc. |
| `Message` | Single message display |
| `PromptInput` | Text input with send button |
| `CodeBlock` | Syntax-highlighted code display |
| `ModelSelector` | Dropdown to switch AI models |
| `ThreadPicker` | Conversation history selector |

### Basic Usage

```tsx
import {
  CopilotChat,
  CopilotChatCompound,
  Message,
  PromptInput
} from "@yourgpt/copilot-sdk/ui";

// Simple - use CopilotChat
<CopilotChat />

// Advanced - use compound components
<CopilotChatCompound>
  <CopilotChatCompound.Header>
    <h1>My Assistant</h1>
  </CopilotChatCompound.Header>
  <CopilotChatCompound.Messages />
  <CopilotChatCompound.Input />
</CopilotChatCompound>
```

---

---

## Message Actions

Add floating copy, edit, feedback, and custom buttons to messages. Actions appear on hover below each message bubble.

```tsx
<CopilotChat>
  <CopilotChat.MessageActions role="assistant">
    <CopilotChat.CopyAction />
    <CopilotChat.FeedbackAction
      onFeedback={(message, type) => sendFeedback({ messageId: message.id, type })}
    />
  </CopilotChat.MessageActions>

  <CopilotChat.MessageActions role="user">
    <CopilotChat.EditAction />
  </CopilotChat.MessageActions>
</CopilotChat>
```

| Component | Description |
|-----------|-------------|
| `CopilotChat.MessageActions` | Registers actions for a role (`user` or `assistant`) |
| `CopilotChat.CopyAction` | Copy message to clipboard |
| `CopilotChat.EditAction` | Inline edit for user messages |
| `CopilotChat.FeedbackAction` | Thumbs up / down |
| `CopilotChat.Action` | Fully custom action button |

```tsx
// Custom action
<CopilotChat.MessageActions role="assistant">
  <CopilotChat.CopyAction />
  <CopilotChat.Action
    icon={<ShareIcon />}
    tooltip="Share"
    onClick={({ message }) => share(message.content)}
  />
</CopilotChat.MessageActions>

// Conditional — hide based on message content
<CopilotChat.Action
  icon={<FlagIcon />}
  tooltip="Report"
  hidden={({ message }) => !message.content}
  onClick={({ message }) => report(message.id)}
/>
```

### Props

```tsx
// MessageActions
role: "user" | "assistant"

// CopyAction / EditAction
tooltip?: string
className?: string

// FeedbackAction
onFeedback?: (message: ChatMessage, type: "helpful" | "not-helpful") => void
tooltip?: string

// Action (custom)
icon: ReactNode
tooltip: string
onClick: (props: { message: ChatMessage }) => void
hidden?: boolean | ((props: { message: ChatMessage }) => boolean)
```

<Callout type="info">
If no `MessageActions` children are declared, the chat UI is identical to before — purely additive.
</Callout>

---

## Next Steps

- [Customizations](/docs/customizations) - Create custom themes, CSS classes, branding
- [Generative UI](/docs/chat/generative-ui) - Render custom components from AI
- [Branching](/docs/advanced/branching) - Conversation branching and edit history

---

## UI Primitives
URL: https://copilot-sdk.yourgpt.ai/docs/customizations/chat-primitives
Description: Headless building blocks for composing fully custom chat UIs

<Callout type="warn">
**Beta** — This feature is in **alpha**. APIs may change before stable release.
</Callout>

Low-level building blocks for composing custom chat UIs. The SDK handles all state, streaming, and context — you control the layout.

Two complementary APIs:
- **`ChatPrimitives`** — named export of individual components, import under any alias
- **`CopilotChat.*`** — same primitives mounted directly on `CopilotChat` for inline composition

---

## All Primitives

```tsx
```

| Primitive | Description |
|-----------|-------------|
| `Chat.MessageList` | Render-prop message list — reads `messages` from context |
| `Chat.DefaultMessage` | Full SDK message bubble — use as fallback in custom lists |
| `Chat.Header` | Chat header bar |
| `Chat.Welcome` | Welcome screen shown when there are no messages |
| `Chat.Input` | Composer / input box |
| `Chat.ScrollAnchor` | Auto-scroll anchor, place at end of message list |
| `Chat.Message` | Low-level message row wrapper |
| `Chat.MessageAvatar` | Avatar with fallback initials |
| `Chat.MessageContent` | Content bubble — renders markdown, supports streaming |
| `Chat.MessageActions` | Action bar layout primitive (wraps action buttons) |
| `Chat.MessageAction` | Single action icon button with tooltip |
| `Chat.Loader` | Streaming / thinking indicator |

---

## `Chat.MessageList` props

```ts
interface MessageListProps {
  children?: (message: ChatMessage, index: number) => React.ReactNode;
  className?: string;
}
```

When `children` is provided, called once per message — return your custom component or fall back to `Chat.DefaultMessage`. When omitted, renders all messages with `DefaultMessage`.

---

## Examples

### Custom message type with fallback

```tsx

<CopilotChat>
  <Chat.MessageList>
    {(message) =>
      message.metadata?.type === "plan" ? (
        <PlanCard key={message.id} message={message} />
      ) : (
        <Chat.DefaultMessage key={message.id} message={message} />
      )
    }
  </Chat.MessageList>
</CopilotChat>
```

### Fully custom layout — compose from scratch

```tsx

<CopilotChat>
  <div className="flex flex-col h-full">
    <Chat.Header />
    <Chat.Welcome />

    <div className="flex-1 overflow-y-auto px-4">
      <Chat.MessageList>
        {(message) => (
          <Chat.Message key={message.id} message={message}>
            <Chat.MessageAvatar message={message} />
            <Chat.MessageContent message={message} />
          </Chat.Message>
        )}
      </Chat.MessageList>
      <Chat.Loader />
      <Chat.ScrollAnchor />
    </div>

    <Chat.Input />
  </div>
</CopilotChat>
```

### Mix primitives with message actions

```tsx

<CopilotChat>
  {/* Register floating action buttons */}
  <CopilotChat.MessageActions role="assistant">
    <CopilotChat.CopyAction />
    <CopilotChat.FeedbackAction onFeedback={(msg, type) => log(msg.id, type)} />
  </CopilotChat.MessageActions>

  {/* Custom message list */}
  <Chat.MessageList>
    {(message) =>
      message.metadata?.type === "approval" ? (
        <ApprovalCard key={message.id} message={message} />
      ) : (
        <Chat.DefaultMessage key={message.id} message={message} />
      )
    }
  </Chat.MessageList>
</CopilotChat>
```

### Per-message action buttons using primitives directly

```tsx

<Chat.MessageList>
  {(message) => (
    <Chat.Message key={message.id} message={message}>
      <Chat.MessageAvatar message={message} />
      <div className="flex flex-col gap-1">
        <Chat.MessageContent message={message} />
        <Chat.MessageActions>
          <Chat.MessageAction
            icon={<CopyIcon />}
            tooltip="Copy"
            onClick={() => navigator.clipboard.writeText(message.content ?? "")}
          />
        </Chat.MessageActions>
      </div>
    </Chat.Message>
  )}
</Chat.MessageList>
```

---

## `messageView` vs `Chat.MessageList`

Two ways to customize message rendering at different abstraction levels:

| | `messageView` prop | `Chat.MessageList` |
|--|--------------------|--------------------|
| Style | Prop on `<CopilotChat>` | Child component inside `<CopilotChat>` |
| Access | `messages[]` + pre-rendered `messageElements[]` | `messages[]` via render-prop |
| When to use | Quick overrides, inject extra UI around existing renders | Full layout control, building from primitives |

Both are non-breaking and can coexist.

→ See [Custom Message View](/docs/customizations/custom-message-view) for the `messageView` API.

---

## Breaking Changes

**None.** Both are purely additive. Existing `<CopilotChat />` usage is untouched.

---

## CSS Class Reference
URL: https://copilot-sdk.yourgpt.ai/docs/customizations/css-classes
Description: Complete list of all csdk-* CSS classes exposed by the SDK for targeting and customization

Every structural element in the SDK has a `csdk-*` class. Target any of them in your own CSS to override colors, spacing, borders, animations, or layout — no specificity hacks needed.

<Callout type="info">
All `csdk-*` classes are **additive only** — they never carry layout-breaking styles on their own. The SDK's visual defaults come from Tailwind utility classes alongside them, which you can override freely.
</Callout>

---

## Messages

| Class | Element | Example override |
|---|---|---|
| `csdk-message` | Every message row (user + assistant + tool) | Entry animation, row spacing |
| `csdk-user-message` | User message row wrapper | Row-level alignment |
| `csdk-assistant-message` | Assistant message row wrapper | Row-level alignment |
| `csdk-message-user` | User message bubble | Background, border radius, padding |
| `csdk-message-assistant` | Assistant message bubble | Background, border, padding |
| `csdk-message-content` | Text content inside a bubble | Font size, line height, color |
| `csdk-message-actions` | Hover-reveal action button bar | Positioning, visibility timing |

```css
/* Example: custom user bubble */
.csdk-message-user {
  background: linear-gradient(135deg, #6366f1, #8b5cf6);
  border-radius: 1rem 1rem 0.25rem 1rem;
}

/* Example: tighten row spacing */
.csdk-message {
  margin-bottom: 0.25rem;
}
```

---

## Avatars

| Class | Element | Example override |
|---|---|---|
| `csdk-avatar` | Avatar container (user & assistant) | Size, border, shadow |
| `csdk-avatar-fallback` | Fallback initials shown when no image | Color, font |

```css
.csdk-avatar {
  width: 2rem;
  height: 2rem;
  border: 2px solid var(--primary);
}
```

---

## Input

| Class | Element | Example override |
|---|---|---|
| `csdk-input` | Input container (the whole bar) | Border, background, border-radius |
| `csdk-input-textarea` | The `<textarea>` inside the input | Font size, color, placeholder style |
| `csdk-button` | All buttons in the chat | Base button reset |
| `csdk-button-send` | Send message button | Color, size, icon |
| `csdk-button-stop` | Stop generation button | Color, icon |
| `csdk-button-attach` | Attachment picker button | Color, icon |
| `csdk-compound-input` | Compound input wrapper | Outer border, padding |
| `csdk-compound-suggestions` | Suggestions dropdown inside compound input | Background, shadow, border |

```css
/* Example: pill-shaped input */
.csdk-input {
  border-radius: 999px;
  padding: 0.25rem 0.75rem;
}

/* Example: custom send button color */
.csdk-button-send {
  background: #10b981;
  color: white;
}
```

---

## Inline Edit

These appear when a user edits a sent message.

| Class | Element | Example override |
|---|---|---|
| `csdk-edit-btn` | Edit trigger button (hover-reveal, left of message) | Position, opacity timing |
| `csdk-edit-textarea` | Textarea shown during edit mode | Border, background |
| `csdk-edit-cancel` | Cancel edit button | Color, border |
| `csdk-edit-submit` | Submit edit button | Color, background |

```css
/* Always show edit button instead of hover-only */
.csdk-edit-btn {
  opacity: 1 !important;
}
```

---

## Confirmation Card

Used for tool approval prompts (`PermissionConfirmation`, `SimpleConfirmation`).

| Class | Element | Example override |
|---|---|---|
| `csdk-confirm-card` | The pending confirmation card | Border, background, border-radius |
| `csdk-confirm-btn` | Deny / Allow buttons | Padding, border-radius, hover state |
| `csdk-confirm-result` | Approved / Rejected result pill | Background, border, color |

```css
/* Example: match your brand on the Allow button */
.csdk-confirm-btn:last-child {
  background: #6366f1;
}

/* Example: custom approved pill */
.csdk-confirm-result {
  border-radius: 0.375rem;
}
```

---

## Layout

| Class | Element | Example override |
|---|---|---|
| `csdk-chat-header` | Chat view header bar | Height, background, border |
| `csdk-chat-footer` | Chat view footer area | Background, padding, border |
| `csdk-chat-home-view` | Home/welcome view container | Background, padding |
| `csdk-chat-view` | Active conversation view container | Background |
| `csdk-back-button` | Back / New chat button in header | Size, icon color |
| `csdk-scroll-btn-layer` | Invisible layer that positions the scroll-to-bottom button | `pointer-events: none` layer — adjust padding to reposition button |

```css
/* Example: transparent footer */
.csdk-chat-footer {
  background: transparent;
  border-top: none;
}
```

---

## Overlays

These are absolutely or fixed-positioned layers. Target them to change colors, z-index, or backdrop styles.

| Class | Element | Example override |
|---|---|---|
| `csdk-image-backdrop` | Fullscreen backdrop behind expanded image | Background color, z-index |
| `csdk-image-close` | Close button inside the image lightbox | Position, background, size |
| `csdk-dropzone-overlay` | Drag-and-drop overlay shown while dragging files | Border color, background tint |
| `csdk-attachment-loading` | Loading overlay on attachment thumbnail | Background opacity |
| `csdk-attachment-error` | Error overlay on failed attachment | Background tint |
| `csdk-mcp-loading` | Loading overlay inside an MCP UI frame | Background, z-index |

```css
/* Example: darker image backdrop */
.csdk-image-backdrop {
  background: rgba(0, 0, 0, 0.92);
}

/* Example: brand-colored drop zone */
.csdk-dropzone-overlay {
  background: color-mix(in srgb, var(--primary) 10%, transparent);
  border-color: var(--primary);
}
```

---

## Follow-up Suggestions

| Class | Element | Example override |
|---|---|---|
| `csdk-followup` | Follow-up suggestions container | Layout, spacing, max-width |
| `csdk-followup-button` | Individual suggestion chip buttons | Color, border, hover state |

```css
.csdk-followup-button {
  border-radius: 999px;
  font-size: 0.75rem;
}
```

---

## Navigation

| Class | Element | Example override |
|---|---|---|
| `csdk-branch-navigator` | Branch/version navigator between message variants | Visibility, sizing |

---

## Model Selector

| Class | Element | Example override |
|---|---|---|
| `csdk-model-dropdown` | Dropdown list shown when picking a model | Width, max-height, shadow, border |

```css
.csdk-model-dropdown {
  border-radius: 0.75rem;
  box-shadow: 0 8px 24px rgba(0, 0, 0, 0.12);
}
```

---

## Dev Tools

These classes are on the `DevLogger` component, which is only rendered in development mode.

| Class | Element |
|---|---|
| `csdk-devlogger-backdrop` | Modal backdrop overlay |
| `csdk-devlogger-modal` | Modal content panel |

---

## CSS Custom Properties

A few SDK-specific CSS variables complement the standard shadcn/ui variables:

| Variable | Default | Used for |
|---|---|---|
| `--csdk-link-color` | `#2563eb` (light) / `#60a5fa` (dark) | Hyperlink color inside message content |
| `--csdk-dialog-foreground` | Inherited from `--foreground` | Text color inside SDK-rendered dialogs |
| `--csdk-dialog-muted-foreground` | Inherited from `--muted-foreground` | Muted text inside SDK-rendered dialogs |

```css
:root {
  --csdk-link-color: #7c3aed; /* purple links */
}
```

---

## Animation Classes (Internal)

These classes are applied internally for loader animations. You can target them to adjust timing or disable animations, but they are not intended as customization hooks.

`csdk-spinner-fade` · `csdk-thin-pulse` · `csdk-pulse-dot` · `csdk-bounce-dots` · `csdk-typing` · `csdk-wave` · `csdk-blink` · `csdk-text-blink` · `csdk-shimmer` · `csdk-loading-dots`

```css
/* Example: disable all SDK loader animations for reduced motion */
@media (prefers-reduced-motion: reduce) {
  [class*="csdk-loader"] {
    animation: none;
  }
}
```

---

## Full Theme Example

Combining CSS variables + class overrides to create a fully custom look:

```css title="themes/my-brand.css"
[data-csdk-theme="mybrand"] {
  --primary: hsl(258 90% 60%);
  --primary-foreground: hsl(0 0% 100%);
  --background: hsl(258 20% 98%);
  --border: hsl(258 20% 88%);
  --radius: 0.75rem;
  --csdk-link-color: hsl(258 90% 55%);
}

/* Pill-shaped input */
[data-csdk-theme="mybrand"] .csdk-input {
  border-radius: 999px;
}

/* Gradient user bubbles */
[data-csdk-theme="mybrand"] .csdk-message-user {
  background: linear-gradient(135deg, hsl(258 90% 60%), hsl(280 80% 60%));
  color: white;
}

/* Rounded suggestion chips */
[data-csdk-theme="mybrand"] .csdk-followup-button {
  border-radius: 999px;
  border-color: hsl(258 60% 80%);
  color: hsl(258 90% 50%);
}
```

```tsx

<div data-csdk-theme="mybrand">
  <CopilotChat />
</div>
```

---

## Custom Message View
URL: https://copilot-sdk.yourgpt.ai/docs/customizations/custom-message-view
Description: Full control over how the message list is rendered via the messageView prop

<Callout type="warn">
**Beta** — This feature is in **alpha**. APIs may change before stable release.
</Callout>

The `messageView` prop on `<CopilotChat>` intercepts message list rendering. Inject custom UI, conditionally replace messages based on `metadata.type`, or build entirely custom layouts — without touching roles or message history.

---

## API

```ts
messageView?: {
  children?: (props: {
    /** Raw messages array */
    messages: ChatMessage[];
    /** Pre-rendered default SDK elements, one per message */
    messageElements: React.ReactNode[];
  }) => React.ReactNode;
};
```

You receive:
- **`messageElements`** — pre-rendered default SDK elements (one per message, may include `null` for filtered messages)
- **`messages`** — raw `ChatMessage[]` for conditional logic

---

## Examples

### Inject custom UI below messages

```tsx
<CopilotChat
  messageView={{
    children: ({ messageElements }) => (
      <>
        {messageElements}
        <div className="p-4 text-center text-sm text-muted-foreground">
          Powered by YourGPT
        </div>
      </>
    ),
  }}
/>
```

### Custom message types via `metadata.type`

Inject a custom message type (e.g. from a tool handler), then render it with your own component:

```tsx
<CopilotChat
  messageView={{
    children: ({ messages, messageElements }) => (
      <>
        {messages.map((message, i) => {
          if (message.metadata?.type === "plan") {
            return <PlanCard key={message.id} data={message.metadata} />;
          }
          if (message.metadata?.type === "approval") {
            return <ApprovalCard key={message.id} data={message.metadata} />;
          }
          return messageElements[i];
        })}
      </>
    ),
  }}
/>
```

### Combine with agent state

```tsx
function Chat() {
  const agentState = useMyAgentState();

  return (
    <CopilotChat
      messageView={{
        children: ({ messageElements }) => (
          <div className="flex flex-col gap-4">
            {messageElements}
            {agentState?.steps && <TaskProgress steps={agentState.steps} />}
          </div>
        ),
      }}
    />
  );
}
```

---

## `messageView` vs `Chat.MessageList`

| | `messageView` | `Chat.MessageList` |
|--|---------------|---------------------|
| Style | Prop on `<CopilotChat>` | Child component inside `<CopilotChat>` |
| Access | `messages[]` + pre-rendered `messageElements[]` | `messages[]` via render-prop |
| When to use | Quick overrides, inject UI around existing renders | Full layout control, building from scratch |

`messageView` is the simpler option for most cases. Use [Chat Primitives](/docs/customizations/chat-primitives) when you need full layout control.

---

## Breaking Changes

**None.** Fully additive. Existing `renderMessage`, `toolRenderers`, and all other props are unchanged.

---

## Headless Copilot
URL: https://copilot-sdk.yourgpt.ai/docs/customizations/headless
Description: Build fully custom chat UIs using raw SDK primitives — no built-in components required

The SDK ships two layers. The **headless layer** lets you build your own UI from scratch using two low-level primitives — no built-in components involved.

| Layer | What it is | When to use |
|---|---|---|
| UI layer | `<CopilotChat>`, built-in components | Get running fast |
| **Headless layer** | Raw hooks + stream events | Build your own UI |

---

## Primitives

### `useCopilotEvent`

Subscribe to raw stream chunks as they flow through the pipeline.

```ts
import { useCopilotEvent } from '@yourgpt/copilot-sdk/react'

function useCopilotEvent<T extends StreamChunkType | '*'>(
  eventType: T,
  handler: (chunk: ChunkOfType<T>) => void
): void
```

The handler is always called with its **latest** version via a ref — no `useCallback` needed. Resubscribes only when `eventType` changes.

#### Event types

| Event | When | Key fields |
|---|---|---|
| `message:start` | New assistant message begins | `id` |
| `message:delta` | Text token arrives | `content`, `messageId` |
| `message:end` | Message turn complete | `messageId` |
| `thinking:delta` | Reasoning token | `content`, `messageId` |
| `action:start` | Server tool begins | `id`, `name`, `messageId` |
| `action:args` | Tool args streamed | `id`, `args`, `messageId` |
| `action:end` | Server tool completes | `id`, `name`, `result`, `messageId` |
| `tool:status` | Client tool status change | `id`, `name`, `status`, `messageId` |
| `tool:result` | Client tool result | `id`, `name`, `result`, `messageId` |
| `source:add` | Knowledge source cited | `source`, `messageId` |
| `loop:iteration` | Agent loop step | `iteration`, `maxIterations`, `messageId` |
| `loop:complete` | Agent loop finished | `iterations`, `maxIterationsReached`, `messageId` |
| `*` | Every event | all fields |

---

### `useMessageMeta`

A reactive per-message key-value store. Attach any shape of data to a message ID — every component reading that ID re-renders on write.

```ts
import { useMessageMeta } from '@yourgpt/copilot-sdk/react'

function useMessageMeta<T extends Record<string, unknown>>(
  messageId: string | undefined
): {
  meta: T
  setMeta: (meta: T) => void
  updateMeta: (updater: (prev: T) => T) => void
}
```

Passing `undefined` as `messageId` returns a no-op instance — safe for conditional use. `meta` is always an object, never `null`.

---

## Usage pattern

Write metadata from event handlers, read it in message components:

```tsx
// 1. Write during streaming — use messageMeta store directly from useCopilot()
const { messageMeta } = useCopilot()

useCopilotEvent('thinking:delta', (e) => {
  if (!e.messageId) return
  messageMeta.updateMeta(e.messageId, prev => ({
    ...prev,
    thinking: ((prev.thinking as string) ?? '') + e.content,
  }))
})

useCopilotEvent('action:start', (e) => {
  if (!e.messageId) return
  messageMeta.updateMeta(e.messageId, prev => ({
    ...prev,
    activeTools: { ...(prev.activeTools as object ?? {}), [e.name]: 'running' }
  }))
})

// 2. Read in your message component
interface MyMeta {
  thinking?: string
  activeTools?: Record<string, 'running' | 'done'>
}

function Message({ message }) {
  const { meta } = useMessageMeta<MyMeta>(message.id)

  return (
    <div>
      {meta.thinking && <div className="thinking">{meta.thinking}</div>}
      {Object.entries(meta.activeTools ?? {})
        .filter(([, v]) => v === 'running')
        .map(([name]) => <span key={name}>⚙ {name}</span>)
      }
      <p>{message.content}</p>
    </div>
  )
}
```

<Callout type="info">
Use `messageMeta` from `useCopilot()` inside event handlers (where React hooks can't be called). Use `useMessageMeta(id)` inside components for reactive reads.
</Callout>

---

## Direct store access

For non-component code, access the store imperatively:

```tsx
const { messageMeta } = useCopilot()

messageMeta.getMeta(messageId)
messageMeta.setMeta(messageId, { key: 'value' })
messageMeta.updateMeta(messageId, prev => ({ ...prev, count: (prev.count as number ?? 0) + 1 }))
```

---

## Notes

- Metadata is **in-memory only** — resets when the provider unmounts. Sync to your own storage in event handlers if you need persistence.
- Multiple components can read the same `messageId` — all re-render on any write.
- Handlers in `useCopilotEvent` run synchronously during streaming — keep them fast.

---

## Attachment Primitives

Build custom file upload UIs with the `useAttachments` hook and companion components.

### `useAttachments`

Core hook for file upload management — handles validation, upload progress, cancellation, retry, and drag-drop.

```tsx

function MyCustomInput() {
  const { send } = useCopilotChatContext();

  const {
    attachments,           // PendingAttachment[] — current files
    addFiles,              // (files: FileList | File[]) => void
    removeAttachment,      // (id: string) => void
    cancelUpload,          // (id: string) => void
    retryUpload,           // (id: string) => void
    clearAll,              // () => void
    getReadyAttachments,   // () => MessageAttachment[]
    hasAttachments,        // boolean
    isUploading,           // boolean
    canSend,               // boolean (has ready files, none uploading)
    dragHandlers,          // spread on container for drag-drop
    isDragging,            // boolean
    openFilePicker,        // () => void
    fileInputRef,          // ref for hidden <input type="file">
    onFileInputChange,     // onChange handler for file input
  } = useAttachments({
    // Server upload URL (string), URL + options (object), or custom handler (function)
    upload: "/api/copilot/upload",
    maxFiles: 5,                                    // default: 5
    maxFileSize: 10 * 1024 * 1024,                  // default: 10MB
    allowedFileTypes: ["image/*", "application/pdf"], // default
  });

  const handleSend = (text: string) => {
    const files = getReadyAttachments();
    send(text, files.length ? files : undefined);
    clearAll();
  };

  return (
    <div {...dragHandlers} className="relative">
      <DropZoneOverlay isDragging={isDragging} />
      <AttachmentStrip
        attachments={attachments}
        onRemove={removeAttachment}
        onRetry={retryUpload}
      />
      <textarea ... />
      <button onClick={openFilePicker}>Attach</button>
      <input ref={fileInputRef} type="file" hidden multiple onChange={onFileInputChange} />
      <button onClick={() => handleSend(text)}>Send</button>
    </div>
  );
}
```

#### Config

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `upload` | `string \| object \| function` | — | Upload handler (see [Attachments](/docs/attachments)) |
| `maxFiles` | `number` | `5` | Maximum concurrent files |
| `maxFileSize` | `number` | `10MB` | Max file size in bytes |
| `allowedFileTypes` | `string[]` | `["image/*", "application/pdf", ...]` | Allowed MIME types |

#### PendingAttachment

Each item in the `attachments` array:

```ts
{
  id: string;
  file: File;
  preview?: string;       // object URL for image thumbnails
  status: "uploading" | "ready" | "error";
  progress: number;       // 0-100
  error?: string;
  attachment?: MessageAttachment; // final result when ready
}
```

### `AttachmentStrip`

Compact horizontal strip showing pending attachments. Each file shows a thumbnail (images) or type icon, filename, upload progress bar, and remove/retry button.

```tsx
<AttachmentStrip
  attachments={attachments}
  onRemove={removeAttachment}
  onRetry={retryUpload}
  className="mb-2"
/>
```

### `DropZoneOverlay`

Overlay that appears when files are dragged over the container. Spread `dragHandlers` from `useAttachments` on the parent element.

```tsx
<div {...dragHandlers} className="relative">
  <DropZoneOverlay isDragging={isDragging} />
  {/* your input */}
</div>
```

---

## Customizations
URL: https://copilot-sdk.yourgpt.ai/docs/customizations
Description: Create custom themes, extend components, and brand your copilot

Extend the SDK's UI with custom themes, CSS overrides, and branding options.

<Callout type="info">
For base setup and pre-built themes, see [UI Components](/docs/ui).
</Callout>

---

## CSS Variables Reference

The SDK uses standard shadcn/ui CSS variables. Override these to customize the look:

```css
:root {
  /* Background colors */
  --background: hsl(0 0% 100%);
  --foreground: hsl(0 0% 0%);

  /* Card/panel colors */
  --card: hsl(0 0% 100%);
  --card-foreground: hsl(0 0% 0%);

  /* Primary action color */
  --primary: hsl(220 90% 50%);
  --primary-foreground: hsl(0 0% 100%);

  /* Secondary elements */
  --secondary: hsl(220 10% 95%);
  --secondary-foreground: hsl(0 0% 0%);

  /* Muted/subtle elements */
  --muted: hsl(220 10% 95%);
  --muted-foreground: hsl(0 0% 45%);

  /* Accent highlights */
  --accent: hsl(220 10% 95%);
  --accent-foreground: hsl(0 0% 0%);

  /* Destructive actions */
  --destructive: hsl(0 84% 60%);
  --destructive-foreground: hsl(0 0% 100%);

  /* Borders and inputs */
  --border: hsl(220 10% 90%);
  --input: hsl(220 10% 90%);
  --ring: hsl(220 90% 50%);

  /* Border radius */
  --radius: 0.5rem;
}

.dark {
  --background: hsl(0 0% 5%);
  --foreground: hsl(0 0% 95%);
  /* ... dark mode overrides */
}
```

---

## Semantic CSS Classes

Every structural element in the SDK exposes a `csdk-*` class for CSS targeting. See the full reference:

➜ [CSS Class Reference](/docs/customizations/css-classes) — complete list of all `csdk-*` classes with descriptions and override examples.

---

## Creating Custom Themes

### 1. Create Theme File

```css title="themes/my-brand.css"
.csdk-theme-mybrand,
[data-csdk-theme="mybrand"] {
  /* Colors */
  --background: hsl(210 20% 98%);
  --foreground: hsl(210 40% 10%);
  --primary: hsl(210 100% 50%);
  --primary-foreground: hsl(0 0% 100%);
  --secondary: hsl(210 20% 94%);
  --secondary-foreground: hsl(210 40% 10%);
  --muted: hsl(210 20% 94%);
  --muted-foreground: hsl(210 20% 40%);
  --accent: hsl(210 100% 95%);
  --accent-foreground: hsl(210 100% 40%);
  --border: hsl(210 20% 88%);
  --input: hsl(210 20% 88%);
  --ring: hsl(210 100% 50%);

  /* Border radius */
  --radius: 0.75rem;
}

/* Dark mode variant */
.dark.csdk-theme-mybrand,
.dark .csdk-theme-mybrand {
  --background: hsl(210 30% 8%);
  --foreground: hsl(210 20% 95%);
  --primary: hsl(210 100% 60%);
  /* ... */
}
```

### 2. Add Component Overrides

```css title="themes/my-brand.css"
/* Custom message styling */
.csdk-theme-mybrand .csdk-message-user {
  border: 2px solid var(--primary);
  box-shadow: 4px 4px 0 0 var(--primary);
}

/* Rounded send button */
.csdk-theme-mybrand .csdk-button-send {
  border-radius: 50%;
}

/* Custom input styling */
.csdk-theme-mybrand .csdk-input-textarea {
  border-width: 2px;
}
```

### 3. Apply Theme

```tsx

<div className="csdk-theme-mybrand">
  <CopilotChat />
</div>
```

---

## Branding

### Header

```tsx
<CopilotChat
  header={{
    title: 'Support Assistant',
    subtitle: 'How can I help you today?',
    logo: '/logo.svg',
  }}
/>
```

### Welcome Message

```tsx
<CopilotChat
  welcomeMessage="Hi! I'm your AI assistant. Ask me anything about our products."
/>
```

### Placeholder

```tsx
<CopilotChat
  placeholder="Type your question here..."
/>
```

### Avatars

```tsx
<CopilotChat
  userAvatar="/user-avatar.png"
  assistantAvatar="/ai-avatar.png"
/>
```

---

## Layout Options

### Position

```tsx
// Floating button (default)
<CopilotChat position="bottom-right" />

// Embedded in page
<CopilotChat embedded={true} />

// Full page
<CopilotChat fullPage={true} />
```

### Size

```tsx
<CopilotChat
  width={400}
  height={600}
  maxHeight="80vh"
/>
```

---

## Input Options

### Attachments

```tsx
<CopilotChat
  attachmentsEnabled={true}
  allowedFileTypes={['image/*', '.pdf', '.doc']}
  maxFileSize={10 * 1024 * 1024} // 10MB
/>
```

### Voice Input

```tsx
<CopilotChat
  voiceEnabled={true}
/>
```

---

## Behavior

### Auto-focus

```tsx
<CopilotChat
  autoFocus={true}
/>
```

### Persist History

```tsx
<CopilotChat
  persistHistory={true}
  storageKey="my-app-chat"
/>
```

### Scroll Behavior

```tsx
<CopilotChat
  scrollBehavior="smooth" // 'smooth' | 'instant' | 'auto'
/>
```

---

## Custom Message Rendering

```tsx
<CopilotChat
  renderMessage={(message) => (
    <div className="custom-message">
      <Markdown>{message.content}</Markdown>
    </div>
  )}
/>
```

---

## Full Example

```tsx

<div className="csdk-theme-mybrand">
  <CopilotChat
    // Branding
    header={{
      title: 'AI Assistant',
      logo: '/logo.svg',
    }}
    welcomeMessage="How can I help you today?"
    placeholder="Ask anything..."

    // Layout
    position="bottom-right"
    width={400}

    // Features
    attachmentsEnabled={true}
    voiceEnabled={true}
    persistHistory={true}

    // Avatars
    userAvatar="/user.png"
    assistantAvatar="/ai.png"
  />
</div>
```

---

## Next Steps

- [CSS Class Reference](/docs/customizations/css-classes) - All `csdk-*` classes with override examples
- [UI Components](/docs/ui) - Pre-built components and themes
- [Generative UI](/docs/generative-ui) - Render custom components from AI
- [Chat Primitives](/docs/customizations/chat-primitives) - Headless building blocks
- [Custom Message View](/docs/customizations/custom-message-view) - Full control over message rendering

---

## Headless Copilot
URL: https://copilot-sdk.yourgpt.ai/docs/headless
Description: Build fully custom chat UIs using raw SDK primitives — no built-in components required

The Copilot SDK ships two layers:

| Layer | What it is | When to use |
|---|---|---|
| **UI layer** | `<CopilotChat>`, `<CopilotProvider>`, built-in components | Get up and running fast |
| **Headless layer** | Raw hooks, stream events, per-message state | Build your own UI from scratch |

The headless layer gives you full control — your own message bubbles, your own tool indicators, your own thinking step visualiser, your own artifact previews — without forking or overriding SDK internals.

---

## Philosophy

The headless API follows a **primitives, not patterns** approach. Rather than shipping opinionated hooks like `useThinkingSteps()` that bake in a specific data shape, the SDK exposes two low-level primitives that let you compose anything:

- **[`useCopilotEvent`](/docs/headless/use-copilot-event)** — subscribe to every raw stream chunk as it arrives
- **[`useMessageMeta`](/docs/headless/use-message-meta)** — a reactive per-message key-value store you shape yourself

With just these two, you can build thinking step trackers, artifact stores, tool progress badges, plan approval flows, clarifying question UIs — entirely in your own code, with your own types.

---

## Architecture

```
CopilotProvider
├── sends messages → runtime API
├── streams chunks → fires onStreamChunk for each
│     message:delta, thinking:delta, tool:status,
│     action:start/end, loop:iteration, loop:complete …
│
├── useCopilotEvent('thinking:delta', handler)
│     └── your handler runs for each thinking chunk
│
└── useMessageMeta(messageId)
      └── reactive store — write anything, read anywhere
```

---

## Getting started

Install the SDK if you haven't already:

```bash
npm install @yourgpt/copilot-sdk
```

Wrap your app with `CopilotProvider` as normal — the headless hooks work inside any component under the provider:

```tsx
import { CopilotProvider } from '@yourgpt/copilot-sdk/react'

export default function App() {
  return (
    <CopilotProvider runtimeUrl="/api/copilot">
      <YourCustomChatUI />
    </CopilotProvider>
  )
}
```

Then use `useCopilotEvent` and `useMessageMeta` anywhere inside to build whatever you need.

---

## Full example — custom streaming chat

A complete headless chat UI using only SDK primitives:

```tsx
import {
  useCopilot,
  useCopilotEvent,
  useMessageMeta,
} from '@yourgpt/copilot-sdk/react'

// ── Message component ─────────────────────────────────────────────
interface MyMeta {
  thinkingText?: string
  toolsRunning?: string[]
}

function Message({ message }) {
  // Read custom metadata we wrote during streaming
  const { meta } = useMessageMeta<MyMeta>(message.id)

  return (
    <div className={`message ${message.role}`}>
      {/* Thinking indicator */}
      {meta.thinkingText && (
        <div className="thinking">{meta.thinkingText}</div>
      )}

      {/* Active tool badges */}
      {meta.toolsRunning?.map(name => (
        <span key={name} className="tool-badge">⚙ {name}</span>
      ))}

      {/* Message content */}
      <p>{message.content}</p>
    </div>
  )
}

// ── Chat component ────────────────────────────────────────────────
function MyChat() {
  const { messages, sendMessage, status } = useCopilot()
  const [input, setInput] = useState('')

  // Track which message is currently streaming
  const activeMessageId = useRef<string | null>(null)

  // Capture message start
  useCopilotEvent('message:start', (e) => {
    activeMessageId.current = e.id
  })

  // Build thinking text per message
  const { updateMeta: updateActiveMeta } = useMessageMeta(activeMessageId.current ?? undefined)

  useCopilotEvent('thinking:delta', (e) => {
    useMessageMeta — see pattern below for per-message writes
  })

  // Track tool execution
  useCopilotEvent('action:start', (e) => {
    if (!e.messageId) return
    // write to the message's meta store via a child component or ref pattern
  })

  return (
    <div>
      {messages.map(m => <Message key={m.id} message={m} />)}
      <input value={input} onChange={e => setInput(e.target.value)} />
      <button onClick={() => sendMessage(input)}>Send</button>
    </div>
  )
}
```

<Callout type="info">
For writing metadata from event handlers that fire before a component mounts,
use the `messageMeta` store directly from `useCopilot()`:

```tsx
const { messageMeta } = useCopilot()
useCopilotEvent('thinking:delta', (e) => {
  messageMeta.updateMeta(e.messageId!, prev => ({
    ...prev,
    thinkingText: (prev.thinkingText ?? '') + e.content
  }))
})
```
</Callout>

---

## Available stream events

| Event | When it fires | Key fields |
|---|---|---|
| `message:start` | New assistant message begins | `id` |
| `message:delta` | Text token arrives | `content`, `messageId` |
| `message:end` | Message turn complete | `messageId` |
| `thinking:delta` | Thinking/reasoning token | `content`, `messageId` |
| `action:start` | Server tool begins | `id`, `name`, `messageId` |
| `action:args` | Tool args streamed | `id`, `args`, `messageId` |
| `action:end` | Server tool completes | `id`, `name`, `result`, `messageId` |
| `tool:status` | Client tool status change | `id`, `name`, `status`, `messageId` |
| `tool:result` | Client tool result | `id`, `name`, `result`, `messageId` |
| `source:add` | Knowledge base source cited | `source`, `messageId` |
| `loop:iteration` | Agent loop step | `iteration`, `maxIterations`, `messageId` |
| `loop:complete` | Agent loop finished | `iterations`, `maxIterationsReached`, `messageId` |
| `*` | Every event | (all fields) |

---

## Next steps

- [`useCopilotEvent`](/docs/headless/use-copilot-event) — full API reference and recipes
- [`useMessageMeta`](/docs/headless/use-message-meta) — full API reference and recipes
- [Custom Message View](/docs/customizations/custom-message-view) — intercept rendering inside `<CopilotChat>`
- [Chat Primitives](/docs/customizations/chat-primitives) — lower-level layout components

---

## useCopilotEvent
URL: https://copilot-sdk.yourgpt.ai/docs/headless/use-copilot-event
Description: Subscribe to raw stream chunks as they arrive — build any custom real-time UI

`useCopilotEvent` subscribes to the raw stream chunks flowing through the SDK pipeline. Every token, tool call, thinking delta, and loop iteration fires an event — your handler decides what to do with it.

```ts
import { useCopilotEvent } from '@yourgpt/copilot-sdk/react'
```

---

## Signature

```ts
function useCopilotEvent<T extends StreamChunkType | '*'>(
  eventType: T,
  handler: (chunk: ChunkOfType<T>) => void
): void
```

### Parameters

| Parameter | Type | Description |
|---|---|---|
| `eventType` | `StreamChunkType \| '*'` | The event type to listen for, or `'*'` for all |
| `handler` | `(chunk) => void` | Called for each matching chunk. Handler identity is stable via ref — no re-subscription on re-render |

<Callout type="info">
The handler is always called with the **latest** version via a ref — you don't need to wrap it in `useCallback`. The hook only resubscribes when `eventType` changes.
</Callout>

---

## Event types

```ts
type StreamChunkType =
  | 'message:start'      // assistant message begins — { id }
  | 'message:delta'      // text token — { content }
  | 'message:end'        // message turn complete
  | 'thinking:delta'     // reasoning token — { content }
  | 'action:start'       // server tool starts — { id, name, hidden? }
  | 'action:args'        // server tool args streamed — { id, args }
  | 'action:end'         // server tool finishes — { id, name, result?, error? }
  | 'tool:status'        // client tool status — { id, name, status }
  | 'tool:result'        // client tool result — { id, name, result }
  | 'source:add'         // knowledge source cited — { source }
  | 'loop:iteration'     // agent loop step — { iteration, maxIterations }
  | 'loop:complete'      // agent loop done — { iterations, maxIterationsReached? }
  | '*'                  // every event
```

All chunks also include `messageId?: string` — the ID of the assistant message being streamed.

---

## Examples

### Thinking text accumulator

```tsx
function ThinkingDisplay({ messageId }: { messageId: string }) {
  const [thinking, setThinking] = useState('')

  useCopilotEvent('thinking:delta', (e) => {
    if (e.messageId !== messageId) return
    setThinking(prev => prev + e.content)
  })

  if (!thinking) return null
  return <div className="thinking-box">{thinking}</div>
}
```

---

### Tool execution badge

Show a live "Searching…" indicator while a tool runs:

```tsx
function ToolBadge() {
  const [activeTool, setActiveTool] = useState<string | null>(null)

  useCopilotEvent('action:start', (e) => setActiveTool(e.name))
  useCopilotEvent('action:end',   (e) => setActiveTool(null))

  if (!activeTool) return null
  return (
    <div className="tool-badge">
      <Spinner /> {activeTool.replace(/_/g, ' ')}
    </div>
  )
}
```

---

### Agent loop progress bar

```tsx
function LoopProgress() {
  const [progress, setProgress] = useState(0)

  useCopilotEvent('loop:iteration', (e) => {
    setProgress(e.iteration / e.maxIterations)
  })

  useCopilotEvent('loop:complete', () => setProgress(0))

  if (!progress) return null
  return <progress value={progress} max={1} />
}
```

---

### Artifact tracking

Parse `create_artifact` tool results and store them per message:

```tsx
function useArtifactTracker() {
  const { messageMeta } = useCopilot()

  useCopilotEvent('action:end', (e) => {
    if (e.name !== 'create_artifact' || !e.result || !e.messageId) return
    messageMeta.updateMeta(e.messageId, prev => ({
      ...prev,
      artifacts: [...((prev.artifacts as unknown[]) ?? []), e.result]
    }))
  })
}
```

---

### Catch-all debug logger

```tsx
useCopilotEvent('*', (e) => {
  console.log(`[stream] ${e.type}`, e)
})
```

---

### Writing to message meta from event handlers

For writing metadata while streaming (before the message component mounts), use the `messageMeta` store directly from `useCopilot()`:

```tsx
const { messageMeta } = useCopilot()

useCopilotEvent('thinking:delta', (e) => {
  if (!e.messageId) return
  messageMeta.updateMeta(e.messageId, prev => ({
    ...prev,
    thinking: ((prev.thinking as string) ?? '') + e.content
  }))
})
```

Then read it in your message component with [`useMessageMeta`](/docs/headless/use-message-meta).

---

## Notes

- Handlers run **synchronously** during the streaming loop — keep them fast. Defer expensive work with `setTimeout` or `startTransition` if needed.
- The hook is a no-op outside of a `CopilotProvider`.
- Multiple components can subscribe to the same event type independently.

---

## useMessageMeta
URL: https://copilot-sdk.yourgpt.ai/docs/headless/use-message-meta
Description: Reactive per-message custom metadata — attach any data to a message ID and react to changes

`useMessageMeta` is a reactive per-message key-value store. Attach any shape of data to a message ID — any component reading that message ID will re-render when the data changes.

```ts
import { useMessageMeta } from '@yourgpt/copilot-sdk/react'
```

It's the storage layer for the headless system. Pair it with [`useCopilotEvent`](/docs/headless/use-copilot-event) to write data during streaming, then read it in your message components.

---

## Signature

```ts
function useMessageMeta<T extends Record<string, unknown>>(
  messageId: string | undefined
): UseMessageMetaReturn<T>
```

### Parameters

| Parameter | Type | Description |
|---|---|---|
| `messageId` | `string \| undefined` | The message to attach metadata to. Pass `undefined` for a no-op instance (safe for conditional calls) |

### Returns

```ts
interface UseMessageMetaReturn<T> {
  /** Current metadata. Empty object if nothing set yet. */
  meta: T

  /** Replace metadata entirely */
  setMeta: (meta: T) => void

  /** Update metadata with an updater function */
  updateMeta: (updater: (prev: T) => T) => void
}
```

---

## Examples

### Thinking steps

Define your own shape — the SDK doesn't dictate it:

```tsx
interface MyMeta {
  thinking?: string
  isThinking?: boolean
}

// Writer — inside useCopilotEvent handler
const { messageMeta } = useCopilot()

useCopilotEvent('thinking:delta', (e) => {
  if (!e.messageId) return
  messageMeta.updateMeta(e.messageId, prev => ({
    ...prev,
    thinking: ((prev.thinking as string) ?? '') + e.content,
    isThinking: true,
  }))
})

useCopilotEvent('message:end', (e) => {
  messageMeta.updateMeta(e.messageId!, prev => ({
    ...prev,
    isThinking: false,
  }))
})

// Reader — in your message component
function AssistantMessage({ message }) {
  const { meta } = useMessageMeta<MyMeta>(message.id)

  return (
    <div>
      {meta.isThinking && <ThinkingIndicator text={meta.thinking} />}
      <p>{message.content}</p>
    </div>
  )
}
```

---

### Artifact storage

```tsx
interface MyMeta {
  artifacts?: Array<{ type: string; title: string; content: unknown }>
}

// Writer
useCopilotEvent('action:end', (e) => {
  if (e.name !== 'create_artifact' || !e.messageId) return
  messageMeta.updateMeta(e.messageId, prev => ({
    ...prev,
    artifacts: [...((prev.artifacts as unknown[]) ?? []), e.result]
  }))
})

// Reader
function Message({ message }) {
  const { meta } = useMessageMeta<MyMeta>(message.id)

  return (
    <div>
      <p>{message.content}</p>
      {meta.artifacts?.map((a, i) => (
        <ArtifactPreview key={i} artifact={a} />
      ))}
    </div>
  )
}
```

---

### Plan approval state

```tsx
interface MyMeta {
  planStatus?: 'pending' | 'approved' | 'rejected'
  plan?: { summary: string; steps: Step[] }
}

// Writer — called from your tool render function
const { updateMeta } = useMessageMeta<MyMeta>(messageId)
updateMeta(prev => ({ ...prev, planStatus: 'pending', plan: planData }))

// Reader
function Message({ message }) {
  const { meta, updateMeta } = useMessageMeta<MyMeta>(message.id)

  if (meta.planStatus === 'pending') {
    return (
      <PlanCard
        plan={meta.plan}
        onApprove={() => updateMeta(p => ({ ...p, planStatus: 'approved' }))}
        onReject={() => updateMeta(p => ({ ...p, planStatus: 'rejected' }))}
      />
    )
  }

  return <p>{message.content}</p>
}
```

---

### Tool progress per message

```tsx
interface MyMeta {
  activeTools?: Record<string, 'running' | 'done' | 'error'>
}

useCopilotEvent('action:start', (e) => {
  if (!e.messageId) return
  messageMeta.updateMeta(e.messageId, prev => ({
    ...prev,
    activeTools: { ...((prev.activeTools as object) ?? {}), [e.name]: 'running' }
  }))
})

useCopilotEvent('action:end', (e) => {
  if (!e.messageId) return
  messageMeta.updateMeta(e.messageId, prev => ({
    ...prev,
    activeTools: {
      ...((prev.activeTools as object) ?? {}),
      [e.name]: e.error ? 'error' : 'done'
    }
  }))
})

// Reader
function Message({ message }) {
  const { meta } = useMessageMeta<MyMeta>(message.id)
  const running = Object.entries(meta.activeTools ?? {}).filter(([, v]) => v === 'running')

  return (
    <div>
      {running.map(([name]) => <ToolBadge key={name} name={name} />)}
      <p>{message.content}</p>
    </div>
  )
}
```

---

## Using `messageMeta` directly

For writing from event handlers (where a hook can't be called), access the store directly from `useCopilot()`:

```tsx
const { messageMeta } = useCopilot()

// Read
const meta = messageMeta.getMeta(messageId)

// Write
messageMeta.setMeta(messageId, { myKey: 'value' })

// Update
messageMeta.updateMeta(messageId, prev => ({ ...prev, count: (prev.count as number ?? 0) + 1 }))
```

<Callout type="info">
`messageMeta` is the same store instance that `useMessageMeta` reads from — writing via `messageMeta.updateMeta()` will cause all `useMessageMeta(messageId)` consumers for that ID to re-render.
</Callout>

---

## Notes

- `meta` is always an object — never `null` or `undefined`. It starts as `{}`.
- Metadata is **in-memory only** — it resets when the provider unmounts. For persistence, sync to your own storage inside event handlers.
- Passing `undefined` as `messageId` returns a no-op instance — safe to call unconditionally.
- Multiple components can read the same `messageId` — all will re-render on any write.

---

## generateText()
URL: https://copilot-sdk.yourgpt.ai/docs/llm-sdk/generate-text
Description: Generate complete text responses

Generate complete text responses in a single call. Supports tools and multi-step reasoning.

```ts

const result = await generateText({
  model: openai('gpt-4o'),
  prompt: 'Write a haiku about coding.',
});

console.log(result.text);
```

---

## Parameters

```ts
const result = await generateText({
  // Required: Language model to use
  model: openai('gpt-4o'),

  // Content (at least one required)
  prompt: 'Hello',              // Simple prompt
  messages: [...],              // Chat history
  system: 'Be concise.',        // System instruction

  // Optional: Tools for function calling
  tools: { ... },
  maxSteps: 5,                  // Max LLM calls for tool loops

  // Optional: Generation settings
  temperature: 0.7,
  maxTokens: 4096,
  signal: abortController.signal,
});
```

---

## Response Object

```ts
const result = await generateText({ ... });

result.text           // string - Generated text
result.usage          // TokenUsage - { promptTokens, completionTokens, totalTokens }
result.finishReason   // 'stop' | 'length' | 'tool-calls'
result.toolCalls      // ToolCall[] - All tool calls made
result.toolResults    // ToolResult[] - All tool results
result.steps          // GenerateStep[] - Step-by-step breakdown
result.response       // { messages } - Full message history
```

---

## API Route Examples

<Tabs items={['Next.js', 'Node.js']}>
  <Tab value="Next.js">
    ```ts title="app/api/generate/route.ts"
    import { generateText } from '@yourgpt/llm-sdk';
    import { openai } from '@yourgpt/llm-sdk/openai';

    export async function POST(req: Request) {
      const { prompt } = await req.json();

      const result = await generateText({
        model: openai('gpt-4o'),
        system: 'You are a helpful assistant.',
        prompt,
      });

      return Response.json({
        text: result.text,
        usage: result.usage,
      });
    }
    ```
  </Tab>
  <Tab value="Node.js">
    ```ts title="server.ts"
    import { createServer } from 'http';
    import { generateText } from '@yourgpt/llm-sdk';
    import { openai } from '@yourgpt/llm-sdk/openai';

    createServer(async (req, res) => {
      const body = await getBody(req);
      const { prompt } = JSON.parse(body);

      const result = await generateText({
        model: openai('gpt-4o'),
        system: 'You are a helpful assistant.',
        prompt,
      });

      res.writeHead(200, { 'Content-Type': 'application/json' });
      res.end(JSON.stringify({
        text: result.text,
        usage: result.usage,
      }));
    }).listen(3001);

    function getBody(req: any): Promise<string> {
      return new Promise((resolve) => {
        let data = '';
        req.on('data', (chunk: any) => data += chunk);
        req.on('end', () => resolve(data));
      });
    }
    ```
  </Tab>
</Tabs>

---

## With Tools

```ts

const result = await generateText({
  model: openai('gpt-4o'),
  prompt: 'What is 25 * 48?',
  tools: {
    calculate: tool({
      description: 'Evaluate a math expression',
      parameters: z.object({
        expression: z.string().describe('Math expression to evaluate'),
      }),
      execute: async ({ expression }) => {
        return { result: eval(expression) };
      },
    }),
  },
  maxSteps: 5,
});

console.log(result.text);
// "The result of 25 * 48 is 1200."

console.log(result.toolCalls);
// [{ id: 'call_123', name: 'calculate', args: { expression: '25 * 48' } }]

console.log(result.toolResults);
// [{ toolCallId: 'call_123', result: { result: 1200 } }]
```

---

## Multi-step Agentic Workflows

Set `maxSteps` to allow multiple tool calls in sequence:

```ts
const result = await generateText({
  model: openai('gpt-4o'),
  prompt: 'Research the weather in Tokyo, Paris, and London, then tell me which is warmest.',
  tools: {
    getWeather: tool({
      description: 'Get weather for a city',
      parameters: z.object({ city: z.string() }),
      execute: async ({ city }) => fetchWeatherAPI(city),
    }),
  },
  maxSteps: 10, // Allow up to 10 LLM calls
});

// The AI will:
// 1. Call getWeather for Tokyo
// 2. Call getWeather for Paris
// 3. Call getWeather for London
// 4. Compare and respond

console.log(result.steps.length); // 4 steps
```

<Callout type="warn">
**maxSteps** limits total LLM calls to prevent infinite loops. Set it high enough for your use case.
</Callout>

---

## Accessing Steps

```ts
for (const step of result.steps) {
  console.log('Step text:', step.text);
  console.log('Tool calls:', step.toolCalls);
  console.log('Tool results:', step.toolResults);
  console.log('Finish reason:', step.finishReason);
  console.log('Usage:', step.usage);
}
```

---

## When to Use generateText vs streamText

| Use Case | Function |
|----------|----------|
| Chat interfaces | `streamText()` |
| Real-time responses | `streamText()` |
| Background processing | `generateText()` |
| Batch operations | `generateText()` |
| Simple API endpoints | `generateText()` |
| When you need full response at once | `generateText()` |

---

## Next Steps

- [streamText()](/docs/llm-sdk/stream-text) - Stream responses in real-time
- [tool()](/docs/llm-sdk/tools) - Define type-safe tools
- [Providers](/docs/providers) - Configure LLM providers

---

## Overview
URL: https://copilot-sdk.yourgpt.ai/docs/llm-sdk
Description: Unified API for any LLM provider

One API, any provider. Switch between OpenAI, Anthropic, Google, and more with a single line change.

```ts

const result = await streamText({
  model: openai('gpt-4o'),
  prompt: 'Hello!',
});
```

---

## Switch Providers Instantly

Same code, different provider. No refactoring needed.

<Tabs items={['OpenAI', 'Anthropic', 'Google', 'xAI']}>
  <Tab value="OpenAI">
    ```ts
    import { openai } from '@yourgpt/llm-sdk/openai';

    const model = openai('gpt-4o');
    ```
  </Tab>
  <Tab value="Anthropic">
    ```ts
    import { anthropic } from '@yourgpt/llm-sdk/anthropic';

    const model = anthropic('claude-sonnet-4-20250514');
    ```
  </Tab>
  <Tab value="Google">
    ```ts
    import { google } from '@yourgpt/llm-sdk/google';

    const model = google('gemini-2.0-flash');
    ```
  </Tab>
  <Tab value="xAI">
    ```ts
    import { xai } from '@yourgpt/llm-sdk/xai';

    const model = xai('grok-3-fast');
    ```
  </Tab>
</Tabs>

---

## Framework Examples

Works with any HTTP framework. Returns standard Web `Response` objects.

<Tabs items={['Next.js', 'Express', 'Hono', 'Fastify']}>
  <Tab value="Next.js">
    ```ts title="app/api/chat/route.ts"
    import { streamText } from '@yourgpt/llm-sdk';
    import { openai } from '@yourgpt/llm-sdk/openai';

    export async function POST(req: Request) {
      const { messages } = await req.json();

      const result = await streamText({
        model: openai('gpt-4o'),
        messages,
      });

      return result.toTextStreamResponse();
    }
    ```
  </Tab>
  <Tab value="Express">
    ```ts title="server.ts"
    import express from 'express';
    import { streamText } from '@yourgpt/llm-sdk';
    import { openai } from '@yourgpt/llm-sdk/openai';

    const app = express();
    app.use(express.json());

    app.post('/api/chat', async (req, res) => {
      const result = await streamText({
        model: openai('gpt-4o'),
        messages: req.body.messages,
      });

      const response = result.toTextStreamResponse();
      res.set(Object.fromEntries(response.headers));
      response.body?.pipeTo(new WritableStream({
        write(chunk) { res.write(chunk); },
        close() { res.end(); }
      }));
    });
    ```
  </Tab>
  <Tab value="Hono">
    ```ts title="src/index.ts"
    import { Hono } from 'hono';
    import { streamText } from '@yourgpt/llm-sdk';
    import { openai } from '@yourgpt/llm-sdk/openai';

    const app = new Hono();

    app.post('/api/chat', async (c) => {
      const { messages } = await c.req.json();

      const result = await streamText({
        model: openai('gpt-4o'),
        messages,
      });

      return result.toTextStreamResponse();
    });

    export default app;
    ```
  </Tab>
  <Tab value="Fastify">
    ```ts title="server.ts"
    import Fastify from 'fastify';
    import { streamText } from '@yourgpt/llm-sdk';
    import { openai } from '@yourgpt/llm-sdk/openai';

    const app = Fastify();

    app.post('/api/chat', async (req, reply) => {
      const result = await streamText({
        model: openai('gpt-4o'),
        messages: req.body.messages,
      });

      const response = result.toTextStreamResponse();
      reply.headers(Object.fromEntries(response.headers));
      return reply.send(response.body);
    });
    ```
  </Tab>
</Tabs>

---

## Core Functions

| Function | Description |
|----------|-------------|
| [`streamText()`](/docs/llm-sdk/stream-text) | Stream responses in real-time |
| [`generateText()`](/docs/llm-sdk/generate-text) | Generate complete responses |
| [`tool()`](/docs/llm-sdk/tools) | Define AI-callable functions |

---

## Why Unified?

- **One API** - Learn once, use everywhere
- **Swap providers** - Change one import, keep all your code
- **Type-safe** - Full TypeScript support across all providers
- **Standard responses** - Web `Response` objects work anywhere

---

## streamText()
URL: https://copilot-sdk.yourgpt.ai/docs/llm-sdk/stream-text
Description: Stream text responses in real-time

Stream text responses in real-time. Returns helpers to consume the stream or convert it to HTTP responses.

<Callout type="info">
**Using with Copilot SDK?** Use `toDataStreamResponse()` instead of `toTextStreamResponse()`. See [Response Types](#response-types) below.
</Callout>

```ts

const result = await streamText({
  model: openai('gpt-4o'),
  prompt: 'Tell me a story.',
});

// Option 1: Iterate over text chunks
for await (const chunk of result.textStream) {
  process.stdout.write(chunk);
}

// Option 2: Get complete text (waits for stream to finish)
const text = await result.text;

// Option 3: Return as HTTP Response (for Copilot SDK)
return result.toDataStreamResponse();
```

---

## Parameters

```ts
const result = await streamText({
  // Required: Language model to use
  model: openai('gpt-4o'),

  // Content (at least one required)
  prompt: 'Hello',              // Simple prompt
  messages: [...],              // Chat history
  system: 'Be concise.',        // System instruction

  // Optional: Tools for function calling
  tools: { ... },
  maxSteps: 5,                  // Max LLM calls for tool loops

  // Optional: Generation settings
  temperature: 0.7,
  maxTokens: 4096,
});
```

---

## Response Object

```ts
const result = await streamText({ ... });

// Streams
result.textStream     // AsyncIterable<string> - text only
result.fullStream     // AsyncIterable<StreamPart> - all events

// Promises (resolve when stream completes)
result.text           // Promise<string> - full text
result.usage          // Promise<TokenUsage> - token counts
result.finishReason   // Promise<FinishReason>

// HTTP Response helpers
result.toTextStreamResponse()   // text/plain stream
result.toDataStreamResponse()   // SSE with structured events
```

---

## API Route Examples

<Tabs items={['Next.js', 'Node.js']}>
  <Tab value="Next.js">
    ```ts title="app/api/chat/route.ts"
    import { streamText } from '@yourgpt/llm-sdk';
    import { openai } from '@yourgpt/llm-sdk/openai';

    export async function POST(req: Request) {
      const { messages } = await req.json();

      const result = await streamText({
        model: openai('gpt-4o'),
        system: 'You are helpful.',
        messages,
      });

      // Use toDataStreamResponse() for Copilot SDK compatibility
      return result.toDataStreamResponse();
    }
    ```
  </Tab>
  <Tab value="Node.js">
    ```ts title="server.ts"
    import { createServer } from 'http';
    import { streamText } from '@yourgpt/llm-sdk';
    import { openai } from '@yourgpt/llm-sdk/openai';

    createServer(async (req, res) => {
      const body = await getBody(req);
      const { messages } = JSON.parse(body);

      const result = await streamText({
        model: openai('gpt-4o'),
        system: 'You are helpful.',
        messages,
      });

      // Use toDataStreamResponse() for Copilot SDK compatibility
      const response = result.toDataStreamResponse();
      res.writeHead(200, Object.fromEntries(response.headers));

      const reader = response.body!.getReader();
      while (true) {
        const { done, value } = await reader.read();
        if (done) break;
        res.write(value);
      }
      res.end();
    }).listen(3001);

    function getBody(req: any): Promise<string> {
      return new Promise((resolve) => {
        let data = '';
        req.on('data', (chunk: any) => data += chunk);
        req.on('end', () => resolve(data));
      });
    }
    ```
  </Tab>
</Tabs>

<Callout type="info">
**For Copilot SDK:** Consider using the [Runtime API](/docs/server) instead of `streamText()` directly. The Runtime provides a higher-level API with built-in support for tools, persistence, and more.
</Callout>

---

## Response Types

### Data Stream Response (Recommended for Copilot SDK)

SSE format with structured events. **Required for Copilot SDK compatibility.**

```ts
return result.toDataStreamResponse();
```

```
Content-Type: text/event-stream

data: {"type":"text-delta","text":"Hello"}
data: {"type":"text-delta","text":"!"}
data: {"type":"tool-call-complete","toolCall":{...}}
data: {"type":"tool-result","toolCallId":"...","result":{...}}
data: {"type":"finish","finishReason":"stop","usage":{...}}
data: [DONE]
```

### Text Stream Response

Simple text streaming. **Not compatible with Copilot SDK** (use for direct streaming to other clients).

```ts
return result.toTextStreamResponse();
```

```
Content-Type: text/plain; charset=utf-8

Hello! How can I help you?
```

<Callout type="warn">
**Copilot SDK Compatibility:** The Copilot SDK expects SSE format. Use `toDataStreamResponse()` for Copilot SDK, or `toTextStreamResponse()` only for direct streaming to non-Copilot clients.
</Callout>

---

## With Tools

```ts

const result = await streamText({
  model: openai('gpt-4o'),
  prompt: 'What is the weather in Tokyo?',
  tools: {
    getWeather: tool({
      description: 'Get weather for a city',
      parameters: z.object({ city: z.string() }),
      execute: async ({ city }) => ({ temp: 22, condition: 'sunny' }),
    }),
  },
  maxSteps: 5,
});

return result.toDataStreamResponse();
```

<Callout type="info">
Use `toDataStreamResponse()` with tools to receive tool call and result events.
</Callout>

---

## Consuming the Full Stream

For custom handling of all events:

```ts
for await (const part of result.fullStream) {
  switch (part.type) {
    case 'text-delta':
      console.log('Text:', part.text);
      break;
    case 'tool-call-complete':
      console.log('Tool called:', part.toolCall.name);
      break;
    case 'tool-result':
      console.log('Tool result:', part.result);
      break;
    case 'step-start':
      console.log('Starting step:', part.step);
      break;
    case 'step-finish':
      console.log('Step done:', part.finishReason);
      break;
    case 'finish':
      console.log('Complete:', part.usage);
      break;
    case 'error':
      console.error('Error:', part.error);
      break;
  }
}
```

---

## Stream Part Types

| Type | Description | Properties |
|------|-------------|------------|
| `text-delta` | Text chunk | `text: string` |
| `tool-call-complete` | Tool was called | `toolCall: { id, name, args }` |
| `tool-result` | Tool returned | `toolCallId, result` |
| `step-start` | New step began | `step: number` |
| `step-finish` | Step completed | `step, finishReason` |
| `finish` | Stream done | `finishReason, usage` |
| `error` | Error occurred | `error: Error` |

---

## Custom Response Headers

```ts
return result.toDataStreamResponse({
  status: 200,
  headers: {
    'X-Custom-Header': 'value',
  },
});
```

---

## Abort Handling

```ts
export async function POST(req: Request) {
  const { messages } = await req.json();

  const result = await streamText({
    model: openai('gpt-4o'),
    messages,
    signal: req.signal, // Pass abort signal
  });

  return result.toDataStreamResponse();
}
```

---

## Next Steps

- [generateText()](/docs/llm-sdk/generate-text) - Non-streaming generation
- [tool()](/docs/llm-sdk/tools) - Define type-safe tools
- [Providers](/docs/providers) - Configure LLM providers

---

## tool()
URL: https://copilot-sdk.yourgpt.ai/docs/llm-sdk/tools
Description: Define type-safe tools with Zod schemas

Define type-safe tools that AI models can call. Tools let your AI application interact with external systems, APIs, databases, and more.

---

## Basic Usage

```ts

const weatherTool = tool({
  description: 'Get current weather for a city',
  parameters: z.object({
    city: z.string().describe('City name'),
  }),
  execute: async ({ city }) => {
    // Call your weather API
    return { temperature: 22, condition: 'sunny' };
  },
});

const result = await generateText({
  model: openai('gpt-4o'),
  prompt: 'What is the weather in Tokyo?',
  tools: { getWeather: weatherTool },
});
```

---

## Tool Definition

```ts
const myTool = tool({
  // Required: Tell the AI what this tool does
  description: 'Description of what the tool does',

  // Required: Zod schema for parameters
  parameters: z.object({
    param1: z.string().describe('Description for AI'),
    param2: z.number().optional(),
  }),

  // Required: Function to execute
  execute: async (params, context) => {
    // params is fully typed from your Zod schema
    // context provides { toolCallId, abortSignal }
    return { result: 'data' };
  },
});
```

---

## Zod Schema Examples

### Basic Types

```ts
const myTool = tool({
  description: 'Example tool',
  parameters: z.object({
    // String
    name: z.string(),

    // Number
    age: z.number(),

    // Boolean
    active: z.boolean(),

    // Optional field
    nickname: z.string().optional(),

    // With default
    count: z.number().default(10),

    // Enum
    status: z.enum(['pending', 'active', 'done']),

    // Array
    tags: z.array(z.string()),
  }),
  execute: async (params) => {
    // params is fully typed!
    return { success: true };
  },
});
```

### Descriptions for AI

Use `.describe()` to help the AI understand parameters:

```ts
parameters: z.object({
  city: z.string().describe('The city name, e.g., "Tokyo" or "New York"'),
  unit: z.enum(['celsius', 'fahrenheit']).describe('Temperature unit').default('celsius'),
})
```

<Callout type="info">
Good descriptions help the AI provide correct arguments. Be specific about expected formats.
</Callout>

---

## Multiple Tools

Pass multiple tools to let the AI choose:

```ts
const result = await generateText({
  model: openai('gpt-4o'),
  prompt: 'Book a flight from NYC to Tokyo for next Monday',
  tools: {
    searchFlights: tool({
      description: 'Search for available flights',
      parameters: z.object({
        from: z.string(),
        to: z.string(),
        date: z.string(),
      }),
      execute: async ({ from, to, date }) => {
        return await flightAPI.search(from, to, date);
      },
    }),
    bookFlight: tool({
      description: 'Book a specific flight',
      parameters: z.object({
        flightId: z.string(),
        passengerName: z.string(),
      }),
      execute: async ({ flightId, passengerName }) => {
        return await flightAPI.book(flightId, passengerName);
      },
    }),
    getFlightStatus: tool({
      description: 'Check flight status',
      parameters: z.object({
        flightNumber: z.string(),
      }),
      execute: async ({ flightNumber }) => {
        return await flightAPI.status(flightNumber);
      },
    }),
  },
  maxSteps: 5,
});
```

---

## Tool Context

The execute function receives a context object:

```ts
const myTool = tool({
  description: 'My tool',
  parameters: z.object({ query: z.string() }),
  execute: async (params, context) => {
    // Unique ID for this tool call
    console.log('Tool call ID:', context.toolCallId);

    // Check for cancellation
    if (context.abortSignal?.aborted) {
      throw new Error('Cancelled');
    }

    return { result: 'data' };
  },
});
```

---

## Agentic Workflows (maxSteps)

For complex tasks requiring multiple tool calls:

```ts
const result = await generateText({
  model: openai('gpt-4o'),
  prompt: 'Research the weather in 5 major cities and summarize',
  tools: {
    getWeather: tool({
      description: 'Get weather for a city',
      parameters: z.object({ city: z.string() }),
      execute: async ({ city }) => fetchWeather(city),
    }),
  },
  maxSteps: 10, // Allow up to 10 LLM calls
});

// The AI will call getWeather multiple times, then summarize
```

<Callout type="warn">
**maxSteps** limits the total number of LLM calls. Set it high enough for your use case, but not unlimited to prevent runaway loops.
</Callout>

---

## Accessing Tool Results

```ts
const result = await generateText({
  model: openai('gpt-4o'),
  prompt: 'What is 25 * 48?',
  tools: { calculate: calculateTool },
});

// All tool calls made
console.log(result.toolCalls);
// [{ id: 'call_123', name: 'calculate', args: { expression: '25 * 48' } }]

// All tool results
console.log(result.toolResults);
// [{ toolCallId: 'call_123', result: { answer: 1200 } }]

// Step-by-step breakdown
for (const step of result.steps) {
  console.log('Text:', step.text);
  console.log('Tool calls:', step.toolCalls);
  console.log('Tool results:', step.toolResults);
}
```

---

## With Streaming

Tools work with `streamText()` too:

```ts
const result = await streamText({
  model: openai('gpt-4o'),
  prompt: 'What is the weather?',
  tools: { getWeather: weatherTool },
  maxSteps: 5,
});

for await (const part of result.fullStream) {
  if (part.type === 'tool-call-complete') {
    console.log('Tool called:', part.toolCall.name, part.toolCall.args);
  }
  if (part.type === 'tool-result') {
    console.log('Tool result:', part.result);
  }
  if (part.type === 'text-delta') {
    process.stdout.write(part.text);
  }
}
```

---

## Error Handling

Errors in tools are caught and passed back to the AI:

```ts
const myTool = tool({
  description: 'Risky operation',
  parameters: z.object({ id: z.string() }),
  execute: async ({ id }) => {
    const item = await db.find(id);
    if (!item) {
      throw new Error(`Item ${id} not found`);
    }
    return item;
  },
});
```

The AI will see the error and can try again or inform the user.

---

## Real-World Examples

### Database Query Tool

```ts
const queryDatabase = tool({
  description: 'Query the product database',
  parameters: z.object({
    query: z.string().describe('Search query'),
    limit: z.number().optional().default(10),
    category: z.enum(['electronics', 'clothing', 'home']).optional(),
  }),
  execute: async ({ query, limit, category }) => {
    const results = await db.products.search({
      query,
      limit,
      ...(category && { category }),
    });
    return results;
  },
});
```

### API Integration Tool

```ts
const sendEmail = tool({
  description: 'Send an email to a recipient',
  parameters: z.object({
    to: z.string().email().describe('Recipient email address'),
    subject: z.string().describe('Email subject line'),
    body: z.string().describe('Email body content'),
  }),
  execute: async ({ to, subject, body }) => {
    await emailService.send({ to, subject, body });
    return { sent: true, to };
  },
});
```

### Web Scraping Tool

```ts
const scrapeWebpage = tool({
  description: 'Extract content from a webpage',
  parameters: z.object({
    url: z.string().url().describe('URL to scrape'),
  }),
  execute: async ({ url }) => {
    const response = await fetch(url);
    const html = await response.text();
    // Parse and return relevant content
    return { title: '...', content: '...' };
  },
});
```

---

## TypeScript Types

```ts
```

---

## Next Steps

- [generateText()](/docs/llm-sdk/generate-text) - Use tools with text generation
- [streamText()](/docs/llm-sdk/stream-text) - Use tools with streaming
- [Agentic Loop](/docs/tools/agentic-loop) - Build complex AI agents

---

## Anthropic
URL: https://copilot-sdk.yourgpt.ai/docs/providers/anthropic
Description: Use Claude 3.5 Sonnet, Claude 3 Opus, and more

<ProviderHeader
  provider="anthropic"
  name="Anthropic"
  description="Claude 3.5 Sonnet, Claude 3 Opus"
/>

Claude models from Anthropic. Known for safety, long context, and excellent reasoning.

---

## Setup

### 1. Install Packages

```bash
npm install @yourgpt/copilot-sdk @yourgpt/llm-sdk @anthropic-ai/sdk
```

### 2. Get API Key

Get your API key from [console.anthropic.com](https://console.anthropic.com/)

### 3. Add Environment Variable

```bash title=".env.local"
ANTHROPIC_API_KEY=sk-ant-...
```

### 4. Usage

```ts

const result = await generateText({
  model: anthropic('claude-sonnet-4-20250514'),
  prompt: 'Explain the theory of relativity.',
});

console.log(result.text);
```

### 5. Streaming (API Route)

```ts title="app/api/chat/route.ts"

export async function POST(req: Request) {
  const { messages } = await req.json();

  const result = await streamText({
    model: anthropic('claude-sonnet-4-20250514'),
    system: 'You are a helpful assistant.',
    messages,
  });

  return result.toTextStreamResponse();
}
```

---

## Available Models

```ts
// Claude 4 (Latest)
anthropic('claude-sonnet-4-20250514')    // Best balance of speed & quality
anthropic('claude-opus-4-20250514')      // Most capable

// Claude 3.7
anthropic('claude-3-7-sonnet-20250219')  // Extended thinking support
anthropic('claude-3-7-sonnet-latest')    // Latest 3.7 version

// Claude 3.5
anthropic('claude-sonnet-4-20250514')  // Great performance
anthropic('claude-3-5-sonnet-latest')    // Latest 3.5 version
anthropic('claude-3-5-haiku-20241022')   // Fast and affordable

// Claude 3
anthropic('claude-3-opus-20240229')      // High quality
anthropic('claude-3-sonnet-20240229')    // Balanced
anthropic('claude-3-haiku-20240307')     // Fastest
```

---

## Configuration Options

```ts

// Custom API key
const model = anthropic('claude-3-5-sonnet-20241022', {
  apiKey: 'sk-ant-custom-key',
});

// With generation options
const result = await generateText({
  model: anthropic('claude-sonnet-4-20250514'),
  prompt: 'Hello',
  temperature: 0.7,        // 0-1
  maxTokens: 4096,         // Max response length
});
```

---

## Tool Calling

Claude has robust tool support:

```ts

const result = await generateText({
  model: anthropic('claude-sonnet-4-20250514'),
  prompt: 'Analyze this document for key insights',
  tools: {
    analyzeDocument: tool({
      description: 'Analyze a document',
      parameters: z.object({
        documentId: z.string(),
        analysisType: z.enum(['summary', 'sentiment', 'entities']),
      }),
      execute: async ({ documentId, analysisType }) => {
        return await analyzeDocument(documentId, analysisType);
      },
    }),
  },
  maxSteps: 5,
});
```

---

## Long Context

Claude excels at long documents (200K context):

```ts
const result = await generateText({
  model: anthropic('claude-sonnet-4-20250514'),
  system: `You are a support agent. Here is our full documentation:

  ${fullDocumentation}  // Can be 100K+ tokens

  Answer questions based on this documentation.`,
  prompt: userQuestion,
});
```

---

## Vision (Image Input)

Claude models support image analysis:

```ts
const result = await generateText({
  model: anthropic('claude-sonnet-4-20250514'),
  messages: [
    {
      role: 'user',
      content: [
        { type: 'text', text: 'Analyze this screenshot' },
        { type: 'image', image: base64ImageData },
      ],
    },
  ],
});
```

---

## With Copilot UI

Use with the Copilot React components:

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


export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <CopilotProvider runtimeUrl="/api/chat">
      {children}
    </CopilotProvider>
  );
}
```

---

## Pricing

| Model | Input | Output |
|-------|-------|--------|
| claude-3-5-sonnet | $3/1M tokens | $15/1M tokens |
| claude-3-opus | $15/1M tokens | $75/1M tokens |
| claude-3-5-haiku | $0.80/1M tokens | $4/1M tokens |

*Check [Anthropic pricing](https://anthropic.com/pricing) for current rates.*

---

## Next Steps

- [Google](/docs/providers/google) - Try Gemini models
- [generateText()](/docs/llm-sdk/generate-text) - Full API reference
- [tool()](/docs/llm-sdk/tools) - Define tools with Zod

---

## Custom Provider
URL: https://copilot-sdk.yourgpt.ai/docs/providers/custom-provider
Description: Build your own LLM provider adapter

<Callout type="warn">
**Coming Soon.** Custom provider documentation is under active development.
</Callout>

Build an adapter for any LLM API that isn't natively supported.

Custom providers follow the same interface as built-in providers. Your frontend code doesn't need to change when using a custom provider.

---

## Fallback
URL: https://copilot-sdk.yourgpt.ai/docs/providers/fallback
Description: Automatic failover and load distribution across LLM providers

Automatically retry failed requests with backup models. When your primary provider returns a `5xx` error, rate limit (`429`), or times out — the SDK silently tries the next model in your chain. Your application code doesn't change.

```ts

const chain = createFallbackChain({
  models: [
    createOpenAI({ apiKey: '...' }).languageModel('gpt-5.4'),
    createAnthropic({ apiKey: '...' }).languageModel('claude-haiku-4-5'),
  ],
});

const runtime = createRuntime({ adapter: chain });
```

---

## Installation

```bash
npm install @yourgpt/llm-sdk openai @anthropic-ai/sdk
```

---

## Basic Usage

Pass `createFallbackChain()` as the `adapter` in `createRuntime()`. The rest of your server code — streaming, tools, sessions — stays exactly the same.

```ts title="server.ts"

const openai = createOpenAI({ apiKey: process.env.OPENAI_API_KEY });
const anthropic = createAnthropic({ apiKey: process.env.ANTHROPIC_API_KEY });

const runtime = createRuntime({
  adapter: createFallbackChain({
    models: [
      openai.languageModel('gpt-5.4'),            // tried first
      anthropic.languageModel('claude-haiku-4-5'), // tried if OpenAI fails
    ],
  }),
  systemPrompt: 'You are a helpful assistant.',
});

// Use exactly as normal — no other changes
app.post('/api/chat', async (req, res) => {
  await runtime.stream(req.body).pipeToResponse(res);
});
```

---

## What Triggers Fallback

| Error type | Triggers fallback? |
|---|---|
| `5xx` server errors | ✅ Yes |
| `429` rate limit | ✅ Yes |
| Network timeout / connection refused | ✅ Yes |
| `4xx` client errors (bad key, bad request) | ❌ No — these are your bugs, not provider failures |

<Callout type="info">
Once content has started streaming to the client, fallback is not attempted. You cannot restart a stream mid-flight.
</Callout>

---

## Routing Strategies

Control which model is tried first on each request.

<Tabs items={['Priority (default)', 'Round-Robin']}>
  <Tab value="Priority (default)">
    Always tries models in the order defined. First model handles all traffic until it fails.

    ```ts
    createFallbackChain({
      models: [primaryModel, backupModel],
      strategy: 'priority', // default — can be omitted
    });
    ```
  </Tab>
  <Tab value="Round-Robin">
    Distributes load evenly. Request 1 starts at model A, request 2 starts at model B, and so on. If the starting model fails, the chain falls through to the next one as usual.

    ```ts
    createFallbackChain({
      models: [openaiModel, anthropicModel],
      strategy: 'round-robin',
    });
    ```

    <Callout type="info">
    **Multi-instance deployments:** Round-robin state is in-memory by default and resets on restart. For shared state across instances, plug in a custom store (Redis, Upstash, etc.) via the `store` option.
    </Callout>
  </Tab>
</Tabs>

---

## Per-Model Retries

Retry the same model before moving to the next one. Useful for transient errors like brief rate limits or flaky connections.

```ts
createFallbackChain({
  models: [openaiModel, anthropicModel],
  retries: 2,                  // retry each model up to 2 times
  retryDelay: 500,             // base delay: 500ms
  retryBackoff: 'exponential', // 500ms → 1000ms → 2000ms (default)
  onRetry: ({ model, retryAttempt, maxRetries, delayMs, error }) => {
    console.warn(`[retry] ${model} attempt ${retryAttempt}/${maxRetries} — waiting ${delayMs}ms`);
  },
});
```

**Backoff options:**

| `retryBackoff` | Pattern (retryDelay=500) |
|---|---|
| `exponential` (default) | 500ms → 1000ms → 2000ms |
| `fixed` | 500ms → 500ms → 500ms |

<Callout type="info">
With `retries: 2`, each model gets 3 total attempts (1 initial + 2 retries) before the chain moves to the next model.
</Callout>

---

## Observability Callbacks

Two callbacks give you visibility into what the chain is doing.

```ts
createFallbackChain({
  models: [openaiModel, anthropicModel, googleModel],

  // Fires on each per-model retry (before the wait delay)
  onRetry: ({ model, provider, error, retryAttempt, maxRetries, delayMs }) => {
    console.warn(`[retry] ${provider}/${model} — attempt ${retryAttempt}/${maxRetries}`);
    metrics.increment('llm.retry', { provider, model });
  },

  // Fires when a model is abandoned and the next one is tried
  onFallback: ({ attemptedModel, nextModel, error, attempt }) => {
    console.warn(`[fallback] ${attemptedModel} → ${nextModel}: ${error.message}`);
    metrics.increment('llm.fallback', { from: attemptedModel, to: nextModel });
  },
});
```

---

## Handling Full Failure

When every model in the chain fails, `FallbackExhaustedError` is thrown. It includes a per-model breakdown of what failed.

```ts

try {
  await runtime.stream(req.body).pipeToResponse(res);
} catch (err) {
  if (err instanceof FallbackExhaustedError) {
    // Per-model breakdown
    for (const f of err.failures) {
      console.error(
        `${f.provider}/${f.model} failed after ${f.retriesAttempted} retries: ${f.error.message}`
      );
    }
    res.status(503).json({ error: 'All models unavailable. Try again later.' });
  }
}
```

---

## Custom Error Filtering

By default the chain uses sensible rules (5xx, 429, network errors trigger fallback; 4xx does not). Override with `retryableErrors` for custom logic.

```ts
createFallbackChain({
  models: [openaiModel, anthropicModel],

  // Fall back on any error at all
  retryableErrors: () => true,

  // Or — only fall back on rate limits
  retryableErrors: (err) => {
    return err instanceof Error && /429|rate.?limit/i.test(err.message);
  },
});
```

---

## Shared Routing Store (Multi-Instance)

For round-robin to work correctly across multiple server instances or serverless functions, plug in a shared store.

```ts

// Implement RoutingStore with any backend — Redis, Upstash, Cloudflare KV, etc.
// The SDK ships the interface. You own the implementation.
const redisStore: RoutingStore = {
  async get(key) {
    const val = await redis.get(key);
    return val ? Number(val) : undefined;
  },
  async set(key, value) {
    await redis.set(key, String(value));
  },
};

createFallbackChain({
  models: [openaiModel, anthropicModel],
  strategy: 'round-robin',
  store: redisStore,
});
```

<Callout type="info">
The default `MemoryRoutingStore` is zero-config and works for single-process apps. No store configuration is needed unless you run multiple instances.
</Callout>

---

## With Tools

Tools work transparently across fallback providers. Define your tools once — whichever provider handles the request formats them natively.

```ts
const runtime = createRuntime({
  adapter: createFallbackChain({
    models: [openaiModel, anthropicModel],
  }),
  tools: [
    {
      name: 'get_weather',
      description: 'Get current weather for a city',
      location: 'server',
      inputSchema: {
        type: 'object',
        properties: { city: { type: 'string' } },
        required: ['city'],
      },
      handler: async ({ city }) => fetchWeather(city),
    },
  ],
});
```

OpenAI receives tools as function-calling JSON. Anthropic receives them as `tool_use` blocks. **Your handler always runs on your server regardless of which provider responded.**

---

## Full Configuration Reference

```ts

createFallbackChain({
  // Required: adapters to try in order
  models: LLMAdapter[],

  // Routing strategy (default: 'priority')
  strategy?: 'priority' | 'round-robin',

  // Pluggable store for round-robin state (default: MemoryRoutingStore)
  store?: RoutingStore,

  // Retries per model before moving to next (default: 0)
  retries?: number,

  // Base delay between retries in ms (default: 500)
  retryDelay?: number,

  // Backoff strategy (default: 'exponential')
  retryBackoff?: 'exponential' | 'fixed',

  // Called on each per-model retry attempt
  onRetry?: (info: RetryInfo) => void,

  // Called when a model is abandoned and next one is tried
  onFallback?: (info: FallbackInfo) => void,

  // Custom predicate to decide which errors trigger fallback/retry
  retryableErrors?: (error: unknown) => boolean,
})
```

---

## Next Steps

- [OpenAI](/docs/providers/openai) — Configure your primary provider
- [Anthropic](/docs/providers/anthropic) — Add a Claude fallback
- [Server Storage](/docs/server/storage) — Persist sessions alongside fallback chains

---

## Fireworks
URL: https://copilot-sdk.yourgpt.ai/docs/providers/fireworks
Description: Fast open-source model inference — Llama, DeepSeek, Qwen, Mixtral and more

[Fireworks.ai](https://fireworks.ai) is a high-performance inference platform for open-source models. It offers fast, scalable serving for Llama, DeepSeek, Qwen, Mixtral, Gemma and many others through an OpenAI-compatible API.

---

## Setup

### 1. Install packages

```bash
npm install @yourgpt/copilot-sdk @yourgpt/llm-sdk openai
```

<Callout type="info">
Fireworks uses an OpenAI-compatible API, so the `openai` package is the only peer dependency needed.
</Callout>

### 2. Get API key

Sign up and get your API key at [fireworks.ai](https://fireworks.ai).

### 3. Add environment variable

```bash title=".env.local"
FIREWORKS_API_KEY=fw_...
```

### 4. Streaming API route

```ts title="app/api/chat/route.ts"

export async function POST(req: Request) {
  const { messages } = await req.json();

  const result = await streamText({
    model: fireworks('accounts/fireworks/models/llama-v3p1-70b-instruct'),
    system: 'You are a helpful assistant.',
    messages,
  });

  return result.toTextStreamResponse();
}
```

### 5. Generate text

```ts

const result = await generateText({
  model: fireworks('accounts/fireworks/models/deepseek-v3'),
  prompt: 'Explain quantum entanglement simply.',
});

console.log(result.text);
```

---

## Available Models

```ts
// Llama 3.1
fireworks('accounts/fireworks/models/llama-v3p1-405b-instruct')  // 405B, 131K ctx
fireworks('accounts/fireworks/models/llama-v3p1-70b-instruct')   // 70B, 131K ctx
fireworks('accounts/fireworks/models/llama-v3p1-8b-instruct')    // 8B, fast

// Llama 3.2 Vision
fireworks('accounts/fireworks/models/llama-v3p2-90b-vision-instruct')  // vision + tools
fireworks('accounts/fireworks/models/llama-v3p2-11b-vision-instruct')

// DeepSeek
fireworks('accounts/fireworks/models/deepseek-v3')  // 131K ctx, tools
fireworks('accounts/fireworks/models/deepseek-r1')  // reasoning model

// Qwen
fireworks('accounts/fireworks/models/qwen2p5-72b-instruct')        // 32K ctx
fireworks('accounts/fireworks/models/qwen2p5-coder-32b-instruct')  // code

// Mixtral
fireworks('accounts/fireworks/models/mixtral-8x22b-instruct')  // 65K ctx
fireworks('accounts/fireworks/models/mixtral-8x7b-instruct')

// Gemma
fireworks('accounts/fireworks/models/gemma2-9b-it')
```

Any model ID listed on [fireworks.ai/models](https://fireworks.ai/models) works — unknown models default to tools enabled with 131K context.

---

## Configuration

```ts

// Explicit API key
const model = fireworks('accounts/fireworks/models/llama-v3p1-70b-instruct', {
  apiKey: 'fw_...',
});

// Custom base URL (e.g. self-hosted or proxy)
const model = fireworks('accounts/fireworks/models/llama-v3p1-70b-instruct', {
  baseURL: 'https://my-proxy.example.com/v1',
});
```

---

## Tool Calling

Most Fireworks models support tool calling:

```ts

const result = await generateText({
  model: fireworks('accounts/fireworks/models/llama-v3p1-70b-instruct'),
  prompt: 'What is the weather in Miami?',
  tools: {
    getWeather: tool({
      description: 'Get weather for a city',
      parameters: z.object({ city: z.string() }),
      execute: async ({ city }) => ({ temperature: 82, condition: 'sunny' }),
    }),
  },
  maxSteps: 5,
});
```

<Callout type="info">
`deepseek-r1` does not support tool calling — it is a reasoning model. Use `deepseek-v3` or a Llama model for tool use.
</Callout>

---

## With Copilot UI

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


export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <CopilotProvider runtimeUrl="/api/chat">
      {children}
    </CopilotProvider>
  );
}
```

---

## Next Steps

- [OpenRouter](/docs/providers/openrouter) - Access 500+ models with one API key
- [Fallback Chain](/docs/providers/fallback) - Automatic failover between providers
- [generateText()](/docs/llm-sdk) - Full LLM SDK reference

---

## Google (Gemini)
URL: https://copilot-sdk.yourgpt.ai/docs/providers/google
Description: Use Gemini 2.0, Gemini 1.5 Pro, and Flash models

<ProviderHeader
  provider="google"
  name="Google Generative AI"
  description="Gemini 2.0 Flash, Gemini 1.5 Pro"
/>

Google's Gemini models. Excellent for multimodal tasks with massive context windows.

---

## Setup

### 1. Install Packages

```bash
npm install @yourgpt/copilot-sdk @yourgpt/llm-sdk openai
```

<Callout type="info">
Google Gemini uses an OpenAI-compatible API, so we use the `openai` SDK.
</Callout>

### 2. Get API Key

Get your API key from [Google AI Studio](https://aistudio.google.com/apikey)

### 3. Add Environment Variable

```bash title=".env.local"
GOOGLE_API_KEY=...
```

### 4. Usage

```ts

const result = await generateText({
  model: google('gemini-2.0-flash'),
  prompt: 'Explain machine learning.',
});

console.log(result.text);
```

### 5. Streaming (API Route)

```ts title="app/api/chat/route.ts"

export async function POST(req: Request) {
  const { messages } = await req.json();

  const result = await streamText({
    model: google('gemini-2.0-flash'),
    system: 'You are a helpful assistant.',
    messages,
  });

  return result.toTextStreamResponse();
}
```

---

## Available Models

```ts
// Gemini 2.5 (Experimental - Latest)
google('gemini-2.5-pro-preview-05-06')    // Most capable, 1M context
google('gemini-2.5-flash-preview-05-20')  // Fast and powerful

// Gemini 2.0
google('gemini-2.0-flash')        // Fast and capable
google('gemini-2.0-flash-lite')   // Most efficient
google('gemini-2.0-flash-exp')    // Experimental

// Gemini 1.5
google('gemini-1.5-pro')          // Best quality, 2M context
google('gemini-1.5-flash')        // Fast and cheap
google('gemini-1.5-flash-8b')     // Lightweight
```

---

## Configuration Options

```ts

// Custom API key
const model = google('gemini-2.0-flash', {
  apiKey: 'custom-api-key',
});

// With generation options
const result = await generateText({
  model: google('gemini-2.0-flash'),
  prompt: 'Hello',
  temperature: 0.7,        // 0-1
  maxTokens: 8192,         // Max response length
});
```

---

## Tool Calling

```ts

const result = await generateText({
  model: google('gemini-2.0-flash'),
  prompt: 'Search our knowledge base for AI topics',
  tools: {
    searchKnowledge: tool({
      description: 'Search internal knowledge base',
      parameters: z.object({
        query: z.string(),
        category: z.string().optional(),
      }),
      execute: async ({ query, category }) => {
        return await searchKnowledge(query, category);
      },
    }),
  },
  maxSteps: 5,
});
```

---

## Massive Context Window

Gemini supports 1M+ token context:

```ts
const result = await generateText({
  model: google('gemini-1.5-pro'),
  system: `Here is the entire codebase:

  ${entireCodebase}  // Can be 500K+ tokens!

  Help users understand and modify this code.`,
  prompt: userQuestion,
});
```

---

## Multimodal (Images, Video, Audio)

Gemini excels at multimodal understanding:

```ts
const result = await generateText({
  model: google('gemini-2.0-flash'),
  messages: [
    {
      role: 'user',
      content: [
        { type: 'text', text: "What's in this image?" },
        { type: 'image', image: imageBase64 },
      ],
    },
  ],
});
```

---

## With Copilot UI

Use with the Copilot React components:

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


export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <CopilotProvider runtimeUrl="/api/chat">
      {children}
    </CopilotProvider>
  );
}
```

---

## Pricing

| Model | Input | Output |
|-------|-------|--------|
| gemini-2.0-flash | Free tier available | See pricing |
| gemini-1.5-pro | $1.25/1M tokens | $5/1M tokens |
| gemini-1.5-flash | $0.075/1M tokens | $0.30/1M tokens |

*Very competitive pricing. Check [Google AI pricing](https://ai.google.dev/pricing) for current rates.*

---

## Next Steps

- [xAI](/docs/providers/xai) - Ultra-fast inference
- [generateText()](/docs/llm-sdk/generate-text) - Full API reference
- [tool()](/docs/llm-sdk/tools) - Define tools with Zod

---

## Providers Overview
URL: https://copilot-sdk.yourgpt.ai/docs/providers
Description: Connect to any LLM provider

Copilot SDK supports multiple LLM providers through `@yourgpt/llm-sdk`. **Switch providers without changing your frontend code.**

<Callout type="info">
All providers use the same API. Change one line in your backend to switch from OpenAI to Anthropic.
</Callout>

<ProviderCards />

---

## How It Works

Install the SDK and the provider's official SDK. Each provider returns a model instance that works with `generateText()` and `streamText()`.

### Installation

<Tabs items={['OpenAI / Google / xAI', 'Anthropic', 'Ollama']}>
  <Tab value="OpenAI / Google / xAI">
    ```bash
    npm install @yourgpt/copilot-sdk @yourgpt/llm-sdk openai
    ```
    <Callout type="info">
    OpenAI, Google Gemini, and xAI all use the `openai` SDK (OpenAI-compatible APIs).
    </Callout>
  </Tab>
  <Tab value="Anthropic">
    ```bash
    npm install @yourgpt/copilot-sdk @yourgpt/llm-sdk @anthropic-ai/sdk
    ```
  </Tab>
  <Tab value="Ollama">
    ```bash
    npm install @yourgpt/copilot-sdk @yourgpt/llm-sdk
    ```
    <Callout type="info">
    **No additional SDK needed!** Ollama uses native `fetch` for local inference.
    </Callout>
  </Tab>
</Tabs>

### Backend Setup

```ts title="app/api/chat/route.ts"

export async function POST(req: Request) {
  const { messages } = await req.json();

  const result = await streamText({
    model: openai('gpt-5.2'),
    system: 'You are a helpful assistant.',
    messages,
  });

  return result.toTextStreamResponse();
}
```

### Frontend Setup

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


export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <CopilotProvider runtimeUrl="/api/chat">
      {children}
    </CopilotProvider>
  );
}
```

---

## Switching Providers

Change the import and model - frontend stays the same:

```ts title="app/api/chat/route.ts"

// OpenAI
const model = openai('gpt-4o');

// Anthropic
const model = anthropic('claude-3-5-sonnet-20241022');

// Google
const model = google('gemini-2.0-flash');

// xAI (Grok)
const model = xai('grok-3-fast');

// OpenRouter (500+ models)
const model = openrouter('anthropic/claude-3.5-sonnet');

// Fireworks (fast open-source)
const model = fireworks('accounts/fireworks/models/llama-v3p1-70b-instruct');

// Ollama (Local)
const ollama = createOllama();
const model = ollama('llama3.1');

// Use any model
const result = await streamText({
  model,
  messages,
});
```

<Callout type="info">
Your tools, UI, and all frontend code remain unchanged. The SDK normalizes responses across providers.
</Callout>

---

## Available Providers

| Provider | Import | SDK Required | Example |
|----------|--------|--------------|---------|
| OpenAI | `@yourgpt/llm-sdk/openai` | `openai` | `openai('gpt-4o')` |
| Anthropic | `@yourgpt/llm-sdk/anthropic` | `@anthropic-ai/sdk` | `anthropic('claude-3-5-sonnet-20241022')` |
| Google | `@yourgpt/llm-sdk/google` | `openai` | `google('gemini-2.0-flash')` |
| xAI | `@yourgpt/llm-sdk/xai` | `openai` | `xai('grok-3-fast')` |
| OpenRouter | `@yourgpt/llm-sdk/openrouter` | `openai` | `openrouter('anthropic/claude-3.5-sonnet')` |
| Fireworks | `@yourgpt/llm-sdk/fireworks` | `openai` | `fireworks('accounts/fireworks/models/llama-v3p1-70b-instruct')` |
| Ollama | `@yourgpt/llm-sdk/ollama` | None | `ollama('llama3.1')` |

---

## Why So Few SDKs?

Most LLM providers now offer **OpenAI-compatible APIs**. This means you only need:

| SDK | Providers |
|-----|-----------|
| `openai` | OpenAI, Google Gemini, xAI Grok, Azure OpenAI, Groq, Together AI |
| `@anthropic-ai/sdk` | Anthropic Claude (native SDK for full features) |
| None | Ollama (uses native `fetch` for local inference) |

<Callout type="info">
Google and xAI use OpenAI-compatible endpoints. Ollama runs locally and needs no external SDK. We automatically configure the correct `baseURL` for each provider.
</Callout>

---

## Provider Comparison

| Provider | Speed | Quality | Cost | Best For |
|----------|-------|---------|------|----------|
| OpenAI | Fast | Excellent | $$ | General use |
| Anthropic | Medium | Excellent | $$ | Long context, safety |
| Google | Fast | Very Good | $ | Multimodal |
| xAI | Ultra Fast | Excellent | $ | Speed-critical apps |
| OpenRouter | Varies | Any model | $ | Model flexibility, single key |
| Fireworks | Ultra Fast | Very Good | $ | Open-source models, cost savings |
| Ollama | Varies | Good-Excellent | Free | Privacy, offline, development |

---

## Fallback Chain

Use multiple providers together for automatic failover and load distribution.

```ts

const runtime = createRuntime({
  adapter: createFallbackChain({
    models: [
      openai.languageModel('gpt-5.4'),
      anthropic.languageModel('claude-haiku-4-5'),
    ],
    strategy: 'round-robin',
    retries: 2,
  }),
});
```

[Fallback Chain docs →](/docs/providers/fallback)

---

## Ollama
URL: https://copilot-sdk.yourgpt.ai/docs/providers/ollama
Description: Run LLMs locally with no API keys

<ProviderHeader
  provider="ollama"
  name="Ollama"
  description="Local AI inference, full privacy"
/>

Run powerful LLMs locally on your machine. No API keys, no cloud, no costs - just privacy and control.

---

## Setup

### 1. Install Ollama

First, install Ollama on your machine:

```bash
# macOS
brew install ollama

# Linux
curl -fsSL https://ollama.ai/install.sh | sh

# Windows: Download from https://ollama.ai
```

### 2. Pull a Model

```bash
# Start Ollama server
ollama serve

# Pull a model (in another terminal)
ollama pull llama3.1        # Best for chat & tools (~4.7GB)
ollama pull llava           # For vision support (~4.7GB)
ollama pull qwen2.5:1.5b    # Lightweight option (~986MB)
```

### 3. Install Packages

```bash
npm install @yourgpt/copilot-sdk @yourgpt/llm-sdk
```

<Callout type="info">
**No additional SDK required!** Ollama uses native `fetch` - no `openai` or other provider SDK needed.
</Callout>

### 4. Usage

```ts

const ollama = createOllama();
const model = ollama('llama3.1');

for await (const event of model.stream({
  messages: [{ id: '1', role: 'user', content: 'Hello!' }],
})) {
  if (event.type === 'message:delta') {
    process.stdout.write(event.content);
  }
}
```

### 5. Streaming (API Route)

```ts title="app/api/chat/route.ts"

const ollama = createOllama();

export async function POST(req: Request) {
  const { messages } = await req.json();

  const model = ollama('llama3.1');

  const stream = new ReadableStream({
    async start(controller) {
      for await (const event of model.stream({
        messages,
        system: 'You are a helpful assistant.',
      })) {
        if (event.type === 'message:delta') {
          controller.enqueue(new TextEncoder().encode(event.content));
        }
      }
      controller.close();
    },
  });

  return new Response(stream, {
    headers: { 'Content-Type': 'text/plain' },
  });
}
```

---

## Available Models

| Model | Vision | Tools | Context | Size |
|-------|--------|-------|---------|------|
| `llama3.1` | ❌ | ✅ | 128k | ~4.7GB |
| `llama3.2-vision` | ✅ | ✅ | 128k | ~4.7GB |
| `llava` | ✅ | ❌ | 4k | ~4.7GB |
| `mistral` | ❌ | ✅ | 8k | ~4.1GB |
| `mixtral` | ❌ | ✅ | 32k | ~26GB |
| `qwen2.5:1.5b` | ❌ | ✅ | 32k | ~986MB |
| `deepseek` | ❌ | ✅ | 16k | ~4GB |
| `codellama` | ❌ | ❌ | 16k | ~3.8GB |

```ts
// Use any Ollama model
ollama('llama3.1')           // General purpose, tool support
ollama('llava')              // Vision capable
ollama('mistral')            // Fast, good for coding
ollama('qwen2.5:1.5b')       // Lightweight, great for testing
```

---

## Ollama-Specific Options

Ollama supports unique configuration options for fine-tuning model behavior:

```ts

const ollama = createOllama({
  baseUrl: 'http://localhost:11434',  // Custom server URL
  options: {
    // Context & Performance
    num_ctx: 8192,           // Context window size
    num_batch: 512,          // Batch size for processing
    num_gpu: 1,              // Number of GPUs to use

    // Sampling
    temperature: 0.7,        // Creativity (0.0-2.0)
    top_p: 0.9,              // Nucleus sampling
    top_k: 40,               // Top-k sampling

    // Repetition Control
    repeat_penalty: 1.1,     // Penalize repetition
    repeat_last_n: 64,       // Look back window

    // Advanced
    mirostat: 0,             // Mirostat sampling (0, 1, or 2)
    mirostat_eta: 0.1,       // Mirostat learning rate
    mirostat_tau: 5.0,       // Mirostat target entropy
    seed: 42,                // For reproducible outputs
  },
});
```

---

## Tool Calling

Ollama supports tool calling with compatible models (llama3.1, mistral, qwen2):

```ts

const ollama = createOllama();
const model = ollama('llama3.1');

for await (const event of model.stream({
  messages: [{ id: '1', role: 'user', content: "What's the weather in San Francisco?" }],
  actions: [
    {
      name: 'get_weather',
      description: 'Get current weather for a location',
      parameters: {
        city: { type: 'string', required: true, description: 'City name' },
      },
      handler: async ({ city }) => {
        return { temperature: 65, condition: 'foggy', city };
      },
    },
  ],
})) {
  if (event.type === 'action:start') {
    console.log(`\nTool called: ${event.name}`);
  }
  if (event.type === 'action:result') {
    console.log(`Result: ${JSON.stringify(event.result)}`);
  }
  if (event.type === 'message:delta') {
    process.stdout.write(event.content);
  }
}
```

<Callout type="warn">
Not all models support tool calling. Use `llama3.1`, `mistral`, or `qwen2` for best results.
</Callout>

---

## Vision

Use vision-capable models like LLaVA to analyze images:

```ts

const ollama = createOllama();
const model = ollama('llava');

// Read image and convert to base64
const imageBuffer = readFileSync('./image.png');
const base64Image = imageBuffer.toString('base64');

for await (const event of model.stream({
  messages: [
    {
      id: '1',
      role: 'user',
      content: 'What do you see in this image?',
      metadata: {
        attachments: [
          {
            type: 'image',
            data: base64Image,
            mimeType: 'image/png',
          },
        ],
      },
    },
  ],
})) {
  if (event.type === 'message:delta') {
    process.stdout.write(event.content);
  }
}
```

---

## With Copilot UI

Use with the Copilot React components:

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


export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <CopilotProvider runtimeUrl="/api/chat">
      {children}
    </CopilotProvider>
  );
}
```

```ts title="app/api/chat/route.ts"

const ollama = createOllama();

export async function POST(req: Request) {
  const { messages } = await req.json();
  const model = ollama('llama3.1');

  const stream = new ReadableStream({
    async start(controller) {
      for await (const event of model.stream({ messages })) {
        if (event.type === 'message:delta') {
          controller.enqueue(new TextEncoder().encode(event.content));
        }
      }
      controller.close();
    },
  });

  return new Response(stream, {
    headers: { 'Content-Type': 'text/plain' },
  });
}
```

---

## Why Ollama?

| Benefit | Description |
|---------|-------------|
| **Privacy** | All data stays on your machine - nothing sent to external servers |
| **No API Keys** | No billing, no rate limits, no account required |
| **Offline** | Works completely offline once models are downloaded |
| **No Costs** | Run unlimited inferences without paying per token |
| **Fast Iteration** | No network latency for local development |
| **Customizable** | Fine-tune with Ollama modelfiles |

<Callout type="info">
Ollama is perfect for development, testing, privacy-sensitive applications, and air-gapped environments.
</Callout>

---

## Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `OLLAMA_BASE_URL` | `http://localhost:11434` | Ollama server URL |
| `OLLAMA_MODEL` | `llama3.1` | Default model |

---

## Troubleshooting

### Cannot connect to Ollama

```bash
# Make sure Ollama is running
ollama serve

# Check if it's responding
curl http://localhost:11434/api/tags
```

### Model not found

```bash
# Pull the required model
ollama pull llama3.1
ollama pull llava  # for vision
```

### Tool calling not working

Not all models support tool calling. Supported models:
- `llama3.1` ✅
- `mistral` ✅
- `qwen2` ✅

Models like `codellama` and `gemma2` don't support tools.

---

## Next Steps

- [OpenAI](/docs/providers/openai) - Cloud-based alternative
- [Custom Provider](/docs/providers/custom-provider) - Build your own
- [Examples](https://github.com/YourGPT/copilot-sdk/tree/main/examples/ollama-demo) - Full demo project

---

## OpenAI
URL: https://copilot-sdk.yourgpt.ai/docs/providers/openai
Description: Use GPT-4o, GPT-4, and GPT-3.5 models

<ProviderHeader
  provider="openai"
  name="OpenAI"
  description="GPT-4o, GPT-4, GPT-3.5 Turbo"
/>

The most popular LLM provider. Access GPT-4o, GPT-4 Turbo, and GPT-3.5 models.

---

## Setup

### 1. Install Packages

```bash
npm install @yourgpt/copilot-sdk @yourgpt/llm-sdk openai
```

### 2. Get API Key

Get your API key from [platform.openai.com](https://platform.openai.com/api-keys)

### 3. Add Environment Variable

```bash title=".env.local"
OPENAI_API_KEY=sk-...
```

### 4. Usage

```ts

const result = await generateText({
  model: openai('gpt-4o'),
  prompt: 'Explain quantum computing simply.',
});

console.log(result.text);
```

### 5. Streaming (API Route)

```ts title="app/api/chat/route.ts"

export async function POST(req: Request) {
  const { messages } = await req.json();

  const result = await streamText({
    model: openai('gpt-4o'),
    system: 'You are a helpful assistant.',
    messages,
  });

  return result.toTextStreamResponse();
}
```

---

## Available Models

```ts
// Latest and best
openai('gpt-4o')              // Fastest GPT-4 class
openai('gpt-5.2')         // Cost-effective, very capable

// GPT-4 Turbo
openai('gpt-4-turbo')         // 128K context

// GPT-3.5
openai('gpt-3.5-turbo')       // Fast and cheap
```

---

## Configuration Options

```ts

// Custom API key
const model = openai('gpt-4o', {
  apiKey: 'sk-custom-key',
});

// With generation options
const result = await generateText({
  model: openai('gpt-4o'),
  prompt: 'Hello',
  temperature: 0.7,        // 0-2, default 1
  maxTokens: 4096,         // Max response length
});
```

---

## Tool Calling

OpenAI has excellent tool/function calling support:

```ts

const result = await generateText({
  model: openai('gpt-4o'),
  prompt: 'What is the weather in Tokyo?',
  tools: {
    getWeather: tool({
      description: 'Get weather for a city',
      parameters: z.object({
        city: z.string().describe('City name'),
      }),
      execute: async ({ city }) => {
        // Your weather API call
        return { temperature: 22, condition: 'sunny' };
      },
    }),
  },
  maxSteps: 5, // Allow multiple tool calls
});
```

---

## Vision (Image Input)

GPT-4o supports image analysis. Send images in your messages:

```ts
const result = await generateText({
  model: openai('gpt-4o'),
  messages: [
    {
      role: 'user',
      content: [
        { type: 'text', text: "What's in this image?" },
        { type: 'image', image: base64ImageData },
      ],
    },
  ],
});
```

---

## With Copilot UI

Use with the Copilot React components:

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


export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <CopilotProvider runtimeUrl="/api/chat">
      {children}
    </CopilotProvider>
  );
}
```

---

## Pricing

| Model | Input | Output |
|-------|-------|--------|
| gpt-4o | $2.50/1M tokens | $10/1M tokens |
| gpt-5.2 | $0.15/1M tokens | $0.60/1M tokens |
| gpt-3.5-turbo | $0.50/1M tokens | $1.50/1M tokens |

*Prices as of late 2024. Check [OpenAI pricing](https://openai.com/pricing) for current rates.*

---

## Next Steps

- [Anthropic](/docs/providers/anthropic) - Try Claude models
- [generateText()](/docs/llm-sdk/generate-text) - Full API reference
- [tool()](/docs/llm-sdk/tools) - Define tools with Zod

---

## OpenRouter
URL: https://copilot-sdk.yourgpt.ai/docs/providers/openrouter
Description: Access 500+ models from any provider through a single API key

[OpenRouter](https://openrouter.ai) is a unified API gateway that gives you access to 500+ models from 60+ providers — OpenAI, Anthropic, Google, Meta, Mistral, and more — through a single endpoint and one API key.

---

## Setup

### 1. Install packages

```bash
npm install @yourgpt/copilot-sdk @yourgpt/llm-sdk openai
```

### 2. Get API key

Sign up at [openrouter.ai](https://openrouter.ai) and create an API key.

### 3. Add environment variable

```bash title=".env.local"
OPENROUTER_API_KEY=sk-or-...
```

### 4. Streaming API route

```ts title="app/api/chat/route.ts"

export async function POST(req: Request) {
  const { messages } = await req.json();

  const result = await streamText({
    model: openrouter('anthropic/claude-3.5-sonnet'),
    system: 'You are a helpful assistant.',
    messages,
  });

  return result.toTextStreamResponse();
}
```

### 5. Generate text

```ts

const result = await generateText({
  model: openrouter('openai/gpt-4o'),
  prompt: 'Summarize the latest AI research.',
});

console.log(result.text);
```

---

## Model IDs

OpenRouter model IDs follow the format `provider/model-name`:

```ts
// OpenAI
openrouter('openai/gpt-4o')
openrouter('openai/gpt-4o-mini')
openrouter('openai/o3-mini')

// Anthropic
openrouter('anthropic/claude-3.5-sonnet')
openrouter('anthropic/claude-3.5-haiku')
openrouter('anthropic/claude-3-opus')

// Google
openrouter('google/gemini-2.0-flash-001')
openrouter('google/gemini-2.0-pro-exp-02-05')

// Meta Llama
openrouter('meta-llama/llama-3.1-405b-instruct')
openrouter('meta-llama/llama-3.1-70b-instruct')

// Mistral
openrouter('mistralai/mistral-large')
openrouter('mistralai/mixtral-8x22b-instruct')

// DeepSeek
openrouter('deepseek/deepseek-chat')
openrouter('deepseek/deepseek-r1')

// Auto routing — OpenRouter picks the best model
openrouter('openrouter/auto')
```

Browse the full list at [openrouter.ai/models](https://openrouter.ai/models).

---

## Configuration

```ts

// With site attribution (improves model availability)
const model = openrouter('anthropic/claude-3.5-sonnet', {
  apiKey: 'sk-or-...',
  siteUrl: 'https://myapp.com',
  appName: 'My App',
});

// Provider preferences — control which underlying providers are used
const model = openrouter('openai/gpt-4o', {
  providerPreferences: {
    allow: ['openai'],        // Only use OpenAI directly
    order: 'latency',         // 'price' | 'latency' | 'throughput'
  },
});
```

---

## Fetch available models

```ts

// Get all 500+ models
const models = await fetchOpenRouterModels();

// Search by name or provider
const claudeModels = await searchOpenRouterModels('claude');
const gptModels = await searchOpenRouterModels('gpt-4');
```

---

## Tool Calling

OpenRouter passes tool calls through to the underlying model. Support varies by model — most frontier models handle it well:

```ts

const result = await generateText({
  model: openrouter('openai/gpt-4o'),
  prompt: 'What is the weather in Paris?',
  tools: {
    getWeather: tool({
      description: 'Get weather for a city',
      parameters: z.object({ city: z.string() }),
      execute: async ({ city }) => ({ temperature: 18, condition: 'cloudy' }),
    }),
  },
  maxSteps: 5,
});
```

---

## With Copilot UI

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


export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <CopilotProvider runtimeUrl="/api/chat">
      {children}
    </CopilotProvider>
  );
}
```

---

## Next Steps

- [Fireworks](/docs/providers/fireworks) - Fast open-source model inference
- [Fallback Chain](/docs/providers/fallback) - Automatic failover between providers
- [generateText()](/docs/llm-sdk) - Full LLM SDK reference

---

## Together AI
URL: https://copilot-sdk.yourgpt.ai/docs/providers/togetherai
Description: Cost-effective open-source model inference — Llama, DeepSeek, Qwen, Gemma and more

[Together AI](https://together.ai) is a high-performance inference platform for open-source models. It offers fast, scalable serving for Llama, DeepSeek, Qwen, Gemma, Mistral and many others through an OpenAI-compatible API.

---

## Setup

### 1. Install packages

```bash
npm install @yourgpt/copilot-sdk @yourgpt/llm-sdk openai
```

<Callout type="info">
Together AI uses an OpenAI-compatible API, so the `openai` package is the only peer dependency needed.
</Callout>

### 2. Get API key

Sign up and get your API key at [api.together.xyz/settings/api-keys](https://api.together.xyz/settings/api-keys).

### 3. Add environment variable

```bash title=".env.local"
TOGETHER_API_KEY=your-key-here
```

### 4. Create runtime API route

```ts title="app/api/chat/route.ts"

const together = createTogetherAI({
  apiKey: process.env.TOGETHER_API_KEY,
});

const runtime = createRuntime({
  provider: together,
  model: 'meta-llama/Llama-3.3-70B-Instruct-Turbo',
  systemPrompt: 'You are a helpful assistant.',
});

export async function POST(request: Request) {
  return runtime.handleRequest(request);
}
```

### 5. Connect Copilot UI

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


export default function Page() {
  return (
    <CopilotProvider runtimeUrl="/api/chat">
      <CopilotChat />
    </CopilotProvider>
  );
}
```

---

## Modern Pattern (Direct)

For simpler use cases without the runtime, use `togetherai()` directly with `generateText` or `streamText`:

```ts

const result = await generateText({
  model: togetherai('deepseek-ai/DeepSeek-V3'),
  prompt: 'Explain quantum entanglement simply.',
});

console.log(result.text);
```

```ts

const result = await streamText({
  model: togetherai('meta-llama/Llama-3.3-70B-Instruct-Turbo'),
  system: 'You are a helpful assistant.',
  messages,
});

return result.toTextStreamResponse();
```

---

## Available Models

```ts
// DeepSeek
togetherai('deepseek-ai/DeepSeek-V3')      // 128K ctx, tools
togetherai('deepseek-ai/DeepSeek-V3.1')     // 128K ctx, tools
togetherai('deepseek-ai/DeepSeek-R1')       // reasoning model

// Llama
togetherai('meta-llama/Llama-3.3-70B-Instruct-Turbo')  // 131K ctx, fast

// Qwen
togetherai('Qwen/Qwen3.5-397B-A17B')       // 262K ctx
togetherai('Qwen/Qwen3.5-9B')

// Gemma
togetherai('google/gemma-4-31B-it')

// Other
togetherai('openai/gpt-oss-120b')
togetherai('moonshotai/Kimi-K2.5')          // 262K ctx
togetherai('MiniMaxAI/MiniMax-M2.5')
```

Any model ID listed on [together.ai/models](https://api.together.xyz/models) works.

---

## Configuration

```ts

// With explicit API key
const together = createTogetherAI({
  apiKey: 'your-key',
});

// Custom base URL (e.g. self-hosted or proxy)
const together = createTogetherAI({
  apiKey: 'your-key',
  baseUrl: 'https://my-proxy.example.com/v1',
});
```

Or with the modern pattern:

```ts

const model = togetherai('meta-llama/Llama-3.3-70B-Instruct-Turbo', {
  apiKey: 'your-key',
  baseURL: 'https://my-proxy.example.com/v1',
});
```

---

## Fallback Chain

Automatically fail over to backup models when the primary is unavailable or rate-limited:

```ts title="app/api/chat/route.ts"

const together = createTogetherAI({
  apiKey: process.env.TOGETHER_API_KEY,
});

const chain = createFallbackChain({
  models: [
    together.languageModel('meta-llama/Llama-3.3-70B-Instruct-Turbo'),
    together.languageModel('deepseek-ai/DeepSeek-V3'),
    together.languageModel('Qwen/Qwen3.5-9B'),
    together.languageModel('google/gemma-4-31B-it'),
  ],
  strategy: 'priority',
  retries: 1,
  retryDelay: 500,
  retryBackoff: 'exponential',
  onFallback: ({ attemptedModel, nextModel, error }) => {
    console.warn(`[fallback] ${attemptedModel} → ${nextModel} | ${error.message}`);
  },
});

const runtime = createRuntime({
  adapter: chain,
  systemPrompt: 'You are a helpful assistant.',
});

export async function POST(request: Request) {
  return runtime.handleRequest(request);
}
```

<Callout type="info">
With `strategy: 'priority'`, the first model handles all traffic until it fails.
Use `strategy: 'round-robin'` to distribute load evenly across models.
</Callout>

---

## Tool Calling

Many Together AI models support tool calling:

```ts

const result = await generateText({
  model: togetherai('meta-llama/Llama-3.3-70B-Instruct-Turbo'),
  prompt: 'What is the weather in Miami?',
  tools: {
    getWeather: tool({
      description: 'Get weather for a city',
      parameters: z.object({ city: z.string() }),
      execute: async ({ city }) => ({ temperature: 82, condition: 'sunny' }),
    }),
  },
  maxSteps: 5,
});
```

<Callout type="info">
`deepseek-ai/DeepSeek-R1` is a reasoning model and does not support tool calling. Use `DeepSeek-V3` or a Llama model for tool use.
</Callout>

---

## Next Steps

- [Fireworks](/docs/providers/fireworks) - Another fast open-source model platform
- [OpenRouter](/docs/providers/openrouter) - Access 500+ models with one API key
- [Fallback Chain](/docs/providers/fallback) - Automatic failover between providers
- [generateText()](/docs/llm-sdk) - Full LLM SDK reference

---

## xAI
URL: https://copilot-sdk.yourgpt.ai/docs/providers/xai
Description: Ultra-fast inference with Grok models

<ProviderHeader
  provider="xai"
  name="xAI"
  description="Ultra-fast Grok inference"
/>

Cutting-edge AI from xAI. Grok models offer real-time information access and ultra-fast inference.

---

## Setup

### 1. Install Packages

```bash
npm install @yourgpt/copilot-sdk @yourgpt/llm-sdk openai
```

<Callout type="info">
xAI uses an OpenAI-compatible API, so we use the `openai` SDK.
</Callout>

### 2. Get API Key

Get your API key from [console.x.ai](https://console.x.ai/)

### 3. Add Environment Variable

```bash title=".env.local"
XAI_API_KEY=xai-...
```

### 4. Usage

```ts

const result = await generateText({
  model: xai('grok-3-fast'),
  prompt: 'What are the latest trends in AI?',
});

console.log(result.text);
```

### 5. Streaming (API Route)

```ts title="app/api/chat/route.ts"

export async function POST(req: Request) {
  const { messages } = await req.json();

  const result = await streamText({
    model: xai('grok-3-fast'),
    system: 'You are a helpful assistant.',
    messages,
  });

  return result.toTextStreamResponse();
}
```

---

## Available Models

```ts
// Grok 4.1 Fast (Latest)
xai('grok-4-1-fast-reasoning')      // Best reasoning, 2M context
xai('grok-4-1-fast-non-reasoning')  // Fastest, 2M context

// Grok 4 Fast
xai('grok-4-fast-reasoning')        // Fast reasoning, 2M context
xai('grok-4-fast-non-reasoning')    // Fastest, 2M context

// Grok 4
xai('grok-4')                       // Flagship model, 256K context

// Grok 3 (Stable)
xai('grok-3-beta')                  // Enterprise flagship, 131K context
xai('grok-3-fast')             // Fast and stable, 131K context
xai('grok-3-mini-beta')             // Smaller model, 32K context

// Grok Code
xai('grok-code-fast-1')             // Optimized for coding, 256K context
```

---

## Configuration Options

```ts

// Custom API key
const model = xai('grok-3-fast', {
  apiKey: 'xai-custom-key',
});

// With generation options
const result = await generateText({
  model: xai('grok-3-fast'),
  prompt: 'Hello',
  temperature: 0.7,
  maxTokens: 4096,
});
```

---

## Tool Calling

xAI supports tool calling with all Grok models:

```ts

const result = await generateText({
  model: xai('grok-3-fast'),
  prompt: 'What is the weather in San Francisco?',
  tools: {
    getWeather: tool({
      description: 'Get weather for a city',
      parameters: z.object({
        city: z.string(),
      }),
      execute: async ({ city }) => {
        return { temperature: 65, condition: 'foggy' };
      },
    }),
  },
  maxSteps: 5,
});
```

---

## Speed Comparison

xAI Grok offers ultra-fast inference:

| Provider | Tokens/second |
|----------|---------------|
| xAI Grok | ~400+ |
| OpenAI | ~50-80 |
| Anthropic | ~50-80 |

<Callout type="info">
Grok's speed makes it ideal for real-time applications, chatbots, and agentic use cases.
</Callout>

---

## With Copilot UI

Use with the Copilot React components:

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


export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <CopilotProvider runtimeUrl="/api/chat">
      {children}
    </CopilotProvider>
  );
}
```

---

## Pricing

| Model | Input | Output |
|-------|-------|--------|
| grok-4-1-fast | $0.20/1M tokens | $0.50/1M tokens |
| grok-3-fast | $0.10/1M tokens | $0.30/1M tokens |
| grok-3-mini-beta | $0.05/1M tokens | $0.15/1M tokens |

*Check [x.ai/api](https://x.ai/api) for current rates.*

---

## Next Steps

- [OpenAI](/docs/providers/openai) - Try GPT models
- [generateText()](/docs/llm-sdk/generate-text) - Full API reference
- [tool()](/docs/llm-sdk/tools) - Define tools with Zod

---

## Deployment
URL: https://copilot-sdk.yourgpt.ai/docs/server/deployment
Description: Deploy your Copilot backend to any platform

Your Copilot backend uses standard Web APIs (`fetch`, `Response`, `ReadableStream`), so the **same code runs everywhere**.

<Callout type="info">
**Flexible by Design** — The SDK works with any platform that supports Web APIs. The examples below are just starting points. Feel free to adapt them to your stack — whether it's Fastify, Koa, Bun, or your own custom server.
</Callout>

---

## Vercel

Deploy to Vercel with Next.js. Supports both Serverless and Edge runtimes.

<Tabs items={['Serverless (Default)', 'Edge Runtime']}>
  <Tab value="Serverless (Default)">
    ```ts title="app/api/chat/route.ts"
    import { createRuntime } from '@yourgpt/llm-sdk';
    import { createOpenAI } from '@yourgpt/llm-sdk/openai';

    const runtime = createRuntime({
      provider: createOpenAI({ apiKey: process.env.OPENAI_API_KEY }),
      model: 'gpt-4o',
      systemPrompt: 'You are a helpful assistant.',
    });

    export async function POST(req: Request) {
      const body = await req.json();
      return runtime.stream(body).toResponse();
    }
    ```
  </Tab>
  <Tab value="Edge Runtime">
    Edge functions have faster cold starts (~25ms vs ~250ms) and run closer to users.

    ```ts title="app/api/chat/route.ts"
    import { createRuntime } from '@yourgpt/llm-sdk';
    import { createOpenAI } from '@yourgpt/llm-sdk/openai';

    export const runtime = 'edge'; // Enable Edge Runtime

    const rt = createRuntime({
      provider: createOpenAI({ apiKey: process.env.OPENAI_API_KEY }),
      model: 'gpt-4o',
      systemPrompt: 'You are a helpful assistant.',
    });

    export async function POST(req: Request) {
      const body = await req.json();
      return rt.stream(body).toResponse();
    }
    ```

    <Callout type="info">
    Edge functions have a 30-second execution limit. For long-running agent loops, use Serverless.
    </Callout>
  </Tab>
</Tabs>

### Non-Streaming

```ts title="app/api/chat/route.ts"
export async function POST(req: Request) {
  const body = await req.json();
  const result = await runtime.chat(body);
  return Response.json(result);
}
```

### Deploy

```bash
npm i -g vercel
vercel
```

Set your environment variable in the Vercel dashboard or CLI:

```bash
vercel env add OPENAI_API_KEY
```

---

## Cloudflare Workers

Deploy to Cloudflare's edge network. Runs in 300+ locations worldwide.

<Callout>
**Full Example Available** — See the complete [Cloudflare Workers Demo](https://github.com/YourGPT/copilot-sdk/tree/main/examples/cloudflare-workers-demo) with streaming and non-streaming endpoints.
</Callout>

<Tabs items={['Streaming', 'Non-Streaming']}>
  <Tab value="Streaming">
    ```ts title="src/index.ts"
    import { createRuntime, createHonoApp } from '@yourgpt/llm-sdk';
    import { createOpenAI } from '@yourgpt/llm-sdk/openai';

    export interface Env {
      OPENAI_API_KEY: string;
    }

    export default {
      async fetch(request: Request, env: Env): Promise<Response> {
        const runtime = createRuntime({
          provider: createOpenAI({ apiKey: env.OPENAI_API_KEY }),
          model: 'gpt-4o',
          systemPrompt: 'You are a helpful assistant.',
        });

        return createHonoApp(runtime).fetch(request, env);
      },
    };
    ```
  </Tab>
  <Tab value="Non-Streaming">
    ```ts title="src/index.ts"
    import { createRuntime } from '@yourgpt/llm-sdk';
    import { createOpenAI } from '@yourgpt/llm-sdk/openai';

    export interface Env {
      OPENAI_API_KEY: string;
    }

    export default {
      async fetch(request: Request, env: Env): Promise<Response> {
        const runtime = createRuntime({
          provider: createOpenAI({ apiKey: env.OPENAI_API_KEY }),
          model: 'gpt-4o',
          systemPrompt: 'You are a helpful assistant.',
        });

        if (request.method !== 'POST') {
          return new Response('Method not allowed', { status: 405 });
        }

        const body = await request.json();
        const result = await runtime.chat(body);
        return Response.json(result);
      },
    };
    ```
  </Tab>
</Tabs>

### Configuration

```toml title="wrangler.toml"
name = "my-copilot-api"
main = "src/index.ts"
compatibility_date = "2024-01-01"
compatibility_flags = ["nodejs_compat"]
```

### Deploy

```bash
npm i -g wrangler

# Add your API key as a secret
wrangler secret put OPENAI_API_KEY

# Deploy
wrangler deploy
```

<Callout>
Your API will be available at `https://my-copilot-api.<your-subdomain>.workers.dev`
</Callout>

---

## More Platforms

<Callout type="warn">
**Coming Soon** — Detailed guides for these platforms are in progress.
</Callout>

The SDK works out of the box with these platforms. Use the patterns from Vercel/Cloudflare as a reference:

| Platform | Runtime | Key Method |
|----------|---------|------------|
| **Deno Deploy** | Edge | `Deno.serve(createHonoApp(runtime).fetch)` |
| **AWS Lambda** | Serverless | `runtime.chat(body)` with Function URL |
| **Express / Node.js** | Node.js | `runtime.stream(body).pipeToResponse(res)` |
| **Bun** | Bun | `export default { fetch: createHonoApp(runtime).fetch }` |
| **Docker** | Any | Use `@hono/node-server` with `createHonoApp` |
| **Railway / Render / Fly.io** | Node.js | Same as Express |

<Callout type="info">
**Try it yourself!** The SDK uses standard Web APIs, so if your platform supports `Request`/`Response`, it will work. Check the [Server Setup](/docs/server) page for all available methods like `.toResponse()`, `.pipeToResponse()`, and `.chat()`.
</Callout>

---

## Connect Frontend

Point your Copilot SDK frontend to your deployed API:

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


export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <CopilotProvider
      runtimeUrl="https://your-api.example.com/api/chat"
      // For non-streaming:
      // streaming={false}
    >
      {children}
    </CopilotProvider>
  );
}
```

| Mode | Server Method | CopilotProvider |
|------|---------------|-----------------|
| Streaming | `.stream(body).toResponse()` | `streaming={true}` (default) |
| Non-streaming | `await runtime.chat(body)` | `streaming={false}` |

---

## CORS

If your frontend and backend are on different domains:

<Tabs items={['Next.js', 'Hono', 'Express']}>
  <Tab value="Next.js">
    ```ts title="app/api/chat/route.ts"
    const corsHeaders = {
      'Access-Control-Allow-Origin': '*',
      'Access-Control-Allow-Methods': 'POST, OPTIONS',
      'Access-Control-Allow-Headers': 'Content-Type',
    };

    export async function OPTIONS() {
      return new Response(null, { headers: corsHeaders });
    }

    export async function POST(req: Request) {
      const body = await req.json();
      const response = runtime.stream(body).toResponse();

      Object.entries(corsHeaders).forEach(([key, value]) => {
        response.headers.set(key, value);
      });

      return response;
    }
    ```
  </Tab>
  <Tab value="Hono">
    ```ts
    import { cors } from 'hono/cors';

    const app = createHonoApp(runtime);
    app.use('*', cors());
    ```
  </Tab>
  <Tab value="Express">
    ```ts
    import cors from 'cors';

    app.use(cors());
    ```
  </Tab>
</Tabs>

---

## Next Steps

- [Server Setup](/docs/server) — Full runtime configuration and response methods
- [Tools](/docs/tools) — Add function calling to your Copilot
- [Providers](/docs/providers) — Configure different LLM providers

---

## Server Setup
URL: https://copilot-sdk.yourgpt.ai/docs/server
Description: Configure your backend API for the Copilot SDK

Your server receives messages from the Copilot SDK frontend, calls the LLM, and returns the response.

---

## Quick Start

### 1. Install Dependencies

<Tabs items={['OpenAI', 'Anthropic', 'Google', 'xAI']}>
  <Tab value="OpenAI">
    ```bash
    npm install @yourgpt/llm-sdk openai
    ```

    <Callout>
    See [OpenAI Provider](/docs/providers/openai) for all available models.
    </Callout>
  </Tab>
  <Tab value="Anthropic">
    ```bash
    npm install @yourgpt/llm-sdk @anthropic-ai/sdk
    ```

    <Callout type="warn">
    Anthropic requires its own SDK (`@anthropic-ai/sdk`).
    See [Anthropic Provider](/docs/providers/anthropic) for models and extended thinking.
    </Callout>
  </Tab>
  <Tab value="Google">
    ```bash
    npm install @yourgpt/llm-sdk openai
    ```

    <Callout>
    Google uses OpenAI-compatible API.
    See [Google Provider](/docs/providers/google) for Gemini models.
    </Callout>
  </Tab>
  <Tab value="xAI">
    ```bash
    npm install @yourgpt/llm-sdk openai
    ```

    <Callout>
    xAI uses OpenAI-compatible API.
    See [xAI Provider](/docs/providers/xai) for Grok models.
    </Callout>
  </Tab>
</Tabs>

### 2. Set Environment Variables

```bash title=".env.local"
OPENAI_API_KEY=sk-...
# or ANTHROPIC_API_KEY=sk-ant-...
# or GOOGLE_API_KEY=...
# or XAI_API_KEY=...
```

### 3. Create Runtime

<Tabs items={['OpenAI', 'Anthropic', 'Google', 'xAI']}>
  <Tab value="OpenAI">
    ```ts
    import { createRuntime } from '@yourgpt/llm-sdk';
    import { createOpenAI } from '@yourgpt/llm-sdk/openai';

    const runtime = createRuntime({
      provider: createOpenAI({ apiKey: process.env.OPENAI_API_KEY }),
      model: 'gpt-4o',
      systemPrompt: 'You are a helpful assistant.',
    });
    ```
  </Tab>
  <Tab value="Anthropic">
    ```ts
    import { createRuntime } from '@yourgpt/llm-sdk';
    import { createAnthropic } from '@yourgpt/llm-sdk/anthropic';

    const runtime = createRuntime({
      provider: createAnthropic({ apiKey: process.env.ANTHROPIC_API_KEY }),
      model: 'claude-sonnet-4-20250514',
      systemPrompt: 'You are a helpful assistant.',
    });
    ```
  </Tab>
  <Tab value="Google">
    ```ts
    import { createRuntime } from '@yourgpt/llm-sdk';
    import { createGoogle } from '@yourgpt/llm-sdk/google';

    const runtime = createRuntime({
      provider: createGoogle({ apiKey: process.env.GOOGLE_API_KEY }),
      model: 'gemini-2.0-flash',
      systemPrompt: 'You are a helpful assistant.',
    });
    ```
  </Tab>
  <Tab value="xAI">
    ```ts
    import { createRuntime } from '@yourgpt/llm-sdk';
    import { createXAI } from '@yourgpt/llm-sdk/xai';

    const runtime = createRuntime({
      provider: createXAI({ apiKey: process.env.XAI_API_KEY }),
      model: 'grok-3-fast',
      systemPrompt: 'You are a helpful assistant.',
    });
    ```
  </Tab>
</Tabs>

---

## Usage

<Tabs items={['Next.js / Hono', 'Express', 'Node.js']}>
  <Tab value="Next.js / Hono">
    ```ts title="app/api/chat/route.ts"
    import { createRuntime } from '@yourgpt/llm-sdk';
    import { createOpenAI } from '@yourgpt/llm-sdk/openai';

    const runtime = createRuntime({
      provider: createOpenAI({ apiKey: process.env.OPENAI_API_KEY }),
      model: 'gpt-4o',
      systemPrompt: 'You are a helpful assistant.',
    });

    export async function POST(req: Request) {
      const body = await req.json();

      // Streaming - real-time response
      return runtime.stream(body).toResponse();

      // Non-streaming - wait for complete response
      // const result = await runtime.chat(body);
      // return Response.json(result);
    }
    ```
  </Tab>
  <Tab value="Express">
    ```ts title="server.ts"
    import express from 'express';
    import { createRuntime } from '@yourgpt/llm-sdk';
    import { createOpenAI } from '@yourgpt/llm-sdk/openai';

    const app = express();
    app.use(express.json());

    const runtime = createRuntime({
      provider: createOpenAI({ apiKey: process.env.OPENAI_API_KEY }),
      model: 'gpt-4o',
      systemPrompt: 'You are a helpful assistant.',
    });

    // Copilot SDK - Streaming (SSE)
    app.post('/api/copilot/stream', async (req, res) => {
      await runtime.stream(req.body).pipeToResponse(res);
    });

    // Copilot SDK - Non-streaming (JSON)
    app.post('/api/copilot/chat', async (req, res) => {
      const result = await runtime.chat(req.body);
      res.json(result);
    });

    app.listen(3001);
    ```

    <Callout>
    See the full [Express Demo](https://github.com/yourgpt/copilot-sdk/tree/main/examples/express-demo) for all endpoint variations including raw streaming and text-only responses.
    </Callout>
  </Tab>
  <Tab value="Node.js">
    ```ts title="server.ts"
    import { createServer } from 'http';
    import { createRuntime } from '@yourgpt/llm-sdk';
    import { createOpenAI } from '@yourgpt/llm-sdk/openai';

    const runtime = createRuntime({
      provider: createOpenAI({ apiKey: process.env.OPENAI_API_KEY }),
      model: 'gpt-4o',
      systemPrompt: 'You are a helpful assistant.',
    });

    createServer(async (req, res) => {
      if (req.method !== 'POST') return;
      const body = JSON.parse(await getBody(req));

      if (req.url === '/api/copilot/stream') {
        // Copilot SDK - Streaming (SSE)
        await runtime.stream(body).pipeToResponse(res);
      } else if (req.url === '/api/copilot/chat') {
        // Copilot SDK - Non-streaming (JSON)
        const result = await runtime.chat(body);
        res.writeHead(200, { 'Content-Type': 'application/json' });
        res.end(JSON.stringify(result));
      }
    }).listen(3001);

    function getBody(req: any): Promise<string> {
      return new Promise((resolve) => {
        let data = '';
        req.on('data', (chunk: any) => data += chunk);
        req.on('end', () => resolve(data));
      });
    }
    ```
  </Tab>
</Tabs>

| Method | Use Case | Returns |
|--------|----------|---------|
| `runtime.stream(body)` | Real-time chat, interactive UI | `StreamResult` with `.toResponse()`, `.pipeToResponse()` |
| `runtime.chat(body)` | Background tasks, batch processing | `{ text, messages, toolCalls }` |


---

## All Response Methods

The `runtime.stream()` method returns a `StreamResult` with multiple ways to consume the response:

### For Copilot SDK (SSE format)

| Method | Returns | Framework |
|--------|---------|-----------|
| `toResponse()` | Web `Response` (SSE) | Next.js, Hono, Deno |
| `pipeToResponse(res)` | Pipes SSE stream | Express, Node.js |

```ts
// Next.js / Hono
return runtime.stream(body).toResponse();

// Express
await runtime.stream(body).pipeToResponse(res);
```

### For Non-Streaming

| Method | Returns | Description |
|--------|---------|-------------|
| `collect()` | `CollectedResult` | Wait for full response |
| `text()` | `string` | Just get the final text |

```ts
// Get full result
const { text, messages, toolCalls } = await runtime.stream(body).collect();

// Or just the text
const text = await runtime.stream(body).text();

// Or use the convenience method
const result = await runtime.chat(body); // Same as stream().collect()
```

### Using Runtime generate() (CopilotChat Compatible)

The `generate()` method returns a `GenerateResult` with both raw access and a `toResponse()` method for CopilotChat-compatible format:

<Tabs items={['Next.js', 'Express', 'Hono']}>
  <Tab value="Next.js">
    ```ts title="app/api/chat/route.ts"
    import { createRuntime } from '@yourgpt/llm-sdk';
    import { createOpenAI } from '@yourgpt/llm-sdk/openai';

    const runtime = createRuntime({
      provider: createOpenAI({ apiKey: process.env.OPENAI_API_KEY }),
      model: 'gpt-4o',
      systemPrompt: 'You are a helpful assistant.',
    });

    export async function POST(req: Request) {
      const body = await req.json();
      const result = await runtime.generate(body);

      // CopilotChat-compatible format
      return Response.json(result.toResponse());

      // Or access raw properties
      // return Response.json({ text: result.text, toolCalls: result.toolCalls });
    }
    ```
  </Tab>
  <Tab value="Express">
    ```ts title="server.ts"
    import express from 'express';
    import { createRuntime } from '@yourgpt/llm-sdk';
    import { createOpenAI } from '@yourgpt/llm-sdk/openai';

    const app = express();
    app.use(express.json());

    const runtime = createRuntime({
      provider: createOpenAI({ apiKey: process.env.OPENAI_API_KEY }),
      model: 'gpt-4o',
      systemPrompt: 'You are a helpful assistant.',
    });

    app.post('/api/chat', async (req, res) => {
      const result = await runtime.generate(req.body);
      res.json(result.toResponse());
    });

    app.listen(3001);
    ```
  </Tab>
  <Tab value="Hono">
    ```ts title="server.ts"
    import { Hono } from 'hono';
    import { createRuntime } from '@yourgpt/llm-sdk';
    import { createOpenAI } from '@yourgpt/llm-sdk/openai';

    const app = new Hono();

    const runtime = createRuntime({
      provider: createOpenAI({ apiKey: process.env.OPENAI_API_KEY }),
      model: 'gpt-4o',
      systemPrompt: 'You are a helpful assistant.',
    });

    app.post('/api/chat', async (c) => {
      const result = await runtime.generate(await c.req.json());
      return c.json(result.toResponse());
    });

    export default app;
    ```
  </Tab>
</Tabs>

**GenerateResult properties:**
- `result.text` - Generated text content
- `result.messages` - All conversation messages
- `result.toolCalls` - Tool calls made during generation
- `result.toolResults` - Results from tool executions
- `result.success` - Whether generation was successful
- `result.toResponse()` - CopilotChat-compatible JSON format

<Callout type="info">
**When to use non-streaming:**
- Background processing or batch operations
- When you need the full response before taking action
- Simpler integration without SSE handling
- Logging or analytics that need complete responses
</Callout>

### For Direct Text Streaming (Not Copilot SDK)

<Callout type="warn">
These methods return plain text (`text/plain`) which the Copilot SDK **cannot parse**. Only use for direct streaming to non-Copilot clients.
</Callout>

| Method | Returns | Framework |
|--------|---------|-----------|
| `toTextResponse()` | Web `Response` (text/plain) | Next.js, Hono, Deno |
| `pipeTextToResponse(res)` | Pipes text stream | Express, Node.js |

### For Custom Handling

| Method | Returns | Description |
|--------|---------|-------------|
| `toReadableStream()` | `ReadableStream<Uint8Array>` | Raw stream for custom processing |

### Event Handlers

Process events as they stream (similar to Anthropic SDK):

```ts
const result = runtime.stream(body)
  .on('text', (text) => console.log('Text:', text))
  .on('toolCall', (call) => console.log('Tool:', call.name))
  .on('done', (result) => console.log('Done:', result.text))
  .on('error', (err) => console.error('Error:', err));

await result.pipeToResponse(res);
```

---

## Connect Frontend

Point your Copilot SDK frontend to your API endpoint:

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


export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <CopilotProvider runtimeUrl="/api/copilot/stream">
      {children}
    </CopilotProvider>
  );
}
```

For a separate backend server:

```tsx
// Streaming (default)
<CopilotProvider runtimeUrl="http://localhost:3001/api/copilot/stream">

// Non-streaming
<CopilotProvider
  runtimeUrl="http://localhost:3001/api/copilot/chat"
  streaming={false}
>
```

| Mode | Endpoint | CopilotProvider |
|------|----------|-----------------|
| Streaming (SSE) | `/api/copilot/stream` | `streaming={true}` (default) |
| Non-streaming (JSON) | `/api/copilot/chat` | `streaming={false}` |

---

## Advanced

<Accordions type="single">
  <Accordion title="Add Tools - Let the AI call functions on your server" id="tools">
    ```ts
    import { createRuntime, tool } from '@yourgpt/llm-sdk';
    import { createOpenAI } from '@yourgpt/llm-sdk/openai';
    import { z } from 'zod';

    const runtime = createRuntime({
      provider: createOpenAI({ apiKey: process.env.OPENAI_API_KEY }),
      model: 'gpt-4o',
      systemPrompt: 'You are a helpful assistant.',
      tools: [
        {
          name: 'getWeather',
          description: 'Get current weather for a city',
          inputSchema: {
            type: 'object',
            properties: {
              city: { type: 'string', description: 'City name' },
            },
            required: ['city'],
          },
          handler: async ({ city }) => {
            return { temperature: 72, condition: 'sunny' };
          },
        },
      ],
      agentLoop: {
        maxIterations: 10,
      },
    });
    ```
  </Accordion>

  <Accordion title="Add Persistence - Save conversations to your database" id="persistence">
    ```ts
    export async function POST(request: Request) {
      return runtime.handleRequest(request, {
        onFinish: async ({ messages, threadId }) => {
          await db.thread.upsert({
            where: { id: threadId },
            update: { messages, updatedAt: new Date() },
            create: { id: threadId, messages },
          });
        },
      });
    }
    ```
  </Accordion>

  <Accordion title="Track Token Usage - For billing and consumption limits" id="usage">
    Use the `onFinish` callback to track token usage for billing, credits, or consumption limits.
    Usage data is only available server-side and is not exposed to the client.

    **Option 1: With `handleRequest()` (Next.js)**
    ```ts
    export async function POST(request: Request) {
      return runtime.handleRequest(request, {
        onFinish: async ({ messages, usage }) => {
          if (usage) {
            await billing.recordUsage(userId, usage.totalTokens);
          }
        },
      });
    }
    ```

    **Option 2: With `stream()` (Express)**
    ```ts
    app.post('/api/chat', async (req, res) => {
      await runtime.stream(req.body, {
        onFinish: async ({ messages, usage }) => {
          if (usage) {
            console.log('Tokens:', usage.totalTokens);
            await billing.recordUsage(userId, usage.totalTokens);
          }
        },
      }).pipeToResponse(res);
    });
    ```

    **Option 3: With `chat()` (Non-streaming)**
    ```ts
    // Usage is included in result - strip before sending to client
    const { usage, ...clientResult } = await runtime.chat(body);

    if (usage) {
      console.log('Tokens:', usage.total_tokens);
      await billing.recordUsage(userId, usage.total_tokens);
    }

    res.json(clientResult); // Send without usage
    ```

    **Option 4: Raw access with `collect()`**
    ```ts
    // Use { includeUsage: true } when you need usage in the result
    const { text, usage } = await runtime.stream(body).collect({ includeUsage: true });
    console.log('Tokens:', usage?.total_tokens);
    ```

    | Field | Type | Description |
    |-------|------|-------------|
    | `usage.prompt_tokens` | `number` | Input tokens (prompt + context) |
    | `usage.completion_tokens` | `number` | Output tokens (response) |
    | `usage.total_tokens` | `number` | Total tokens used |

    <Callout type="info">
    For `chat()`, usage is **included in the result** - strip the `usage` key before sending to the Copilot client. For streaming, use `onFinish` callback or `{ includeUsage: true }` with `collect()`.
    </Callout>
  </Accordion>

  <Accordion title="Runtime Configuration - All options" id="config">
    ```ts
    const runtime = createRuntime({
      provider: createOpenAI({ apiKey: process.env.OPENAI_API_KEY }),
      model: 'gpt-4o',
      systemPrompt: 'You are a helpful assistant.',
      agentLoop: {
        maxIterations: 20,  // Max tool call cycles
        debug: true,        // Enable debug logging
      },
      tools: [/* server-side tools */],
      toolContext: {
        userId: 'user_123', // Passed to all tool handlers
      },
    });
    ```

    | Option | Type | Description |
    |--------|------|-------------|
    | `provider` | `AIProvider` | Provider instance |
    | `model` | `string` | Model ID (e.g., `'gpt-4o'`) |
    | `systemPrompt` | `string` | Default system prompt |
    | `agentLoop.maxIterations` | `number` | Max tool cycles (default: 20) |
    | `tools` | `ToolDefinition[]` | Server-side tools |
    | `toolContext` | `object` | Context passed to tool handlers |
  </Accordion>

  <Accordion title="CORS Configuration - For cross-origin requests" id="cors">
    ```ts title="app/api/chat/route.ts"
    export async function OPTIONS() {
      return new Response(null, {
        headers: {
          'Access-Control-Allow-Origin': '*',
          'Access-Control-Allow-Methods': 'POST, OPTIONS',
          'Access-Control-Allow-Headers': 'Content-Type',
        },
      });
    }

    export async function POST(req: Request) {
      const body = await req.json();
      const response = runtime.stream(body).toResponse();
      response.headers.set('Access-Control-Allow-Origin', '*');
      return response;
    }
    ```
  </Accordion>

  <Accordion title="Error Handling" id="errors">
    ```ts
    export async function POST(req: Request) {
      try {
        const body = await req.json();
        return runtime.stream(body).toResponse();
      } catch (error) {
        console.error('Chat error:', error);
        return Response.json({ error: 'Failed to process request' }, { status: 500 });
      }
    }
    ```
  </Accordion>
</Accordions>

---

## Direct AI Functions

For more control or standalone usage without the Runtime, you can use the AI functions directly:

| Function | Description | Link |
|----------|-------------|------|
| `streamText()` | Stream text in real-time | [Documentation](/docs/llm-sdk/stream-text) |
| `generateText()` | Generate complete text (non-streaming) | [Documentation](/docs/llm-sdk/generate-text) |

```ts

// Streaming
const stream = await streamText({
  model: openai('gpt-4o'),
  messages,
});
return stream.toDataStreamResponse();

// Non-streaming
const result = await generateText({
  model: openai('gpt-4o'),
  messages,
});
return Response.json({ text: result.text });
```

<Callout type="info">
**Note:** When using `streamText()` with Copilot SDK, use `toDataStreamResponse()` (not `toTextStreamResponse()`). See the [streamText documentation](/docs/llm-sdk/stream-text) for details.
</Callout>

---

## Next Steps

- [Deploy](/docs/deploy) - Deploy to Vercel, Cloudflare, AWS, Docker, and more
- [Tools](/docs/tools) - Learn more about frontend and backend tools
- [Providers](/docs/providers) - Provider-specific configuration
- [Chat History](/docs/chat-history) - Persist conversations across sessions
- [LLM SDK](/docs/llm-sdk) - Low-level AI functions

---

## Storage & Persistence
URL: https://copilot-sdk.yourgpt.ai/docs/server/storage
Description: Automatic session creation and message persistence with pluggable storage adapters

## Overview

The Storage Adapter system provides **automatic session creation and message persistence** for your copilot. When configured, the runtime handles everything — no manual save calls needed.

```ts

const runtime = createRuntime({
  provider: anthropic,
  model: 'claude-haiku-4-5',
  storage: createYourGPT({ apiKey, widgetUid }),
});

// That's it. Sessions are created automatically.
// Messages are persisted automatically.
app.post('/api/copilot/chat', async (req, res) => {
  const result = await runtime.chat(req.body);
  res.json(result); // result.threadId is included
});
```

---

## YourGPT Adapter

The built-in adapter for the YourGPT platform. Handles session creation, message persistence, and file uploads.

### Setup

```ts

const yourgpt = createYourGPT({
  apiKey: process.env.YOURGPT_API_KEY,
  widgetUid: process.env.YOURGPT_WIDGET_UID,
  // endpoint is optional — defaults to https://api.yourgpt.ai
  // Override for dev/staging:
  // endpoint: 'https://your-dev-server.example.com',
});
```

### Configuration

| Option | Required | Default | Description |
|--------|----------|---------|-------------|
| `apiKey` | Yes | — | YourGPT API key (server-side only, never expose to browser) |
| `widgetUid` | Yes | — | Widget UID — scopes sessions to your project |
| `endpoint` | No | `https://api.yourgpt.ai` | API base URL (override for dev/staging) |

<Callout type="warn">
  **Never expose `apiKey` to the browser.** The YourGPT adapter runs on your server only. The client communicates through your server endpoints.
</Callout>

### What it does automatically

When plugged into `createRuntime({ storage: yourgpt })`:

1. **First message (no threadId)** → Creates a session via YourGPT API → Returns `threadId` to client
2. **Before LLM call** → Saves user message to the session
3. **After LLM response** → Saves assistant response + tool calls to the session
4. **File uploads** → Uploads media to YourGPT storage, returns URL

### API Endpoints Used

| Action | Endpoint | When |
|--------|----------|------|
| Create session | `/chatbot/v1/copilot-sdk/createSession` | First message without threadId |
| Save message | `/chatbot/v1/copilot-sdk/createMessage` | Every user/assistant message |
| Save tool call | `/chatbot/v1/copilot-sdk/createToolMessage` | Tool dispatches + results |
| Upload file | `/chatbot/v1/copilot-sdk/uploadMedia` | File attachments |

---

## Custom Storage Adapter

Build your own adapter for any backend — Supabase, Firebase, your own database, etc.

### Interface

```ts

const myStorage: StorageAdapter = {
  async createSession(data) {
    const session = await db.sessions.create({ title: data?.title });
    return { id: session.id };
  },

  async saveMessages(sessionId, messages) {
    await db.messages.insertMany(
      messages.map(msg => ({
        sessionId,
        role: msg.role,
        content: msg.content,
        toolCalls: msg.toolCalls,
        toolCallId: msg.toolCallId,
      }))
    );
  },

  // Optional: file uploads
  async uploadFile(file) {
    const blob = Buffer.from(file.data, 'base64');
    const url = await s3.upload(blob, file.mimeType, file.filename);
    return { url };
  },
};

const runtime = createRuntime({
  provider: anthropic,
  model: 'claude-haiku-4-5',
  storage: myStorage,
});
```

### StorageAdapter Interface

```ts
interface StorageAdapter {
  /** Create a new session. Returns session ID. */
  createSession(data?: {
    title?: string;
    metadata?: Record<string, unknown>;
  }): Promise<{ id: string }>;

  /** Append messages to a session. */
  saveMessages(sessionId: string, messages: StorageMessage[]): Promise<void>;

  /** Upload a file. Returns URL. (Optional) */
  uploadFile?(file: StorageFile): Promise<{ url: string }>;

  /** List sessions. (Optional — future use) */
  getSessions?(): Promise<{ id: string; title?: string; updatedAt?: Date }[]>;

  /** Get messages for a session. (Optional — future use) */
  getMessages?(sessionId: string): Promise<StorageMessage[]>;
}
```

### StorageMessage

```ts
interface StorageMessage {
  role: 'user' | 'assistant' | 'system' | 'tool';
  content: string;
  toolCalls?: unknown[];
  toolCallId?: string;
  metadata?: Record<string, unknown>;
}
```

---

## How It Works

### Session Creation Flow

```
Client sends first message (no threadId)
  → Server runtime: storage.createSession()
  → Server runtime: storage.saveMessages(threadId, [userMsg])
  → LLM processes message
  → Server runtime: storage.saveMessages(threadId, [assistantMsg])
  → Response includes threadId
  → Client adopts threadId for future requests
```

### Subsequent Messages

```
Client sends message (with threadId)
  → Server runtime: storage.saveMessages(threadId, [userMsg])
  → LLM processes message
  → Server runtime: storage.saveMessages(threadId, [assistantMsg])
```

### Error Handling

If `createSession` fails, the runtime:
- Generates a fallback local thread ID (`local_xxx`)
- Skips all storage calls for that request
- Chat continues working normally (graceful degradation)
- Error is logged once

### Error Callback

Register an `onError` handler to monitor all adapter operations:

```ts
const yourgpt = createYourGPT({
  apiKey: process.env.YOURGPT_API_KEY,
  widgetUid: process.env.YOURGPT_WIDGET_UID,
  onError: (error, operation, params) => {
    console.error(`[YourGPT:${operation}]`, error.message, params);
    // Send to Sentry, Datadog, etc.
    Sentry.captureException(error, {
      tags: { operation },
      extra: params,
    });
  },
});
```

| Argument | Type | Description |
|----------|------|-------------|
| `error` | `Error` | The error that occurred |
| `operation` | `string` | `"createSession"` \| `"saveMessages"` \| `"uploadFile"` |
| `params` | `object` | Context — varies by operation (sessionId, messageCount, filename, etc.) |

The error is still re-thrown after `onError` runs, so the runtime's graceful degradation continues to work.

---

## File Uploads

When the storage adapter has `uploadFile`, expose an upload endpoint on your server:

```ts
app.post('/api/copilot/upload', async (req, res) => {
  const { data, mimeType, filename } = req.body;
  const result = await yourgpt.uploadFile({ data, mimeType, filename });
  res.json(result);
});
```

Then on the client, use the `upload` prop:

```tsx
<CopilotChat upload="/api/copilot/upload" />
```

Files are uploaded to the server, which forwards them to the storage adapter. The returned URL is sent with the message instead of base64 data.

See [Attachments](/docs/attachments) for more on file attachments.

---

## Complete Example

<Tabs items={['YourGPT', 'Custom (Supabase)']}>
  <Tab value="YourGPT">
    ```ts title="server.ts"
    import { createRuntime } from '@yourgpt/llm-sdk';
    import { createAnthropic } from '@yourgpt/llm-sdk/anthropic';
    import { createYourGPT } from '@yourgpt/llm-sdk/yourgpt';
    import express from 'express';

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

    const yourgpt = createYourGPT({
      apiKey: process.env.YOURGPT_API_KEY!,
      widgetUid: process.env.YOURGPT_WIDGET_UID!,
    });

    const runtime = createRuntime({
      provider: createAnthropic({ apiKey: process.env.ANTHROPIC_API_KEY }),
      model: 'claude-haiku-4-5',
      storage: yourgpt,
    });

    // Chat — sessions + messages handled automatically
    app.post('/api/copilot/chat', async (req, res) => {
      const result = await runtime.chat(req.body);
      res.json(result);
    });

    // Stream — same automatic handling
    app.post('/api/copilot/stream', async (req, res) => {
      await runtime.stream(req.body).pipeToResponse(res);
    });

    // File upload — uses same YourGPT credentials
    app.post('/api/copilot/upload', async (req, res) => {
      const result = await yourgpt.uploadFile(req.body);
      res.json(result);
    });

    app.listen(3001);
    ```
  </Tab>
  <Tab value="Custom (Supabase)">
    ```ts title="server.ts"
    import { createRuntime, type StorageAdapter } from '@yourgpt/llm-sdk';
    import { createAnthropic } from '@yourgpt/llm-sdk/anthropic';
    import { createClient } from '@supabase/supabase-js';
    import express from 'express';

    const supabase = createClient(
      process.env.SUPABASE_URL!,
      process.env.SUPABASE_KEY!,
    );

    const storage: StorageAdapter = {
      async createSession(data) {
        const { data: session } = await supabase
          .from('sessions')
          .insert({ title: data?.title })
          .select('id')
          .single();
        return { id: session!.id };
      },
      async saveMessages(sessionId, messages) {
        await supabase.from('messages').insert(
          messages.map(m => ({ session_id: sessionId, ...m }))
        );
      },
    };

    const runtime = createRuntime({
      provider: createAnthropic({ apiKey: process.env.ANTHROPIC_API_KEY }),
      model: 'claude-haiku-4-5',
      storage,
    });

    const app = express();
    app.use(express.json());

    app.post('/api/copilot/chat', async (req, res) => {
      const result = await runtime.chat(req.body);
      res.json(result);
    });

    app.listen(3001);
    ```
  </Tab>
</Tabs>

---

## Client-side Skills
URL: https://copilot-sdk.yourgpt.ai/docs/skills/client
Description: Register skills from React components using SkillProvider and useSkill

<Callout type="warn">
**Beta** — This feature is in **alpha**. APIs may change before stable release.
</Callout>

Register skills from your React app using `<SkillProvider>`, `useSkill`, and `defineSkill`.

<Callout type="info">
Client-side skills only support `inline` source. For `file` or `url` sources, use [server-side skills](/docs/skills/server).
</Callout>

---

## SkillProvider

Wrap your app inside `<CopilotProvider>` to enable client-side skills:

```tsx

const brandVoice = defineSkill({
  name: "brand-voice",
  description: "Ensures responses match our brand tone and terminology",
  strategy: "eager",
  source: {
    type: "inline",
    content: "Always respond in a friendly, concise tone. Use 'we' not 'I'. Avoid jargon.",
  },
});

const codeReview = defineSkill({
  name: "code-review",
  description: "Performs structured code reviews with actionable feedback",
  strategy: "auto",
  source: {
    type: "inline",
    content: "When reviewing code: 1) Check for bugs first...",
  },
});

export default function App() {
  return (
    <CopilotProvider widgetToken="...">
      <SkillProvider skills={[brandVoice, codeReview]}>
        <YourApp />
      </SkillProvider>
    </CopilotProvider>
  );
}
```

---

## useSkill

Register a skill from deep inside the component tree. It activates on mount and cleans up on unmount — useful for page-scoped skills.

```tsx

function CheckoutPage() {
  useSkill({
    name: "checkout-flow",
    description: "Guides the user through the checkout process step by step",
    strategy: "auto",
    source: {
      type: "inline",
      content: `
## Checkout Assistant

When the user asks about checkout:
1. Confirm their cart items
2. Check for applicable promo codes
3. Walk through shipping options
4. Confirm payment method before submitting
      `,
    },
  });

  return <CheckoutUI />;
}
```

The skill is automatically unregistered when `CheckoutPage` unmounts.

<Callout type="info">
If an inline skill exceeds 2000 characters in development, a console warning is shown. Large inline skills are sent on every request — consider using a server-side file skill instead.
</Callout>

---

## defineSkill

Type-safe factory for creating skill definitions. An identity function with TypeScript inference:

```typescript

const mySkill = defineSkill({
  name: "api-docs-helper",
  description: "Helps users understand and use the Acme API",
  strategy: "auto",
  version: "2.0.0",
  source: {
    type: "inline",
    content: "When explaining API endpoints, always include example requests...",
  },
});

// Reuse in multiple providers
<SkillProvider skills={[mySkill]} />
```

---

## useSkillStatus

Observe the live skill registry from any component inside `<SkillProvider>`:

```tsx

function DebugPanel() {
  const { skills, count, has } = useSkillStatus();

  return (
    <div>
      <p>{count} skill(s) active</p>
      {has("code-review") && <Badge>Code Review</Badge>}
      <ul>
        {skills.map((s) => (
          <li key={s.name}>
            {s.name} ({s.strategy ?? "auto"})
          </li>
        ))}
      </ul>
    </div>
  );
}
```

### Return type

```typescript
interface UseSkillStatusReturn {
  skills: ResolvedSkill[];          // All currently registered skills
  count: number;                    // Number of registered skills
  has: (name: string) => boolean;   // Check if a named skill is active
}
```

---

## Type Reference

```typescript
type SkillStrategy = "eager" | "auto" | "manual";

interface SkillDefinition {
  name: string;
  description: string;
  source: { type: "inline"; content: string };
  strategy?: SkillStrategy; // default: "auto"
  version?: string;
}
```

---

## Skills
URL: https://copilot-sdk.yourgpt.ai/docs/skills
Description: Instruction playbooks that shape the AI's behavior — loaded on demand

<Callout type="warn">
**Beta** — This feature is in **alpha**. APIs may change before stable release.
</Callout>

Skills are instruction playbooks the AI loads on demand. They shape the model's **behavior** — separate from [Tools](/docs/tools), which perform actions.

A skill is a Markdown file (or inline string) containing instructions. The AI only loads a skill when it's relevant to the user's query — keeping the system prompt lean.

---

## Strategies

| Strategy | Behavior |
|----------|----------|
| `eager` | Content prepended to system prompt on every request. Always active. |
| `auto` | Listed in the skill catalog. AI calls `load_skill` to retrieve when relevant. |
| `manual` | Accessible via `load_skill` but not advertised in the catalog. For internal/conditional skills. |

The `load_skill` tool is automatically registered when a `<SkillProvider>` is present (client) or when `loadSkills()` builds the tools object (server). **No manual wiring required.**

---

## Skills vs Tools

| | Skills | Tools |
|--|--------|-------|
| **Purpose** | Shape behavior | Perform actions |
| **Payload** | Markdown instructions | Code that runs |
| **Loading** | Into system prompt | Into tool list |
| **Example** | "Always respond in formal English" | `get_weather({ city })` |

---

## Quick Example

```tsx

const brandVoice = defineSkill({
  name: "brand-voice",
  description: "Ensures responses match our brand tone",
  strategy: "eager",  // always active
  source: {
    type: "inline",
    content: "Always respond in a friendly, concise tone. Use 'we' not 'I'.",
  },
});

const sqlExpert = defineSkill({
  name: "sql-expert",
  description: "Writes and explains SQL queries",
  strategy: "auto",   // AI loads when the user asks about SQL
  source: {
    type: "inline",
    content: "When writing SQL: always use parameterized queries...",
  },
});

export default function App() {
  return (
    <CopilotProvider widgetToken="...">
      <SkillProvider skills={[brandVoice, sqlExpert]}>
        <YourApp />
      </SkillProvider>
    </CopilotProvider>
  );
}
```

---

## Skill File Format

Skill files are Markdown with optional YAML frontmatter:

```markdown
---
name: code-review
description: Performs structured code reviews with actionable feedback
strategy: auto
version: 1.2.0
---

## Code Review Instructions

When asked to review code, follow this structure:

1. **Correctness** — Check for logic errors and edge cases
2. **Security** — Flag injection risks, exposed secrets, insecure defaults
3. **Performance** — Note O(n²) loops, unnecessary re-renders, missing indexes
4. **Style** — Suggest naming and structure improvements (non-blocking)
```

### Frontmatter fields

| Field | Required | Description |
|-------|----------|-------------|
| `name` | Recommended | Skill name. Derived from filename if omitted. |
| `description` | Recommended | One-line description shown in the AI's skill catalog. |
| `strategy` | No | `eager`, `auto`, or `manual`. Default: `auto`. |
| `version` | No | Informational version string. |

---

## Directory Layout

```
skills/
├── brand-voice.md       # Flat .md file
├── code-review.md
└── sql-expert/
    └── SKILL.md         # Folder-based skill
```

For folder-based skills, place the main content at `<folder>/SKILL.md`. The folder name is used as the skill name unless overridden by frontmatter.

---

## Next Steps

- [Client-side Skills](/docs/skills/client) — `SkillProvider`, `useSkill`, `useSkillStatus`
- [Server-side Skills](/docs/skills/server) — `loadSkills()`, file/URL sources, collision detection

---

## Server-side Skills
URL: https://copilot-sdk.yourgpt.ai/docs/skills/server
Description: Load skills from files and URLs on the server with loadSkills()

<Callout type="warn">
**Beta** — This feature is in **alpha**. APIs may change before stable release.
</Callout>

For `file` and `url` skill sources, or when you need server-controlled skill loading, use `loadSkills()` in your API route.

---

## Basic Setup

```typescript
// app/api/chat/route.ts

export async function POST(req: Request) {
  const { messages, __skills } = await req.json();

  const { buildSystemPrompt, tools } = await loadSkills({
    // Source 1: .md files from a local directory (highest precedence)
    dir: path.join(process.cwd(), "skills"),

    // Source 2: Remote .md URLs
    remoteUrls: ["https://cdn.myapp.com/skills/support-policy.md"],

    // Source 3: Inline skills forwarded from client (lowest precedence)
    clientSkills: __skills ?? [],
  });

  return streamText({
    model: anthropic("claude-sonnet-4-6"),
    system: buildSystemPrompt("You are a helpful assistant for Acme Corp."),
    messages,
    tools: {
      ...tools,         // includes load_skill automatically
      ...myOtherTools,
    },
  }).toDataStreamResponse();
}
```

---

## loadSkills Options

```typescript
interface LoadSkillsOptions {
  dir?: string;                     // Path to /skills directory (Node.js only)
  remoteUrls?: string[];            // Remote .md URLs to fetch
  clientSkills?: ClientInlineSkill[]; // Forwarded from useSkill() hooks
}
```

## loadSkills Result

```typescript
interface LoadSkillsResult {
  skills: ResolvedSkill[];
  diagnostics: SkillDiagnostic[];

  // Build system prompt: prepends eager content, appends auto catalog
  buildSystemPrompt(basePrompt?: string): string;

  // Ready-to-use load_skill tool definition
  tools: {
    load_skill: ToolDefinition;
  };
}
```

---

## Forwarding Client Skills

`<SkillProvider>` automatically syncs inline skills to `CopilotProvider`, which includes them in every API request as `__skills`. Read them in your route:

```typescript
const { messages, __skills } = await req.json();

const { buildSystemPrompt, tools } = await loadSkills({
  dir: path.join(process.cwd(), "skills"),
  clientSkills: __skills ?? [],
});
```

---

## Source Precedence & Collision Detection

When the same skill name appears in multiple sources, the higher-precedence source wins:

```
server-dir  >  remote-url  >  client-inline
```

```typescript
const { diagnostics } = await loadSkills({ ... });

// [{
//   type: "collision",
//   name: "code-review",
//   winner: "server-dir",
//   loser: "client-inline",
// }]
if (diagnostics.length) {
  console.warn("Skill collisions:", diagnostics);
}
```

This lets you safely override client-provided skills with authoritative server versions.

---

## Full Example

### Project structure

```
skills/
├── brand-voice.md     # eager — always active
└── sql-expert.md      # auto — loaded on demand
```

### API route

```typescript
// app/api/chat/route.ts

export async function POST(req: Request) {
  const { messages, __skills } = await req.json();

  const { buildSystemPrompt, tools } = await loadSkills({
    dir: path.join(process.cwd(), "skills"),
    clientSkills: __skills ?? [],
  });

  return streamText({
    model: anthropic("claude-sonnet-4-6"),
    system: buildSystemPrompt("You are a helpful assistant for Acme Corp."),
    messages,
    tools,
  }).toDataStreamResponse();
}
```

---

## Type Reference

```typescript
type SkillStrategy = "eager" | "auto" | "manual";

type SkillSource =
  | { type: "inline"; content: string }
  | { type: "url"; url: string }
  | { type: "file"; path: string };

interface ResolvedSkill {
  name: string;
  description: string;
  content: string;
  strategy?: SkillStrategy;
  version?: string;
}

interface SkillDiagnostic {
  type: "collision";
  name: string;
  winner: "server-dir" | "remote-url" | "client-inline";
  loser: "server-dir" | "remote-url" | "client-inline";
}
```

---

## Multi-Step
URL: https://copilot-sdk.yourgpt.ai/docs/tools/agentic-loop
Description: Multi-step AI reasoning with continuous tool calls

Enable AI to make multiple tool calls in sequence, reasoning through complex tasks step by step.

---

## Overview

Without agentic loop:
```
User: "Book a flight to NYC and a hotel nearby"
AI: [Calls book_flight] → Done (forgot hotel)
```

With agentic loop:
```
User: "Book a flight to NYC and a hotel nearby"
AI: [Calls search_flights]
    → Analyzes results
    → [Calls book_flight]
    → [Calls search_hotels]
    → [Calls book_hotel]
    → "Done! Booked flight UA123 and Hotel Marriott Times Square"
```

---

## How It Works

```
┌─────────────────────────────────────────────────────────────┐
│                      Agentic Loop                           │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  User Message                                               │
│       ↓                                                     │
│  ┌─────────────┐                                           │
│  │   LLM       │ ← Decides what tool to call               │
│  └─────────────┘                                           │
│       ↓                                                     │
│  ┌─────────────┐                                           │
│  │ Tool Exec   │ ← Executes tool, gets result              │
│  └─────────────┘                                           │
│       ↓                                                     │
│  ┌─────────────┐                                           │
│  │   LLM       │ ← Analyzes result, decides next step      │
│  └─────────────┘                                           │
│       ↓                                                     │
│  [Repeat until task complete or max iterations]             │
│       ↓                                                     │
│  Final Response                                             │
│                                                             │
└─────────────────────────────────────────────────────────────┘
```

---

## Configuration

### Server-Side (Recommended)

Configure the agentic loop on the backend runtime:

```ts
// app/api/chat/route.ts

const runtime = createRuntime({
  provider: createOpenAI({ apiKey: process.env.OPENAI_API_KEY }),
  model: 'gpt-4o',
  // Agentic loop settings
  agentLoop: {
    maxIterations: 20,  // Maximum tool call cycles (default: 20)
    debug: true,        // Enable debug logging
  },
});

export async function POST(request: Request) {
  return runtime.handleRequest(request);
}
```

### Client-Side

You can also set `maxIterations` on the `CopilotProvider` (sent with each request):

```tsx
<CopilotProvider
  runtimeUrl="/api/chat"
  maxIterations={10}  // Override server default for this client
>
  {children}
</CopilotProvider>
```

<Callout type="info">
Client-side `maxIterations` is passed in the request body. The server can enforce a maximum limit.
</Callout>

### maxIterations

Prevents infinite loops by limiting how many times AI can call tools:

| Value | Use Case |
|-------|----------|
| `5` | Simple tasks, quick responses |
| `10` | Medium complexity |
| `20` | Complex multi-step tasks (default) |
| `50` | Very complex workflows |

<Callout type="warning">
Higher values allow more complex tasks but increase latency and token usage. Start low and increase as needed.
</Callout>

---

## Tracking Execution State

Monitor the agentic loop from the frontend:

```tsx

function AgentProgress() {
  const { toolExecutions, isLoading } = useCopilot();

  // Filter to current batch
  const currentExecutions = toolExecutions.filter(
    exec => exec.status === 'executing' || exec.status === 'completed'
  );

  if (!isLoading || currentExecutions.length === 0) {
    return null;
  }

  return (
    <div className="p-4 border rounded-lg bg-muted/50">
      <p className="text-sm font-medium mb-2">AI is working...</p>
      <div className="space-y-2">
        {currentExecutions.map(exec => (
          <div key={exec.id} className="flex items-center gap-2 text-sm">
            {exec.status === 'executing' ? (
              <Spinner className="h-4 w-4" />
            ) : (
              <Check className="h-4 w-4 text-green-500" />
            )}
            <span>{exec.name}</span>
          </div>
        ))}
      </div>
    </div>
  );
}
```

---

## Tool Execution States

```typescript
type ToolExecutionStatus =
  | 'pending'      // Waiting to start
  | 'executing'    // Currently running
  | 'completed'    // Finished successfully
  | 'error'        // Failed with error
  | 'failed'       // Handler threw exception
  | 'rejected';    // User rejected approval
```

Track these to show progress:

```tsx
function ExecutionTimeline({ executions }) {
  return (
    <div className="space-y-2">
      {executions.map((exec, i) => (
        <div key={exec.id} className="flex items-center gap-3">
          <div className={cn(
            "w-2 h-2 rounded-full",
            exec.status === 'completed' && "bg-green-500",
            exec.status === 'executing' && "bg-blue-500 animate-pulse",
            exec.status === 'error' && "bg-red-500",
            exec.status === 'pending' && "bg-gray-300",
          )} />
          <span className="text-sm">
            {i + 1}. {exec.name}
            {exec.status === 'completed' && ' ✓'}
          </span>
        </div>
      ))}
    </div>
  );
}
```

---

## Example: Multi-Step Task

```tsx
// Define interconnected tools
useTools({
  search_products: {
    description: 'Search for products',
    parameters: z.object({ query: z.string() }),
    handler: async ({ query }) => {
      const products = await searchAPI(query);
      return { success: true, data: products };
    },
  },

  get_product_details: {
    description: 'Get detailed info about a product',
    parameters: z.object({ productId: z.string() }),
    handler: async ({ productId }) => {
      const details = await getProductDetails(productId);
      return { success: true, data: details };
    },
  },

  check_availability: {
    description: 'Check if product is available in user location',
    parameters: z.object({ productId: z.string(), zipCode: z.string() }),
    handler: async ({ productId, zipCode }) => {
      const availability = await checkStock(productId, zipCode);
      return { success: true, data: availability };
    },
  },

  add_to_cart: {
    description: 'Add product to shopping cart',
    parameters: z.object({ productId: z.string(), quantity: z.number() }),
    handler: async ({ productId, quantity }) => {
      await cart.add(productId, quantity);
      return { success: true, message: 'Added to cart' };
    },
  },
});
```

**User prompt:** "Find wireless headphones under $100 that ship to 94102 and add the best one to my cart"

**AI executes:**
1. `search_products({ query: "wireless headphones under $100" })`
2. Analyzes results, picks top rated
3. `get_product_details({ productId: "prod_123" })`
4. `check_availability({ productId: "prod_123", zipCode: "94102" })`
5. Confirms available
6. `add_to_cart({ productId: "prod_123", quantity: 1 })`
7. Returns: "Added Sony WH-1000XM4 ($89.99) to your cart. Ships to 94102 in 2 days."

---

## Stopping the Loop

Users can stop the agentic loop mid-execution:

```tsx
function ChatControls() {
  const { isLoading, stop } = useCopilot();

  return (
    <div>
      {isLoading && (
        <button onClick={stop} className="btn-secondary">
          Stop AI
        </button>
      )}
    </div>
  );
}
```

---

## Progress UI Pattern

Show users what's happening:

```tsx
function AgenticProgress() {
  const { toolExecutions, isLoading, status } = useCopilot();

  // Only show during active tool execution
  const isProcessingTools = isLoading && toolExecutions.some(
    e => e.status === 'executing'
  );

  if (!isProcessingTools) return null;

  const completed = toolExecutions.filter(e => e.status === 'completed').length;
  const total = toolExecutions.length;

  return (
    <div className="fixed bottom-20 left-1/2 -translate-x-1/2 bg-background border rounded-lg shadow-lg p-4">
      <div className="flex items-center gap-3">
        <Spinner />
        <div>
          <p className="font-medium">Working on it...</p>
          <p className="text-sm text-muted-foreground">
            Step {completed + 1} of {total}
          </p>
        </div>
      </div>
    </div>
  );
}
```

---

## Best Practices

### 1. Design Tools for Composition

```tsx
// ✅ Good - small, composable tools
useTools({
  get_user: { /* ... */ },
  get_orders: { /* ... */ },
  get_order_details: { /* ... */ },
  cancel_order: { /* ... */ },
});

// ❌ Bad - monolithic tool
useTools({
  manage_everything: {
    // Does too much, AI can't break down tasks
  },
});
```

### 2. Return Helpful Results

```tsx
// ✅ Good - AI can reason about this
return {
  success: true,
  data: {
    found: 5,
    products: results,
    suggestion: results.length === 0 ? 'Try broader search terms' : null,
  },
};

// ❌ Bad - opaque result
return { ok: true };
```

### 3. Handle Long Operations

```tsx
useTools({
  generate_report: {
    description: 'Generate analytics report (may take 30s)',
    handler: async ({ timeRange }) => {
      // For long operations, provide progress hints
      return {
        success: true,
        data: report,
        _aiContext: 'Report generated. Contains 50 pages of analytics.',
      };
    },
  },
});
```

---

## Tracking Iteration Progress

Use `agentIteration` from `useCopilot()` to show which reasoning step the AI is on in real time:

```tsx
function AgentStatus() {
  const { isLoading, agentIteration } = useCopilot();

  if (!isLoading) return null;

  return (
    <div className="text-sm text-muted-foreground">
      {agentIteration > 0
        ? `Reasoning... (step ${agentIteration})`
        : 'Thinking...'}
    </div>
  );
}
```

`agentIteration` increments by 1 each time the AI completes a tool call and continues reasoning. It resets to `0` at the start of each new user message.

### Checkpoints

`useMessageCheckpoints` lets you save and restore specific points in the conversation — useful for letting users branch off mid-task or undo multi-step AI actions:

```tsx

function CheckpointControls() {
  const { saveCheckpoint, restoreCheckpoint, checkpoints } = useMessageCheckpoints();

  return (
    <div>
      <button onClick={() => saveCheckpoint('before-bulk-edit')}>
        Save checkpoint
      </button>
      {checkpoints.map((cp) => (
        <button key={cp.id} onClick={() => restoreCheckpoint(cp.id)}>
          Restore: {cp.label}
        </button>
      ))}
    </div>
  );
}
```

### Inline Editing

Pass `allowEdit` to `CopilotChat` to let users edit any AI message and re-run from that point:

```tsx
<CopilotChat allowEdit />
```

Editing an AI message discards all subsequent messages in the thread and re-sends from the edited content, effectively branching the conversation from that point.

---

## Callbacks (Advanced)

Listen to agentic loop events:

```tsx
// In provider setup
<CopilotProvider
  runtimeUrl="/api/chat"
  onToolStart={(execution) => {
    console.log('Tool starting:', execution.name);
    analytics.track('tool_start', { tool: execution.name });
  }}
  onToolComplete={(execution) => {
    console.log('Tool completed:', execution.name);
  }}
  onMaxIterationsReached={() => {
    toast.warning('AI reached maximum steps. Task may be incomplete.');
  }}
>
```

---

## AbstractAgentLoop (Framework-Agnostic)

For non-React or custom setups, use `AbstractAgentLoop` directly to manage tool execution, approvals, and cancellation.

```typescript

const loop = new AbstractAgentLoop(
  {
    maxIterations: 20,
    tools: [myTool],
  },
  {
    onToolExecutionsChange: (executions) => setExecutions(executions),
    onToolApprovalRequired: (execution) => showApprovalModal(execution),
  },
);

// Register/unregister tools at runtime
loop.registerTool(weatherTool);
loop.unregisterTool("old_tool");

// Execute tool calls returned by the LLM
const results = await loop.executeToolCalls(toolCallsFromLLM);

// Cancel in-flight execution
loop.cancel();
```

```typescript
interface AgentLoopConfig {
  maxIterations?: number;        // default: 20
  maxExecutionHistory?: number;  // default: 100
  tools?: ToolDefinition[];
}
```

Tools use reference counting so React StrictMode double-invocations don't leave orphaned registrations.

---

## Next Steps

- [Tool Approval](/docs/tools/frontend-tools) - Add human confirmation
- [Streaming](/docs/llm-sdk/stream-text) - Real-time updates

---

## Server Tools
URL: https://copilot-sdk.yourgpt.ai/docs/tools/backend-tools
Description: Execute tools securely on the server with full API access

Execute tools securely on your backend with access to databases, APIs, and secrets.

---

## Why Backend Tools?

| Frontend Tools | Backend Tools |
|---------------|---------------|
| Run in browser | Run on server |
| User can inspect | Code stays private |
| No secrets access | Full secrets access |
| Limited capabilities | Database, APIs, files |

Backend tools are perfect for:
- Database queries and mutations
- Calling internal microservices
- External API integrations with secret keys
- File operations and data processing

---

## Basic Usage

Define tools in your API route using the `tool()` helper:

```ts title="app/api/chat/route.ts"

export async function POST(req: Request) {
  const { messages } = await req.json();

  const result = await streamText({
    model: openai('gpt-4o'),
    system: 'You are a helpful assistant.',
    messages,
    tools: {
      searchProducts: tool({
        description: 'Search the product database',
        parameters: z.object({
          query: z.string().describe('Search query'),
          limit: z.number().optional().default(10),
        }),
        execute: async ({ query, limit }) => {
          const results = await db.products.search(query, limit);
          return results;
        },
      }),
    },
    maxSteps: 5,
  });

  return result.toDataStreamResponse();
}
```

---

## Tool Structure

```ts
tool({
  // Required: Tell the AI what this tool does
  description: 'Description of what the tool does',

  // Required: Zod schema for parameters
  parameters: z.object({
    param1: z.string().describe('Description for AI'),
    param2: z.number().optional(),
  }),

  // Required: Function to execute
  execute: async (params, context) => {
    // params is typed from your Zod schema
    // context provides { toolCallId, abortSignal, messages }
    return { result: 'data' };
  },
})
```

| Field | Required | Description |
|-------|----------|-------------|
| `description` | Yes | What the tool does (AI reads this) |
| `parameters` | Yes | Zod schema for inputs |
| `execute` | Yes | Async function that runs on server |

---

## Tool Context

The execute function receives a context object with useful information:

```ts
execute: async (params, context) => {
  // Unique ID for this tool call
  console.log('Tool call ID:', context.toolCallId);

  // Check for cancellation
  if (context.abortSignal?.aborted) {
    throw new Error('Request cancelled');
  }

  // Access conversation history
  console.log('Messages:', context.messages);

  return { result: 'data' };
}
```

---

## Multiple Tools

Pass multiple tools to let the AI choose:

```ts
tools: {
  queryProducts: tool({
    description: 'Search for products in the database',
    parameters: z.object({
      query: z.string(),
      category: z.enum(['electronics', 'clothing', 'home']).optional(),
    }),
    execute: async ({ query, category }) => {
      return await db.products.search({ query, category });
    },
  }),

  createOrder: tool({
    description: 'Create a new order for a product',
    parameters: z.object({
      productId: z.string(),
      quantity: z.number().default(1),
    }),
    execute: async ({ productId, quantity }) => {
      return await db.orders.create({ productId, quantity });
    },
  }),

  sendEmail: tool({
    description: 'Send an email notification',
    parameters: z.object({
      to: z.string().email(),
      subject: z.string(),
      body: z.string(),
    }),
    execute: async ({ to, subject, body }) => {
      await emailService.send({ to, subject, body });
      return { sent: true };
    },
  }),
},
maxSteps: 10,
```

---

## Database Integration

```ts

const dbTools = {
  queryUsers: tool({
    description: 'Query users from the database',
    parameters: z.object({
      filter: z.object({
        email: z.string().optional(),
        role: z.enum(['admin', 'user']).optional(),
      }).optional(),
      limit: z.number().default(10),
    }),
    execute: async ({ filter, limit }) => {
      const users = await db.user.findMany({
        where: filter,
        take: limit,
        select: { id: true, email: true, name: true, role: true },
      });
      return users;
    },
  }),

  updateUser: tool({
    description: 'Update a user in the database',
    parameters: z.object({
      userId: z.string(),
      data: z.object({
        name: z.string().optional(),
        role: z.enum(['admin', 'user']).optional(),
      }),
    }),
    execute: async ({ userId, data }) => {
      const user = await db.user.update({
        where: { id: userId },
        data,
      });
      return { updated: true, user };
    },
  }),
};
```

---

## API Integration

```ts
const apiTools = {
  getWeather: tool({
    description: 'Get current weather for a city',
    parameters: z.object({
      city: z.string().describe('City name'),
    }),
    execute: async ({ city }) => {
      const response = await fetch(
        `https://api.weather.com/v1/current?city=${city}&key=${process.env.WEATHER_API_KEY}`
      );
      return response.json();
    },
  }),

  createPayment: tool({
    description: 'Process a payment',
    parameters: z.object({
      amount: z.number(),
      currency: z.enum(['usd', 'eur', 'gbp']).default('usd'),
    }),
    execute: async ({ amount, currency }) => {
      const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);
      const intent = await stripe.paymentIntents.create({
        amount: amount * 100,
        currency,
      });
      return { clientSecret: intent.client_secret };
    },
  }),
};
```

<Callout type="info">
Backend tools have full access to environment variables and secrets. Never expose sensitive data in tool responses.
</Callout>

---

## Error Handling

Errors in tools are caught and passed back to the AI:

```ts
execute: async ({ userId }) => {
  try {
    const user = await db.user.findUnique({ where: { id: userId } });

    if (!user) {
      return { error: 'User not found', userId };
    }

    return { success: true, user };
  } catch (error) {
    return {
      error: error instanceof Error ? error.message : 'Database error',
    };
  }
}
```

The AI will see the error and can inform the user or try a different approach.

---

## AI Response Control

Control how the AI responds after tool execution:

```ts
execute: async ({ query }) => {
  const results = await db.products.search(query);

  return {
    data: results,
    _aiResponseMode: 'brief',     // 'verbose' | 'brief' | 'silent'
    _aiContext: `Found ${results.length} products`,
  };
}
```

| Mode | Behavior |
|------|----------|
| `verbose` | AI explains results in detail |
| `brief` | AI gives short summary |
| `silent` | No AI response, just show tool result |

---

## Best Practices

1. **Clear descriptions** - AI uses this to decide when to call the tool
2. **Validate with Zod** - Type safety and clear parameter documentation
3. **Return structured data** - AI understands JSON better than strings
4. **Handle errors gracefully** - Return error info instead of throwing
5. **Limit data exposure** - Only return what the AI needs
6. **Use environment variables** - Keep secrets in `.env`, never hardcode

---

## Next Steps

- [Frontend Tools](/docs/tools/frontend-tools) - Client-side tools
- [Agentic Loop](/docs/tools/agentic-loop) - Multi-step execution
- [Server Setup](/docs/server) - Configure your backend

---

## Client Tools
URL: https://copilot-sdk.yourgpt.ai/docs/tools/frontend-tools
Description: Build client-side tools that run in the browser

Create tools that run in the browser with access to DOM, state, and UI.

---

## Why Frontend Tools?

- **Access browser APIs** - DOM, localStorage, navigation
- **Use React state** - Read/write app state directly
- **Show rich UI** - Render components as results
- **Real-time updates** - Stream results as they happen

---

## Basic Tool

```tsx

function MyTools() {
  useTools({
    search_products: {
      description: 'Search the product catalog',
      parameters: z.object({
        query: z.string().describe('Search query'),
        limit: z.number().optional().default(10),
      }),
      handler: async ({ query, limit }) => {
        const results = await fetch(`/api/search?q=${query}&limit=${limit}`);
        return results.json();
      },
    },
  });

  return null;
}
```

---

## Tool Structure

| Field | Required | Description |
|-------|----------|-------------|
| `description` | Yes | What the tool does (AI reads this) |
| `parameters` | Yes | Zod schema for inputs |
| `handler` | Yes | Async function that runs |
| `requiresApproval` | No | Ask user before running |
| `hidden` | No | Hide tool from chat UI (still executes) |

---

## Multiple Tools

```tsx
useTools({
  get_weather: {
    description: 'Get weather for a city',
    parameters: z.object({ city: z.string() }),
    handler: async ({ city }) => fetchWeather(city),
  },

  add_to_cart: {
    description: 'Add product to cart',
    parameters: z.object({
      productId: z.string(),
      quantity: z.number().default(1),
    }),
    handler: async ({ productId, quantity }) => {
      await cart.add(productId, quantity);
      return { success: true };
    },
  },

  navigate: {
    description: 'Go to a page in the app',
    parameters: z.object({ path: z.string() }),
    handler: async ({ path }) => {
      router.push(path);
      return { navigated: path };
    },
  },
});
```

---

## With Approval

Require user confirmation before running:

```tsx
useTools({
  delete_account: {
    description: 'Permanently delete user account',
    parameters: z.object({}),
    requiresApproval: true,
    handler: async () => {
      await deleteAccount();
      return { deleted: true };
    },
  },
});
```

<Callout type="warning">
Use `requiresApproval: true` for destructive or sensitive actions.
</Callout>

---

## Hidden Tools

Hide tool execution from the chat UI while still executing normally:

```tsx
useTools({
  navigate: {
    description: 'Navigate to a page in the app',
    parameters: z.object({ path: z.string() }),
    hidden: true, // Won't show in chat UI
    handler: async ({ path }) => {
      router.push(path);
      return { navigated: path };
    },
  },

  track_event: {
    description: 'Track analytics event',
    parameters: z.object({
      event: z.string(),
      properties: z.record(z.any()).optional(),
    }),
    hidden: true, // Silent background operation
    handler: async ({ event, properties }) => {
      analytics.track(event, properties);
      return { tracked: true };
    },
  },
});
```

<Callout type="info">
Hidden tools are useful for navigation, analytics, or background operations that shouldn't clutter the chat UI.
</Callout>

---

## Deferred Loading

Mark tools with `deferLoading: true` to exclude them from every request. They are injected automatically only when the user's message semantically matches the tool — reducing token cost for large tool sets.

```typescript
useTool({
  name: "run_sql_query",
  description: "Execute a SQL query against the database",
  deferLoading: true,
  searchKeywords: ["sql", "query", "database", "table"],
  inputSchema: z.object({ query: z.string() }),
  handler: async ({ query }) => db.execute(query),
});
```

Add `searchKeywords` alongside `description` for more accurate relevance matching.

---

## Fallback Renderer

`<CopilotChat>` resolves a renderer for each tool call using this priority chain:

| Priority | Source | Description |
|----------|--------|-------------|
| 1 | `toolRenderers[toolName]` | Per-tool renderer on `<CopilotChat>` |
| 2 | `tool.render` | Render function on the tool definition |
| 3 | `mcpToolRenderer` | Catch-all for MCP tools |
| 4 | `fallbackToolRenderer` | Catch-all for any unmatched tool |
| 5 | Built-in default | Generic execution card |

```tsx
<CopilotChat
  toolRenderers={{
    get_weather: ({ args, result }) => <WeatherCard {...result} />,
  }}
  fallbackToolRenderer={({ toolName, args, result }) => (
    <pre>{JSON.stringify(result, null, 2)}</pre>
  )}
/>
```

---

## AI Response Control

Control how the AI responds after tool execution:

```tsx
handler: async ({ query }) => {
  const results = await search(query);

  return {
    data: results,
    _aiResponseMode: 'brief',      // 'verbose' | 'brief' | 'silent'
    _aiContext: `Found ${results.length} results`,
    _aiContent: 'Here are the results:',
  };
}
```

| Mode | Behavior |
|------|----------|
| `verbose` | AI explains results in detail |
| `brief` | AI gives short summary |
| `silent` | No AI response, just show tool result |

---

## Error Handling

```tsx
handler: async ({ query }) => {
  try {
    const results = await search(query);
    return { success: true, data: results };
  } catch (error) {
    return {
      success: false,
      error: error.message,
    };
  }
}
```

### The `success` flag

The `success` field is read by the AI to decide how to continue reasoning after a tool call. Returning `success: false` tells the AI the tool did not accomplish its goal — it can then retry with different parameters, try an alternative tool, or explain the failure to the user.

```tsx
// ✅ Good — AI understands what went wrong and can adapt
return {
  success: false,
  error: 'No results found for that date range. Try a wider range.',
};

// ❌ Avoid — throwing an exception stops the agentic loop entirely
throw new Error('No results found');
```

Always include a descriptive `error` string alongside `success: false`. The AI uses this message to reason about its next step, so vague errors like `"Unknown error"` reduce its ability to recover gracefully.

---

## Best Practices

1. **Clear descriptions** - AI uses this to decide when to call the tool
2. **Validate with Zod** - Type safety and clear parameter docs
3. **Return structured data** - AI understands JSON better than strings
4. **Handle errors** - Return error info instead of throwing
5. **Use approval for destructive actions** - Delete, purchase, send

---

## Next Steps

- [Backend Tools](/docs/tools/backend-tools) - Server-side tools
- [Generative UI](/docs/generative-ui) - Custom tool renderers
- [Agentic Loop](/docs/tools/agentic-loop) - Multi-step execution

---

## Tools
URL: https://copilot-sdk.yourgpt.ai/docs/tools
Description: Give the AI capabilities in your app

Tools let the AI take actions in your app - from UI interactions to database queries.

---

<Cards>
  <Card title="Built-in Tools" href="/docs/tools/built-in">
    Ready-to-use tools for screenshots, console logs, and more.
  </Card>
  <Card title="Frontend Tools" href="/docs/tools/frontend-tools">
    Client-side tools with access to DOM, state, and UI.
  </Card>
  <Card title="Backend Tools" href="/docs/tools/backend-tools">
    Server-side tools with database and API access.
  </Card>
  <Card title="Agentic Loop" href="/docs/tools/agentic-loop">
    Multi-step AI reasoning with continuous tool calls.
  </Card>
</Cards>

---

## How Tools Work

```
User: "Find products under $50 and add the best one to cart"
  ↓
AI calls: search_products({ maxPrice: 50 })
  ↓
AI calls: add_to_cart({ productId: "best-match" })
  ↓
AI: "I found 12 products and added the top-rated one to your cart."
```

---

## Quick Example

```tsx

function MyTools() {
  useTools({
    search_products: {
      description: 'Search the product catalog',
      parameters: z.object({
        query: z.string(),
        maxPrice: z.number().optional(),
      }),
      handler: async ({ query, maxPrice }) => {
        return await fetchProducts(query, maxPrice);
      },
    },
  });

  return null;
}
```

<Callout type="info">
AI reads the `description` to decide when to use each tool.
</Callout>

---

## Frontend vs Backend

| | Frontend Tools | Backend Tools |
|-|----------------|---------------|
| **Location** | Browser | Server |
| **Access** | DOM, state, UI | Database, APIs, secrets |
| **Use for** | Navigation, modals, UI updates | Data queries, auth, payments |

---

## Next Steps

- [Built-in Tools](/docs/tools/built-in) - Screenshot, console, network
- [Frontend Tools](/docs/tools/frontend-tools) - Build client-side tools
- [Backend Tools](/docs/tools/backend-tools) - Build server-side tools

---

## MCP Integration
URL: https://copilot-sdk.yourgpt.ai/docs/tools/mcp
Description: Connect to MCP servers and use their tools in your app

## Provider-Level Config

The simplest way to add MCP servers — configure them directly on `CopilotProvider`:

```tsx

function App() {
  return (
    <CopilotProvider
      runtimeUrl="/api/chat"
      mcpServers={[
        {
          name: "mcp360",
          transport: "http",
          url: "https://connect.mcp360.ai/v1/mcp360/mcp?token=YOUR_TOKEN",
        },
        {
          name: "github",
          transport: "http",
          url: "https://mcp.github.com",
          headers: { Authorization: `Bearer ${githubToken}` },
        },
      ]}
    >
      <CopilotChat />
    </CopilotProvider>
  );
}
```

All servers connect automatically and tools are registered with the AI.

### MCPServerConfig Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `name` | `string` | Required | Unique identifier for this server |
| `transport` | `"http" \| "sse"` | Required | Transport type |
| `url` | `string` | Required | Server URL |
| `headers` | `Record<string, string>` | `{}` | Custom HTTP headers |
| `timeout` | `number` | `30000` | Request timeout in ms |
| `prefixToolNames` | `boolean` | `true` | Prefix tools with server name |

---

## useMCPTools Hook

For more control, use the hook directly inside `CopilotProvider`:

```tsx
function Chat() {
  const { isConnected, isLoading, toolDefinitions } = useMCPTools({
    name: "mcp360",
    transport: "http",
    url: "https://connect.mcp360.ai/v1/mcp360/mcp?token=YOUR_TOKEN",
  });

  return <CopilotChat />;
}
```

### Hook Return Values

| Property | Type | Description |
|----------|------|-------------|
| `isConnected` | `boolean` | Whether connected to the server |
| `isLoading` | `boolean` | Whether connection is in progress |
| `toolDefinitions` | `ToolDefinition[]` | Available tools |
| `state` | `MCPClientState` | Full connection state including errors |
| `connect` | `() => Promise` | Manually connect |
| `disconnect` | `() => Promise` | Disconnect |
| `callTool` | `(name, args) => Promise` | Call a tool directly |

### Transport Types

<Tabs items={['HTTP (Recommended)', 'SSE']}>
  <Tab value="HTTP (Recommended)">
```tsx
useMCPTools({ name: "server", transport: "http", url: "https://mcp.example.com" });
```
Best for most remote MCP servers.
  </Tab>
  <Tab value="SSE">
```tsx
useMCPTools({ name: "realtime", transport: "sse", url: "https://mcp.example.com/events" });
```
Best for real-time streaming connections.
  </Tab>
</Tabs>

---

## Multiple Servers

Call the hook multiple times — all tools register with the same `CopilotProvider`:

```tsx
function Chat() {
  useMCPTools({ name: "github", transport: "http", url: "https://mcp.github.com", headers: { Authorization: `Bearer ${githubToken}` } });
  useMCPTools({ name: "slack", transport: "http", url: "https://mcp.slack.com", headers: { Authorization: `Bearer ${slackToken}` } });

  return <CopilotChat />;
}
```

<Callout type="info">
With `prefixToolNames: true` (default), tools are namespaced to avoid conflicts: `github_create_issue`, `slack_send_message`.
</Callout>

---

## MCP-UI

[MCP-UI](https://github.com/idosal/mcp-ui) extends MCP to allow tools to return interactive HTML components — product cards, forms, charts — rendered inline in chat.

```tsx
function Chat() {
  useMCPTools({ name: "shop", transport: "http", url: "/api/mcp" });

  const { handleIntent } = useMCPUIIntents({
    onIntent: (action, data) => {
      if (action === "add_to_cart") addToCart(data.productId, data.quantity);
    },
    onPrompt: (text) => setChatInput(text),
    onNotify: (message, level) => toast[level || "info"](message),
  });

  return <CopilotChat onUIIntent={handleIntent} />;
}
```

### Intent Types

| Type | Handler | Description |
|------|---------|-------------|
| `intent` | `onIntent` | Semantic action for your app |
| `prompt` | `onPrompt` | Add text to chat input |
| `notify` | `onNotify` | Show notification |
| `link` | `onLink` | Open a URL |
| `tool` | `onToolCall` | Call another MCP tool |

---

## Error Handling

```tsx
const { state } = useMCPTools({
  name: "server",
  transport: "http",
  url: "https://mcp.example.com",
  onError: (error) => console.error(`MCP Error: ${error.message}`),
});

// state.connectionState: "disconnected" | "connecting" | "connected" | "error"
```

---

## MCP360 Gateway

Access 100+ tools through a single connection with [MCP360](https://mcp360.ai):

```tsx
useMCPTools({
  name: "mcp360",
  transport: "http",
  url: "https://connect.mcp360.ai/v1/mcp360/mcp?token=YOUR_TOKEN",
});
```

<Callout type="info">
MCP360 includes web search, scraping, SEO tools, e-commerce data, and more. [Explore all tools →](https://mcp360.ai)
</Callout>

---

## Angular
URL: https://copilot-sdk.yourgpt.ai/docs/api-reference/frameworks/angular
Description: Angular integration

<div className="not-prose mb-8 p-6 rounded-xl border bg-gradient-to-br from-amber-500/10 to-orange-500/10">
  <div className="flex items-center gap-3">
    <span className="text-3xl">🚧</span>
    <div>
      <h2 className="text-xl font-bold m-0">Coming Soon</h2>
      <p className="text-muted-foreground m-0">Angular integration is under development</p>
    </div>
  </div>
</div>

Angular support for Copilot SDK.

---

## Planned Features

- Angular services and injection tokens
- Angular component library
- RxJS observables integration
- Full TypeScript support

---

## Current Alternative

Use the core package with Angular services:

```ts

// Create your own Angular services using the core utilities
```

---

<Callout type="info">
Join our Discord or GitHub to get notified when Angular support is released.
</Callout>

---

## Vue
URL: https://copilot-sdk.yourgpt.ai/docs/api-reference/frameworks/vue
Description: Vue.js integration

<div className="not-prose mb-8 p-6 rounded-xl border bg-gradient-to-br from-amber-500/10 to-orange-500/10">
  <div className="flex items-center gap-3">
    <span className="text-3xl">🚧</span>
    <div>
      <h2 className="text-xl font-bold m-0">Coming Soon</h2>
      <p className="text-muted-foreground m-0">Vue.js integration is under development</p>
    </div>
  </div>
</div>

Vue.js support for Copilot SDK.

---

## Planned Features

- Vue 3 composables (`useCopilot`, `useTools`, `useAIContext`)
- Vue component library
- Nuxt.js integration
- Full TypeScript support

---

## Current Alternative

Use the core package with Vue's reactivity system:

```ts

// Create your own Vue composables using the core utilities
```

---

<Callout type="info">
Join our Discord or GitHub to get notified when Vue support is released.
</Callout>

---

## Components
URL: https://copilot-sdk.yourgpt.ai/docs/api-reference/react/components
Description: React components and providers

Provider and context components for React.

---

## CopilotProvider

Root provider that enables AI chat functionality. Connect to your backend API that handles LLM configuration.

> **Note:** LLM settings (model, temperature, etc.) are configured on your server using `@yourgpt/llm-sdk`. The frontend only specifies the runtime URL.

```tsx

function App() {
  return (
    <CopilotProvider
      runtimeUrl="/api/chat"
      systemPrompt="You are a helpful assistant."
      threadId="user-123-thread"
      initialMessages={[]}
      onMessagesChange={(messages) => console.log(messages)}
      debug={false}
    >
      {children}
    </CopilotProvider>
  );
}
```

### Props

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `runtimeUrl` | `string` | Yes | Your API endpoint URL |
| `systemPrompt` | `string` | No | System prompt sent with each request (reactive - changes auto-apply) |
| `threadId` | `string` | No | Thread ID for conversation persistence |
| `initialMessages` | `Message[]` | No | Initial messages to populate the chat |
| `onMessagesChange` | `(messages: Message[]) => void` | No | Callback when messages change |
| `onError` | `(error: Error) => void` | No | Callback when an error occurs |
| `parseError` | `(status: number, body: unknown) => string \| null` | No | Extract message from custom server error formats |
| `streaming` | `boolean` | No | Enable/disable streaming (default: true) |
| `debug` | `boolean` | No | Enable debug logging |

### Dynamic System Prompt

The `systemPrompt` prop is **reactive** - changes are automatically applied to the chat. You can also update it programmatically:

```tsx

function MyComponent() {
  const { setSystemPrompt } = useCopilot();

  const switchToSalesMode = () => {
    setSystemPrompt('You are a sales assistant. Help users find products.');
  };

  return <button onClick={switchToSalesMode}>Sales Mode</button>;
}
```

---

## Usage Patterns

### Basic Setup

```tsx
<CopilotProvider runtimeUrl="/api/chat">
  <CopilotChat />
</CopilotProvider>
```

### With Tools

```tsx
<CopilotProvider runtimeUrl="/api/chat">
  <MyTools />
  <CopilotChat />
</CopilotProvider>

function MyTools() {
  useTools({ ... });
  return null;
}
```

### With Context

```tsx
<CopilotProvider runtimeUrl="/api/chat">
  <MyContext />
  <CopilotChat />
</CopilotProvider>

function MyContext() {
  useAIContext({ key: 'app-state', data: state });
  return null;
}
```

### Multiple Threads

```tsx
function ChatApp() {
  const [threadId, setThreadId] = useState('thread-1');

  return (
    <CopilotProvider
      key={threadId}  // Remount on thread change
      runtimeUrl="/api/chat"
      threadId={threadId}
    >
      <ThreadSwitcher onSelect={setThreadId} />
      <CopilotChat />
    </CopilotProvider>
  );
}
```

### Persistence

```tsx
<CopilotProvider
  runtimeUrl="/api/chat"
  threadId="user-123"
  onMessagesChange={(messages) => {
    localStorage.setItem('chat-history', JSON.stringify(messages));
  }}
  initialMessages={JSON.parse(localStorage.getItem('chat-history') || '[]')}
>
  <CopilotChat />
</CopilotProvider>
```

---

## Hooks
URL: https://copilot-sdk.yourgpt.ai/docs/api-reference/react/hooks
Description: React hooks for chat state and tools

Core hooks for building AI chat experiences.

---

## useCopilot

Main hook for chat state and actions.

```tsx

function Chat() {
  const {
    // State
    messages,
    isLoading,
    error,
    status,

    // Actions
    sendMessage,
    stop,
    clearMessages,
    regenerate,

    // Tools
    toolExecutions,
    pendingApprovals,
    approveToolExecution,
    rejectToolExecution,
    registeredTools,
  } = useCopilot();
}
```

### Return Values

| Property | Type | Description |
|----------|------|-------------|
| `messages` | `UIMessage[]` | All chat messages |
| `isLoading` | `boolean` | Whether AI is responding |
| `error` | `Error \| null` | Current error state |
| `status` | `'ready' \| 'streaming' \| 'submitted' \| 'error'` | Current status |
| `sendMessage` | `(content: string, attachments?: Attachment[]) => Promise` | Send a message |
| `stop` | `() => void` | Stop current generation |
| `clearMessages` | `() => void` | Clear all messages |
| `regenerate` | `(messageId?: string) => Promise` | Regenerate response |
| `toolExecutions` | `ToolExecution[]` | All tool executions |
| `pendingApprovals` | `ToolExecution[]` | Tools awaiting approval |
| `approveToolExecution` | `(id: string) => void` | Approve a tool |
| `rejectToolExecution` | `(id: string, reason?: string) => void` | Reject a tool |
| `registeredTools` | `ToolDefinition[]` | All registered tools |
| `setSystemPrompt` | `(prompt: string) => void` | Dynamically update the system prompt |

---

## useTools

Register tools with the AI.

```tsx

function MyTools() {
  useTools({
    search_products: {
      description: 'Search the product catalog',
      parameters: z.object({
        query: z.string().describe('Search query'),
        limit: z.number().optional().default(10),
      }),
      handler: async ({ query, limit }) => {
        const results = await searchAPI(query, limit);
        return { products: results };
      },
    },

    add_to_cart: {
      description: 'Add product to cart',
      parameters: z.object({
        productId: z.string(),
        quantity: z.number().default(1),
      }),
      requiresApproval: true,
      handler: async ({ productId, quantity }) => {
        await cart.add(productId, quantity);
        return { success: true };
      },
    },
  });

  return null;
}
```

### Tool Definition

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `description` | `string` | Yes | What the tool does (AI reads this) |
| `parameters` | `ZodSchema` | Yes | Input validation schema |
| `handler` | `(params) => Promise<any>` | Yes | Async function to execute |
| `requiresApproval` | `boolean` | No | Require user approval |

---

## useAIContext

Share app state with the AI.

```tsx

function ProductPage({ product }) {
  useAIContext({
    key: 'current-product',
    data: {
      name: product.name,
      price: product.price,
      stock: product.stock,
    },
    description: 'The product the user is currently viewing',
  });

  return <ProductDetails product={product} />;
}
```

### Options

| Property | Type | Required | Description |
|----------|------|----------|-------------|
| `key` | `string` | Yes | Unique identifier |
| `data` | `object` | Yes | Data to share with AI |
| `description` | `string` | No | Describe the context for AI |
| `parentId` | `string` | No | Parent context for nesting |

---

## useAIContexts

Register multiple contexts at once.

```tsx

function Dashboard() {
  useAIContexts([
    { key: 'user', data: user, description: 'Current user info' },
    { key: 'cart', data: cart, description: 'Shopping cart contents' },
    { key: 'settings', data: settings, description: 'User preferences' },
  ]);
}
```

---

## React
URL: https://copilot-sdk.yourgpt.ai/docs/api-reference/react
Description: React hooks, provider, and components

Full React integration with hooks and components.

```bash
npm install @yourgpt/copilot-sdk/react
```

---

<Cards>
  <Card title="Hooks" href="/docs/api-reference/react/hooks">
    useCopilot, useTools, useAIContext
  </Card>
  <Card title="Components" href="/docs/api-reference/react/components">
    CopilotProvider and context components
  </Card>
</Cards>

---

## Quick Start

```tsx

function App() {
  return (
    <CopilotProvider runtimeUrl="/api/chat">
      <MyTools />
      <CopilotChat />
    </CopilotProvider>
  );
}

function MyTools() {
  useTools({
    search: {
      description: 'Search products',
      parameters: z.object({ query: z.string() }),
      handler: async ({ query }) => searchProducts(query),
    },
  });
  return null;
}
```

---

## Console Logs
URL: https://copilot-sdk.yourgpt.ai/docs/tools/built-in/console
Description: Give AI access to console output for debugging

Let the AI read browser console logs to help debug issues.

---

## Overview

When users report errors, AI can read the console to understand what went wrong:

```
User: "My app keeps crashing"
AI: [Requests console access]
User: [Approves]
AI: "I see a TypeError in your console: 'Cannot read property 'map'
     of undefined' at ProductList.js:42. This means..."
```

---

## Setup

```tsx

function ConsoleLogTool() {
  useTools({
    capture_console: builtinTools.capture_console,
  });

  return null;
}
```

---

## What Gets Captured

| Type | Captured | Example |
|------|----------|---------|
| `console.log()` | Yes | Debug messages |
| `console.warn()` | Yes | Warnings |
| `console.error()` | Yes | Errors with stack traces |
| `console.info()` | Yes | Info messages |
| `console.debug()` | Yes | Debug output |

<Callout type="info">
Only logs from the current browser session are captured. Historical browser logs are not accessible.
</Callout>

---

## Privacy & Consent

Console logs may contain sensitive data. The tool:

- **Always requires user approval** before capturing
- **Only captures current session** logs
- **Does not persist** logs anywhere
- **Lets users review** what's being shared

```tsx
// The tool automatically prompts for consent
useTools({
  capture_console: {
    ...builtinTools.capture_console,
    requiresApproval: true,  // Default - always ask
  },
});
```

---

## How It Works

1. Tool intercepts `console.*` calls when activated
2. Stores recent logs in memory (limited buffer)
3. When AI requests logs, user sees approval prompt
4. On approval, logs are sent to AI for analysis
5. AI can identify errors, warnings, and patterns

---

## Use Cases

### Bug Reports

```
User: "Something's not working right"
AI: "Let me check the console for any errors..."
    [Requests console access]
    [User approves]
AI: "I found the issue! There's a CORS error when fetching
     from api.example.com. Your server needs to add the
     Access-Control-Allow-Origin header."
```

### Performance Issues

```
User: "The app feels slow"
AI: "I'll check for any warnings or performance issues..."
    [Analyzes console]
AI: "I see repeated 'Warning: Each child in a list should
     have a unique key prop' messages. This is causing
     unnecessary re-renders. Let me explain how to fix it..."
```

### Understanding Errors

```
User: "I'm getting a weird error"
AI: [Reads console]
AI: "The error 'ReferenceError: userData is not defined'
     at line 156 means the userData variable doesn't exist
     when the function runs. This usually happens when..."
```

---

## Configuration

### Limit Log Count

```tsx
useTools({
  capture_console: {
    ...builtinTools.capture_console,
    maxLogs: 50,  // Keep last 50 logs
  },
});
```

### Filter Log Types

```tsx
useTools({
  capture_console: {
    ...builtinTools.capture_console,
    logTypes: ['error', 'warn'],  // Only errors and warnings
  },
});
```

---

## Custom Implementation

Build your own console capture:

```tsx
useTools({
  get_console_logs: {
    description: 'Get recent console logs for debugging',
    parameters: z.object({
      types: z.array(z.enum(['log', 'warn', 'error'])).optional(),
      limit: z.number().optional(),
    }),
    requiresApproval: true,
    handler: async ({ types = ['error', 'warn'], limit = 20 }) => {
      // Your console capture implementation
      const logs = getStoredConsoleLogs()
        .filter(log => types.includes(log.type))
        .slice(-limit);

      return {
        success: true,
        data: {
          logs,
          count: logs.length,
        },
        _aiContext: `Captured ${logs.length} console ${types.join('/')} entries`,
      };
    },
  },
});
```

---

## Best Practices

1. **Always require approval** - Console may contain sensitive data
2. **Limit buffer size** - Don't store unlimited logs
3. **Filter by type** - Often only errors/warnings matter
4. **Clear after use** - Don't persist logs unnecessarily
5. **Inform users** - Explain what will be shared

---

## Example: Debug Helper

```tsx
function DebugTools() {
  useTools({
    capture_console: {
      ...builtinTools.capture_console,
      maxLogs: 30,
      requiresApproval: true,
    },

    // Companion tool for more context
    get_error_context: {
      description: 'Get additional context about recent errors',
      parameters: z.object({}),
      requiresApproval: true,
      handler: async () => {
        return {
          success: true,
          data: {
            url: window.location.href,
            userAgent: navigator.userAgent,
            timestamp: new Date().toISOString(),
            localStorage: Object.keys(localStorage).length + ' items',
          },
        };
      },
    },
  });

  return null;
}
```

---

## Next Steps

- [Screenshot Tool](/docs/tools/built-in/screenshot) - Capture visual context
- [Tool Approval](/docs/tools/frontend-tools) - Approval flow details
- [Custom Tools](/docs/tools/frontend-tools) - Build more debugging tools

---

## Built-in Tools
URL: https://copilot-sdk.yourgpt.ai/docs/tools/built-in
Description: Ready-to-use tools for common AI capabilities

Pre-built tools that give AI access to browser context for debugging and assistance.

---

<Cards>
  <Card title="Web Search" href="/docs/tools/built-in/web-search">
    Real-time web search with multi-provider support.
  </Card>
  <Card title="Screenshot" href="/docs/tools/built-in/screenshot">
    Capture and analyze the current page visually.
  </Card>
  <Card title="Console Logs" href="/docs/tools/built-in/console">
    Read browser console for debugging.
  </Card>
</Cards>

---

## Quick Setup

```tsx

function BuiltInTools() {
  useTools({
    capture_screenshot: builtinTools.capture_screenshot,
    capture_console: builtinTools.capture_console,
  });

  return null;
}
```

---

## Available Tools

| Tool | Description |
|------|-------------|
| `web_search` | Search the web for real-time information (server-side) |
| `capture_screenshot` | Takes screenshot of current page for visual analysis |
| `capture_console` | Captures recent console logs for debugging |

---

## Privacy

All built-in tools require user approval before capturing data. Users see exactly what will be shared with the AI.

---

## Screenshot
URL: https://copilot-sdk.yourgpt.ai/docs/tools/built-in/screenshot
Description: Capture viewport for visual context

Capture the current viewport so the AI can see what the user sees.

---

## Setup

```tsx

function ScreenshotTool() {
  useTools({
    capture_screenshot: builtinTools.capture_screenshot,
  });

  return null;
}
```

---

## How It Works

When AI calls `capture_screenshot`:

1. User sees consent prompt
2. On approval, viewport is captured as image
3. Image sent to AI as base64
4. AI can analyze the visual content

<Callout type="info">
Screenshots always require user consent for privacy.
</Callout>

---

## Use Cases

- **Bug reports**: "I'm seeing an error" → AI sees the actual error
- **UI help**: "How do I use this?" → AI sees the current screen
- **Accessibility**: AI can describe visual elements

---

## Example Conversation

```
User: "There's an error on screen, help me fix it"

AI: [Requests screenshot permission]

User: [Approves]

AI: "I can see a TypeError in the console overlay.
     The issue is that `user.name` is undefined.
     Try adding a null check: user?.name"
```

---

## Configuration

```tsx
useTools({
  capture_screenshot: {
    ...builtinTools.capture_screenshot,
    requiresApproval: true, // Always ask (default)
  },
});
```

---

## Web Search
URL: https://copilot-sdk.yourgpt.ai/docs/tools/built-in/web-search
Description: Real-time web search capabilities for your AI copilot

Add real-time web search capabilities to your AI copilot. Search the web for current information, news, and facts.

---

## Enable Web Search

Web search is a built-in tool that works with native providers (OpenAI, Google, Anthropic) using your existing API key.

```tsx

const webSearch = openaiSearch({
  apiKey: process.env.OPENAI_API_KEY,
  maxResults: 5,
});

function App() {
  return (
    <CopilotProvider
      runtimeUrl="/api/chat"
      tools={[webSearch]}
    >
      <CopilotChat />
    </CopilotProvider>
  );
}
```

<Callout type="info">
**No extra API key needed!** Native providers use your existing OpenAI, Google, or Anthropic API key.
</Callout>

---

## Native Providers

No third-party API key required - uses your existing LLM API key.

<Tabs items={['OpenAI', 'Google', 'Anthropic']}>
  <Tab value="OpenAI">
```ts

const webSearch = openaiSearch({
  apiKey: process.env.OPENAI_API_KEY,
  maxResults: 5,
  includeDomains: ['docs.github.com', 'stackoverflow.com'],
});
```
  </Tab>
  <Tab value="Google">
```ts

const webSearch = googleSearch({
  apiKey: process.env.GOOGLE_API_KEY,
  maxResults: 5,
});
```
  </Tab>
  <Tab value="Anthropic">
```ts

const webSearch = anthropicSearch({
  apiKey: process.env.ANTHROPIC_API_KEY,
  maxResults: 5,
});
```
  </Tab>
</Tabs>

---

## Third-Party Providers

### MCP360 Gateway

[MCP360](https://mcp360.ai) provides web search through MCP along with 100+ other tools:

```tsx
function Chat() {
  useMCPTools({
    name: "mcp360",
    transport: "http",
    url: "https://connect.mcp360.ai/v1/mcp360/mcp?token=YOUR_TOKEN",
  });

  return <CopilotChat />;
}
```

<Callout type="info">
**More than just search** — MCP360 includes [Google Search](https://mcp360.ai/mcps/google-search), [Web Scraping](https://mcp360.ai/mcps/web-scraping), SEO tools, e-commerce data, and 100+ other tools through a single connection. [Explore all tools →](https://mcp360.ai)
</Callout>

### Other Providers

<Accordions>
  <Accordion title="Tavily">
```ts

const webSearch = tavilySearch({
  apiKey: process.env.TAVILY_API_KEY,
  includeAnswer: true,
  maxResults: 5,
  searchDepth: 'basic',
});
```
Get API key: [tavily.com](https://tavily.com)
  </Accordion>
  <Accordion title="Serper">
```ts

const webSearch = serperSearch({
  apiKey: process.env.SERPER_API_KEY,
  country: 'us',
  language: 'en',
  maxResults: 5,
});
```
Get API key: [serper.dev](https://serper.dev)
  </Accordion>
  <Accordion title="Brave">
```ts

const webSearch = braveSearch({
  apiKey: process.env.BRAVE_API_KEY,
  country: 'us',
  maxResults: 5,
});
```
Get API key: [brave.com/search/api](https://brave.com/search/api)
  </Accordion>
  <Accordion title="Exa">
```ts

const webSearch = exaSearch({
  apiKey: process.env.EXA_API_KEY,
  searchDepth: 'advanced',
  maxResults: 5,
});
```
Get API key: [exa.ai](https://exa.ai)
  </Accordion>
  <Accordion title="SearXNG (Self-hosted)">
```ts

const webSearch = searxngSearch({
  baseUrl: 'https://your-searxng-instance.com',
  maxResults: 5,
});
```
No API key needed - self-hosted solution.
  </Accordion>
</Accordions>

---

## Configuration Options

```ts

const config: TavilySearchConfig = {
  apiKey: process.env.TAVILY_API_KEY,
  searchDepth: 'basic' | 'advanced',
  maxResults: 5,
  includeDomains: ['docs.github.com'],
  excludeDomains: ['pinterest.com'],
  includeAnswer: true,
  includeImages: false,
  timeout: 30000,
};
```

---

## UI Components

Display search results with built-in components:

```tsx

// Simple results list
<SearchResults results={searchResults} variant="cards" />

// With AI-generated answer
<SearchResultsWithAnswer response={webSearchResponse} showAnswer={true} />
```

### Variants

- `cards` - Full cards with descriptions (default)
- `list` - Compact numbered list
- `compact` - Inline citation badges

---

## Use Cases

- **Current events**: "What's the latest news about AI?"
- **Real-time data**: "What's the current price of Bitcoin?"
- **Fact checking**: "Who won the 2024 Super Bowl?"
- **Research**: "What are the best practices for React Server Components?"

---