Documentation/docs/managed-agents/agents

#Agents

An agent is the versioned definition of what should run: model, system prompt, tool policy, MCP servers, and skills.

Official reference: Claude Managed Agents agent setup.

What Goes In An Agent#

FieldPurpose
nameHuman-readable agent name
modelModel id and optional speed
systemStable instruction text
toolsBuilt-in, MCP, and custom tool definitions
mcp_serversURL MCP servers available through mcp_toolset
skillsUploaded skill versions attached to the agent
metadataApplication metadata

Sandbox0 stores agent versions. Updating an agent creates a new version; sessions keep the agent snapshot they were created with.

Create An Agent#

typescript
const agent = await client.beta.agents.create({
    name: "Coding Assistant",
    model: { id: "claude-sonnet-4-20250514", speed: "standard" },
    system: "Make small, reviewed code changes.",
    tools: [{
        type: "agent_toolset_20260401",
        default_config: {
            enabled: true,
            permission_policy: { type: "always_ask" },
        },
        configs: [
            {
                name: "bash",
                enabled: true,
                permission_policy: { type: "always_allow" },
            },
            { name: "web_search", enabled: false },
        ],
    }],
});

Tool Types#

Tool typeStatus in Sandbox0
agent_toolset_20260401Supported through the selected agent engine
mcp_toolsetSupported for URL MCP servers
customSupported through agent.custom_tool_use and user.custom_tool_result events

Built-in tool names include bash, edit, read, write, glob, grep, web_fetch, and web_search.

MCP Servers#

typescript
const agent = await client.beta.agents.create({
    name: "Docs Agent",
    model: "claude-sonnet-4-20250514",
    mcp_servers: [{
        type: "url",
        name: "docs",
        url: "https://mcp.example.com/sse",
    }],
    tools: [{
        type: "mcp_toolset",
        mcp_server_name: "docs",
    }],
});

If the MCP server needs credentials, attach a vault to the session. The agent declares the server and toolset; the session decides which vaults are available.

Sandbox0 Notes#

  • Reserved sandbox0.managed_agents.* metadata keys are not accepted on agents.
  • The agent model defaults to the Claude engine unless a session attaches an LLM vault that selects another supported engine.
  • The agent object is copied into the session snapshot. Later agent updates do not mutate existing sessions.

Next Steps#

Environments

Prepare reusable environments with packages and network policy.

Sessions

Create sessions that bind an agent snapshot to an environment and vaults.