Create Agent

POST/v1/agents

Create a reusable agent configuration that bundles a model, instructions, capabilities, and metadata. The returned ID can be used to start sessions.

Request body

Send a JSON object with the agent configuration.

string | objectmodelrequired

Model identifier or {id, effort?, speed?}. Responses always use the structured object.

stringnamerequired

Human-readable agent name. Accepts 1 to 256 characters.

Optional<string>description

Short explanation of the agent's purpose. Maximum 2,048 characters.

Optional<string>system

System instructions that define the agent's behavior. Maximum 100,000 characters.

Optional<array>tools

Built-in toolset and custom tool configurations. Maximum 128 tools.

Optional<array>mcp_servers

URL MCP servers referenced by MCP toolsets. Maximum 20.

Optional<object>metadata

Up to 16 application-defined key-value pairs.

Agent object

Fields returned for an agent resource.

stringidrequired

Stable identifier beginning with agent_.

integerversionrequired

Configuration version, beginning at 1 and incrementing after a successful change.

Optional<string · null>archived_at

RFC 3339 timestamp set after the agent is archived.

string · RFC 3339created_atrequired

Time the agent was created.

string · RFC 3339updated_atrequired

Time the current version was last updated.

Model choice

SandBase is multi-model. The model field accepts any available model identifier from the SandBase catalog.

Tool execution

Built-in tools run inside the managed agent runtime. Custom tools are executed by your client after an agent.custom_tool_use event.

Errors

400invalid_request

A required field is missing or a field has an invalid value.

401authentication_error

The API key is missing or invalid.

curl -X POST https://api.sandbase.ai/v1/agents \
  -H "Authorization: Bearer $SANDBASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-sonnet-4",
    "name": "Research Assistant",
    "system": "Research carefully and cite sources.",
    "tools": [{"type": "agent_toolset_20260401"}]
  }'

Response200 OK

{
  "id": "agent_01HqR2k7...",
  "type": "agent",
  "version": 1,
  "name": "Research Assistant",
  "description": null,
  "model": {"id": "claude-sonnet-4", "effort": {"type": "high"}, "speed": "standard"},
  "system": "Research carefully and cite sources.",
  "tools": [{ "type": "agent_toolset_20260401" }],
  "metadata": {},
  "archived_at": null,
  "created_at": "2026-05-29T10:00:00Z",
  "updated_at": "2026-05-29T10:00:00Z"
}