Agents

Define your agent, configure its runtime, model, tools, and permissions, then deploy with the CLI.

Project structure

Every 21st agent lives inside an agents/<slug>/ directory with an entrypoint file and an optional template/ folder for sandbox files.

file tree

my-project/
├── package.json
├── agents/
│   └── my-agent/
│       ├── index.ts          # or index.js
│       └── template/
│           └── ...

package.json

{
  "name": "my-agent",
  "type": "module",
  "dependencies": {
    "@21st-sdk/agent": "latest",
    "zod": "^3.24"
  }
}

Build environment

The CLI bundles your agent before deploying. The target environment is Linux amd64.

esbuild options

platform: "node"
target: "node22"

Minimal agent

The smallest working agent needs a model and a system prompt.

agents/my-agent/index.ts

import { agent } from "@21st-sdk/agent"

export default agent({
  model: "claude-sonnet-4-6",
  systemPrompt: "You are a helpful assistant.",
})

Full agent with tools

Add custom tools, set permission mode, and configure max turns.

agents/my-agent/index.ts

import { agent, tool } from "@21st-sdk/agent"
import { z } from "zod"

const getWeather = tool({
  name: "get_weather",
  description: "Get the current weather for a city",
  parameters: z.object({
    city: z.string().describe("City name"),
  }),
  execute: async ({ city }) => {
    return { temperature: 22, condition: "sunny", city }
  },
})

export default agent({
  model: "claude-sonnet-4-6",
  runtime: "claude_code",
  systemPrompt: `You are a helpful weather assistant.
Use the get_weather tool when asked about weather.`,
  tools: [getWeather],
  permissionMode: "bypass",
  maxTurns: 50,
})

Runtime & Model

The runtime determines which AI provider executes your agent. Each runtime supports a different set of models with varying capabilities and price points.

Anthropic

Claude Code

Full-featured agentic runtime with tool use, web access, and sandboxed execution. Best for complex multi-step tasks.

Claude Sonnet 4.6Claude Opus 4.6Claude Haiku 4.5

Soon

OpenAI

Codex

OpenAI's optimized runtime with multiple reasoning levels. Great for structured tasks and analysis.

GPT-5.2 CodexGPT-5.2 Codex (High)GPT-5.1 Codex Mini

Model switching - you can let end users switch between models at runtime. Enable “Allow model switching” in the agent config and select which models to expose.

System Prompt

The system prompt defines your agent's persona, behavioral rules, and constraints. It's sent with every message and shapes how the agent responds to users.

See the System Prompts page for writing tips, examples, and how to reference skills.

Tools

Tools are the capabilities your agent can use during a conversation. Toggle each tool on or off depending on what your agent needs to do.

Category	Tools	Description
Read-only	`ReadGlobGrep`	Search and read files without modifications.
Edit	`EditWrite`	Create and modify files in the sandbox.
Execution	`Bash`	Run shell commands in the sandboxed environment.
Web	`WebFetchWebSearch`	Fetch URLs and search the web for information.

Only enable the tools your agent actually needs. You can also guide tool usage through the system prompt.

Permission Modes

Permissions control whether the agent can perform certain actions automatically or needs the user to confirm first.

Mode	Behavior
`Default`	Ask the user before risky actions like file writes or shell commands.
`Accept Edits`	Auto-approve file edits, but confirm shell commands.
`Bypass All`	No confirmation needed. The agent acts autonomously.

Tip: For agents embedded in your product where the sandbox is fully isolated, use Bypass All to remove friction.

Max Turns

Max turns limits how many reasoning steps the agent can take per message. Each step is one tool call or response generation. Range: 1-500.

10 · Minimal25 · Low50 · Default100 · High200 · Extended500 · Max

Start with the default (50) and adjust based on what you see in Logs.

Attachments

Allow users to upload files alongside their messages. The agent receives the file content and can reference it during the conversation.

Setting	Description
Allow File Attachments	Master toggle for file uploads
Allowed File Types	Images (.jpg, .png, .gif, .webp), Documents (.pdf, .doc, .txt), Code (.ts, .js, .py, .json, .md), or All
Custom Extensions	Additional file extensions (e.g. .csv, .xlsx, .sql)
Attach Button Icon	Visual style of the upload button - plus circle or paperclip

Skills

Skills are blocks of instructions and context that you attach to an agent. Unlike the system prompt which is sent every turn, skills act as reference material the agent draws on when a specific topic comes up.

Attach skills in the agent config, then reference them by name in the system prompt. See the Skills page for details.

What's next

System Prompts

Write effective prompts, use variables, and reference skills.

Deploy

Project structure, CLI commands, and deploy internals.