Create Agent

POST/v1/agents

Create a reusable, versioned agent. An agent bundles a model, system prompt, tools, and MCP servers into a configuration you reference by ID when creating sessions.

Claude API compatibility

SandBase implements a subset of the Claude Managed Agents Agent API. The fields below are supported today. Claude's skills and multiagent fields are accepted for forward compatibility but not yet active.

Request Parameters

Parameter	Type	Required	Description
model	string | object	✅	Model identifier. A model string (e.g. "claude-sonnet-4", "gpt-4o") or a { "id", "speed" } object.
name	string	✅	Human-readable name. 1–256 characters.
description	string	❌	What the agent does. Up to 2048 characters.
system	string	❌	System prompt. Up to 100,000 characters.
tools	array	❌	Tool configurations. Max 128 tools across all toolsets.
mcp_servers	array	❌	MCP servers to connect. Max 20. Names must be unique.
metadata	object	❌	Arbitrary key-value metadata. Max 16 pairs, keys ≤ 64 chars, values ≤ 512 chars.

Model

SandBase is multi-model — model accepts any model identifier from the SandBase catalog, not only Claude models.

// String form
"claude-sonnet-4"

// Object form
{ "id": "claude-sonnet-4", "speed": "standard" }

Field	Type	Description
id	string	Model identifier
speed	string	"standard" (default) or "fast". Not all models support fast.

Tools

The tools array can contain three tool types.

Built-in Agent Toolset

{
  "type": "agent_toolset_20260401",
  "default_config": {
    "enabled": true,
    "permission_policy": { "type": "always_ask" }
  },
  "configs": [
    { "name": "bash", "enabled": true, "permission_policy": { "type": "always_allow" } }
  ]
}

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

permission_policy.type is always_allow (auto-approved) or always_ask (requires user.tool_confirmation).

MCP Toolset

{
  "type": "mcp_toolset",
  "mcp_server_name": "web-search",
  "default_config": { "enabled": true, "permission_policy": { "type": "always_allow" } },
  "configs": [
    { "name": "search", "enabled": true, "permission_policy": { "type": "always_allow" } }
  ]
}

mcp_server_name must match a server in the mcp_servers array.

Custom Tool

Executed by your client, not the agent. The agent emits agent.custom_tool_use and the session goes idle awaiting user.custom_tool_result.

{
  "type": "custom",
  "name": "query_database",
  "description": "Execute a read-only SQL query",
  "input_schema": {
    "type": "object",
    "properties": { "query": { "type": "string" } },
    "required": ["query"]
  }
}

MCP Servers

[
  { "name": "web-search", "type": "url", "url": "https://mcp.sandbase.ai/web-search/sse" }
]

Field	Type	Description
name	string	Unique name, referenced by mcp_toolset configs. 1–255 chars.
type	string	"url"
url	string	Endpoint URL for the MCP server.

Request Examples

Python

from anthropic import Anthropic

client = Anthropic(
    api_key="sk-sb-YOUR_KEY",
    base_url="https://api.sandbase.ai"
)

agent = client.beta.agents.create(
    model="claude-sonnet-4",
    name="Research Assistant",
    system="You are a research assistant. Search the web to answer questions.",
    tools=[{"type": "agent_toolset_20260401"}],
    mcp_servers=[
        {"name": "web-search", "type": "url", "url": "https://mcp.sandbase.ai/web-search/sse"}
    ]
)
print(agent.id)

TypeScript

import Anthropic from '@anthropic-ai/sdk';

const client = new Anthropic({
  apiKey: 'sk-sb-YOUR_KEY',
  baseURL: 'https://api.sandbase.ai',
});

const agent = await client.beta.agents.create({
  model: 'claude-sonnet-4',
  name: 'Research Assistant',
  system: 'You are a research assistant.',
  tools: [{ type: 'agent_toolset_20260401' }],
});
console.log(agent.id);

cURL

curl -X POST https://api.sandbase.ai/v1/agents \
  -H "Authorization: Bearer sk-sb-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4",
    "name": "Research Assistant",
    "system": "You are a research assistant.",
    "tools": [{"type": "agent_toolset_20260401"}]
  }'

Response

Returns an Agent object.

{
  "id": "agent_01HqR2k7vXbZ9mNpL3wYcT8f",
  "type": "agent",
  "version": 1,
  "name": "Research Assistant",
  "description": "A general-purpose research agent.",
  "model": { "id": "claude-sonnet-4", "speed": "standard" },
  "system": "You are a research assistant. Search the web to answer questions.",
  "tools": [
    {
      "type": "agent_toolset_20260401",
      "default_config": { "enabled": true, "permission_policy": { "type": "always_ask" } },
      "configs": [
        { "name": "bash", "enabled": true, "permission_policy": { "type": "always_allow" } }
      ]
    }
  ],
  "mcp_servers": [
    { "name": "web-search", "type": "url", "url": "https://mcp.sandbase.ai/web-search/sse" }
  ],
  "metadata": {},
  "archived_at": null,
  "created_at": "2026-05-29T10:00:00Z",
  "updated_at": "2026-05-29T10:00:00Z"
}

Agent Object

Field	Type	Description
id	string	Unique agent identifier (agent_...)
type	string	Always "agent"
version	integer	Starts at 1, increments on each modification
name	string	Agent name
description	string | null	Agent description
model	object	Model configuration (id, speed)
system	string | null	System prompt
tools	array	Resolved tool configurations
mcp_servers	array	Connected MCP servers
metadata	object	User-defined key-value pairs
archived_at	string | null	RFC 3339 timestamp when archived
created_at	string	RFC 3339 timestamp
updated_at	string	RFC 3339 timestamp

Roadmap

Claude's Agent object also includes skills (Anthropic/custom skills) and multiagent (coordinator topology). These are accepted for compatibility but not yet active in SandBase.

Errors

Status	Type	Description
400	invalid_request	Missing required fields or invalid format
401	authentication_error	Invalid or missing API key