Core Concepts

How it works

When a user sends a message, your app calls the Chat API. The platform routes the message to a Relay runtime that provisions an E2B sandbox, starts the runtime processes inside it, runs the agent with the tools and instructions you configured, and streams the response back via SSE.

Your App
  └─ AgentChat component (or raw SDK)
        │
        ▼  SSE streaming
    Relay
        │
        ├─ E2B sandbox
        ├─ Agent runtime (Claude Code / Codex)
        ├─ User tools + MCP servers
        ├─ System prompt + skills
        └─ Isolated agent process

Everything in between — auth, routing, sandboxing, token counting, cost tracking — is handled by the platform.

Agents

An agent is a configuration that defines what the AI can do and how it behaves. Agents are code-first — you define them in code (model, system prompt, tools, lifecycle hooks) and deploy with @21st-sdk/cli deploy. This creates an E2B sandbox. Inside it, your tools and MCP servers now run in the sandbox runtime instead of a separate remote worker, while the agent itself executes in an isolated layer. Once deployed, you integrate it into your app with the React SDK.

Skills

A skill is a block of additional instructions and context that you can attach to any agent. Unlike the system prompt which is sent every turn, skills act as reference material the agent can draw on when needed.

For example, you might create a “Returns Policy” skill with detailed procedures and attach it to your support agent. In the system prompt you tell the agent: “When the user asks about returns, follow the Returns Policy skill.” The agent then has access to the full context without bloating every single message.

See the Skills page for details.

Sandboxes & Threads

When a user starts chatting with your agent, the platform creates a sandbox — a persistent E2B environment with its own filesystem, git state, and sessions. The sandbox ties together the agent config, the runtime processes, and the execution environment.

The sandbox now hosts your tool and MCP processes directly, but the agent process itself is isolated from that runtime layer. In practice, that means dashboard env vars can be available to tools without becoming ordinary env vars inside the agent process.

Each conversation within a sandbox is a thread. A sandbox can contain multiple threads, and each thread tracks:

Sandboxes persist across page refreshes. To start a fresh conversation in the same environment, create a new thread. To start from scratch, create a new sandbox. You can inspect every thread in the Logs page.

Relay

Relay is the runtime service sitting between your app and the agent. It takes care of:

1. Authenticating the request and resolving the agent config
2. Provisioning the E2B sandbox and starting the runtime processes inside it
3. Starting user tools and MCP servers for that sandbox
4. Running the agent with the configured runtime in an isolated execution layer
5. Streaming the response back to your app via Server-Sent Events
6. 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.

API Keys

API keys authenticate your app's requests to 21st Agents. You create them in the dashboard under the API tab.

Never expose your API key in client-side code. The Get Started guide shows how to set up the token exchange route.