Core Concepts
The primitives that make up the 21st Agents platform and how they fit together.
Primitives at a glance
| Primitive | What it is | Defined in |
|---|---|---|
| Agent | A code-first config defining what the AI can do | Your code |
| Tool | A capability the agent can invoke (built-in or custom) | Your code + runtime |
| Skill | Reference knowledge the agent can draw on when needed | Dashboard |
| System Prompt | Instructions sent with every message defining agent behavior | Your code / per-request |
| Sandbox | An isolated E2B environment with its own filesystem and runtime | Platform (auto-provisioned) |
| Thread | A single conversation within a sandbox | Platform (auto-created or explicit) |
| Relay | The runtime service that connects your app to the agent | Platform (managed) |
| API Key | Team-scoped credential for authenticating requests | Dashboard |
How it works
When a user sends a message, your app calls the Chat API. The platform routes the message to the Relay, which provisions an E2B sandbox, starts the runtime, runs the agent with your tools and instructions, and streams the response back via SSE.
Your App
└─ AgentChat component (or raw SDK)
│
▼ SSE streaming (11 event types)
Relay (auth, routing, cost tracking)
│
▼
E2B Sandbox
├─ Agent runtime (Claude Code / Codex)
│ ├─ System prompt + skills
│ ├─ Built-in tools (Bash, Read, Write, Glob, Grep, WebSearch...)
│ └─ Custom tools (your Zod-schema functions)
├─ MCP servers
├─ Isolated filesystem
└─ Thread(s) → messages, tokens, costEverything in between — auth, sandboxing, token counting, cost tracking, session persistence — is handled by the platform.
Agent
A configuration that defines what the AI can do and how it behaves. Agents are code-first — you define them in TypeScript (model, system prompt, tools, permissions) and deploy with @21st-sdk/cli deploy. The agent config lives in agents/<slug>/index.ts.
An agent contains: a model, a runtime, a system prompt, tools, permission settings, cost controls (maxTurns, maxBudgetUsd), and optional lifecycle hooks.
Tools
A capability the agent can invoke to interact with the world. Tools come in three flavors:
Built-in tools
Bash, Read, Write, Edit, Glob, Grep, WebSearch, WebFetch - enabled by default with the Claude Code runtime
Custom tools
Your own functions defined with Zod schemas in the agent config - run inside the sandbox
MCP servers
External integrations (databases, APIs, GitHub, Slack) connected via the Model Context Protocol
The agent decides which tools to call based on the user's message and its system prompt. Tool calls are streamed in real time (tool-input-start, tool-output-available). See Tools and MCPs for setup.
Skills
Reference knowledge the agent can draw on when needed. Unlike the system prompt (sent every turn), skills act as on-demand context - the agent loads them when relevant.
For example, a “Returns Policy” skill with detailed procedures can be attached to a support agent. In the system prompt you say: “When the user asks about returns, follow the Returns Policy skill.” The agent gets full context without bloating every message.
See the Skills page for details.
Sandbox
An isolated E2B environment with its own filesystem, git state, and runtime processes. The sandbox ties together the agent config, the execution environment, and your tools. Each sandbox is a dedicated microVM with full network access.
Tools and MCP servers run inside the sandbox alongside the agent, but the agent process itself is isolated from that runtime layer. Dashboard env vars are available to tools without becoming ordinary env vars inside the agent process.
Sandboxes persist across page refreshes and messages. To start from scratch, create a new sandbox. For hardware specs, timeouts, and file sharing, see the Sandboxes FAQ.
Thread
A single conversation within a sandbox. A sandbox can contain multiple threads. Each thread tracks:
Messages
User input, assistant response, and tool calls
Status
streaming, completed, error, or cancelled
Token usage
Input tokens, output tokens, and total
Cost & duration
USD cost and execution time in milliseconds
If you keep one thread per sandbox, you can omit threadId on chat requests and the relay will resume the latest thread. To start a fresh conversation in the same environment, create a new thread. For message storage and history, see the Messages & History FAQ.
Relay
The managed runtime service sitting between your app and the agent. It takes care of:
- Authenticating the request and resolving the agent config
- Provisioning the E2B sandbox and starting the runtime processes
- Starting user tools and MCP servers
- Running the agent in an isolated execution layer
- Streaming the response back via Server-Sent Events
- Persisting session state so the agent can resume across turns
You don't interact with Relay directly — the SDK handles it. But understanding that it exists helps when debugging latency or connection issues.
Streaming
Every chat response is delivered as a Server-Sent Events (SSE) stream, compatible with the Vercel AI SDK. The stream emits 11 event types that let you render text tokens, tool calls, and metadata in real time.
| Event | Description |
|---|---|
| start | First event in every stream |
| text-start | Start of a text content block |
| text-delta | Streaming text token |
| text-end | End of text content block |
| tool-input-start | Agent begins calling a tool (includes tool name) |
| tool-input-delta | Streaming tool input JSON |
| tool-input-available | Complete tool call input (parsed JSON) |
| tool-output-available | Tool execution result |
| message-metadata | Session ID, cost (USD), tokens, duration |
| finish | Stream completed successfully |
| error | Error occurred during streaming |
Typical flow: start → text blocks → tool call cycle (input start → input deltas → input available → output available) → more text blocks → message-metadata → finish. Tool call cycles repeat as the agent uses tools. See the Chat API reference for the full SSE payload format, stream resumption, and cancellation.
API Keys
Team-scoped credentials that authenticate your app's requests. You create them in the dashboard under the API tab.
Format: an_sk_ followed by 64 hex characters
Scope: Each key is scoped to a team
Auth flow: Your backend exchanges the API key for a short-lived JWT token via /api/an/token, then passes the token to the client
Never expose your API key in client-side code. The Get Started guide shows how to set up the token exchange route.