Get Started

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

1.Create your agent

$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

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 for all configuration options, entry points, and project structure.

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

app/api/an-token/route.ts

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

"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

"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

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" })