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 src/agent.ts:

src/agent.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 Build & Deploy 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 { createAnTokenHandler } from "@21st-sdk/nextjs/server"

export const POST = createAnTokenHandler({
  apiKey: process.env.AN_API_KEY!,
})

4.Add the chat component

Use createAnChat to connect to your agent and <AnAgentChat> to render the UI. It handles streaming, tools, and theming automatically.

app/page.tsx

"use client"

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

const chat = createAnChat({
  agent: "my-agent",
  tokenUrl: "/api/an-token",
  // Optional: continue in an existing sandbox/thread
  // sandboxId: "uuid-of-existing-sandbox",
  // threadId: "uuid-of-existing-thread",
})

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

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

Server-side SDK

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

server.ts

import { AnClient } from "@21st-sdk/node"

const an = new AnClient({ apiKey: process.env.AN_API_KEY! })

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

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

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

Templates

Chat App

Next.js chat interface with AI agent powered by 21st Agents SDK

Email Agent

Email operations copilot — send, read inbox, auto-reply via AgentMail

Note Taker

AI notebook assistant with persistent notes and real-time sync via Convex

Monitor Agent

Service health monitoring with Slack alerts

Web Scraper

Extract structured data from any website using Browser Use Cloud

Fill Form

AI-powered form filling with tabbed forms and chat interface