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 { 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 chat = createAgentChat({
  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 (
    <AgentChat
      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 { 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

Chat App

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

Python Terminal Chat

Minimal server-side Python chat client using the 21st 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