# Get Started

Create an agent, deploy it, and add it to your Next.js app.

## 21st-sdk skill (IMPORTANT, ADD IT IF SUCH SKILL IS NOT CONFIGURED YET)

```md
---
name: 21st-sdk
description: Use for any interaction with @21st-sdk packages or 21st Agents. If the task involves files in ./agents/, it most likely refers to 21st SDK.
---

# 21st SDK / 21st Agents

1. For any @21st-sdk or 21st Agents task, fetch `https://21st-search-engine.fly.dev/help` first.
2. This server is the source of truth for searching the 21st SDK documentation, source code, and examples.
3. Treat `/help` as the primary entry point for understanding how the server works and how to use it.
```

## 1.Create your agent

```bash
pnpm add @21st-sdk/agent @21st-sdk/nextjs @21st-sdk/react @21st-sdk/node @ai-sdk/react ai zod
```

Create `agents/my-agent/index.ts`:

agents/my-agent/index.ts
```typescript
import { agent, tool } from "@21st-sdk/agent"
import { z } from "zod"

export default agent({
  model: "claude-sonnet-4-6",
  systemPrompt: "You are a helpful coding assistant.",
  tools: {
    add: tool({
      description: "Add two numbers",
      inputSchema: z.object({ a: z.number(), b: z.number() }),
      execute: async ({ a, b }) => ({
        content: [{ type: "text", text: `${a + b}` }],
      }),
    }),
  },
})
```

See [Project Setup](/agents/docs/md/build/agents) for all configuration options, entry points, and project structure.

## 2.Deploy

Log in with your [API key](/agents/app) from the dashboard, then deploy:

```
npx @21st-sdk/cli login
npx @21st-sdk/cli deploy
```

Your agent is now live. Next, integrate it into your app.

## 3.Create a token route

The SDK exchanges your secret API key for short-lived tokens server-side, so credentials are never exposed to the browser. Get your API key from the [dashboard](/agents/playground).

app/api/an-token/route.ts
```typescript
import { createTokenHandler } from "@21st-sdk/nextjs/server"

export const POST = createTokenHandler({
  apiKey: process.env.API_KEY_21ST!,
})
```

## 4.Add the chat component

Use `createAgentChat` to connect to your agent and `<AgentChat>` to render the UI. It handles streaming, tools, and theming automatically.

app/page.tsx
```tsx
"use client"

import { AgentChat, createAgentChat } from "@21st-sdk/nextjs"
import { useChat } from "@ai-sdk/react"

const sandboxId = "sb_abc123" // Returned by your server

const chat = createAgentChat({
  agent: "my-agent",
  tokenUrl: "/api/an-token",
  sandboxId,
  // Optional: continue a specific thread inside this sandbox
  // threadId: "uuid-of-existing-thread",
})

export default function Page() {
  const { messages, input, handleInputChange, handleSubmit, status, stop, error } =
    useChat({ chat })

  return (
    <AgentChat
      messages={messages}
      onSend={() => handleSubmit()}
      status={status}
      onStop={stop}
      error={error ?? undefined}
    />
  )
}
```

## Optional: per-message runtime options

Pass `options` inside the AI SDK request body when one browser request should run with different runtime settings without changing the deployed agent config.

app/page.tsx
```tsx
"use client"

import { AgentChat, createAgentChat } from "@21st-sdk/nextjs"
import { useChat } from "@ai-sdk/react"

const sandboxId = "sb_abc123" // Returned by your server

const chat = createAgentChat({
  agent: "my-agent",
  tokenUrl: "/api/an-token",
  sandboxId,
})

const reviewOptions = {
  systemPrompt: {
    type: "preset",
    preset: "claude_code",
    append:
      "You are reviewing a checkout diff. Focus on regressions, risky edge cases, and missing tests. Do not edit files.",
  },
  maxTurns: 4,
  maxBudgetUsd: 0.2,
  disallowedTools: ["Bash"],
}

export default function Page() {
  const { messages, sendMessage, status, stop, error } = useChat({ chat })

  return (
    <AgentChat
      messages={messages}
      onSend={(message) =>
        sendMessage(
          {
            role: "user",
            parts: [{ type: "text", text: message.content }],
          },
          {
            body: { options: reviewOptions },
          },
        )
      }
      status={status}
      onStop={stop}
      error={error ?? undefined}
    />
  )
}
```

Currently applied by the runtime: `systemPrompt`, `maxTurns`, `maxBudgetUsd`, and `disallowedTools`.

## Server-side SDK

Use `@21st-sdk/node` for server-side sandbox and thread management - creating sandboxes, listing threads, and generating tokens.

server.ts
```typescript
import { AgentClient } from "@21st-sdk/node"

const client = new AgentClient({ apiKey: process.env.API_KEY_21ST! })

// Create a sandbox for an agent
const sandbox = await client.sandboxes.create({ agent: "my-agent" })

// Create a thread in the sandbox
const thread = await client.threads.create({
  sandboxId: sandbox.id,
  name: "Chat 1",
})

// Create a short-lived token for client-side use
const token = await client.tokens.create({ agent: "my-agent" })
```

## Templates

- [Next.js Starter](/agents/docs/md/templates/chat-app) - Next.js chat interface with AI agent powered by 21st Agents SDK
- [Python Starter](/agents/docs/md/templates/python-terminal-chat) - Minimal server-side Python chat client using the 21st SDK
- [Go Starter](/agents/docs/md/templates/golang-terminal-chat) - Minimal terminal chat client in Go using the 21st SDK
- [Explain GitHub repos with Nia](/agents/docs/md/templates/nia-chat) - Next.js repository chat with Nia MCP-backed GitHub analysis
- [AgentMail Agent](/agents/docs/md/templates/email-agent) - Email operations copilot — send, read inbox, auto-reply via AgentMail
- [Note Taker with Convex](/agents/docs/md/templates/note-taker) - AI notebook assistant with persistent notes and real-time sync via Convex
- [Slack Monitor Agent](/agents/docs/md/templates/monitor-agent) - Track service status and send updates directly to Slack
- [BrowserUse Agent](/agents/docs/md/templates/web-scraper) - Extract structured data from any website using Browser Use Cloud
- [Lead Research Agent](/agents/docs/md/templates/lead-research-agent) - Research people by email online, qualify leads, and send Slack alerts for interesting prospects
- [Form Autocomplete](/agents/docs/md/templates/fill-form) - AI-powered form filling with tabbed forms and chat interface
- [Docs Assistant (llms.txt)](/agents/docs/md/templates/docs-assistant) - Documentation Q&A agent — provide a docs URL and get an instant assistant that searches via llms.txt
- [Support Agent](/agents/docs/md/templates/support-agent) - Docs-powered support agent that answers questions from llms.txt and escalates unanswered ones via email (Resend)

## What's next

[AgentsCustom tools, lifecycle hooks, and full configuration.](/agents/docs/md/build/agents)[DeployProject structure, CLI commands, and deploy internals.](/agents/docs/md/deploy/deploy)