Create Agent

POST/v1/agents

Create a reusable Agent configuration that bundles a catalog model, instructions, capabilities, and metadata. Model IDs use vendor/model form. Unknown request fields are accepted and ignored.

Request body

Send a JSON object with the agent configuration.

string | objectmodelrequired

Available vendor/model identifier or {id, effort?, speed?}. Responses always use the structured object.

stringnamerequired

Human-readable Agent name.

Optional<string>description

Short explanation of the Agent's purpose. Null is accepted as an empty string on creation.

Optional<string>system

System instructions that define the Agent's behavior. Null is accepted as an empty string on creation.

Optional<array>tools

Built-in toolset and custom tool configurations. Omission installs the default Agent toolset; explicit null does not.

Optional<array>mcp_servers

MCP server configurations available to the Agent runtime.

Optional<array>skills

Skills available to the Agent runtime.

Optional<array>handoffs

Agent handoff configurations.

Optional<object>metadata

Application-defined JSON metadata. The platform-owned _sandbase namespace is stripped from public requests.

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": "anthropic/claude-sonnet-5",
    "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": "",
  "model": {
    "id": "anthropic/claude-sonnet-5"
  },
  "system": "Research carefully and cite sources.",
  "tools": [
    {
      "type": "agent_toolset_20260401"
    }
  ],
  "mcp_servers": null,
  "skills": null,
  "handoffs": null,
  "metadata": null,
  "archived_at": null,
  "created_at": "2026-05-29T10:00:00Z",
  "updated_at": "2026-05-29T10:00:00Z"
}