Building agents

Create and configure agents — models, system prompts, tools, connectors, reasoning effort, versioning, and removal.

An agent is a reusable configuration. This page covers everything you can set on one and how edits are versioned.

Create an agent

Open Agents → New. You can either describe the agent to the agent builder and let it assemble the configuration, or fill in the form directly:

Name — what the agent is called.
Model — picked from the available models.
Reasoning effort — depth of reasoning (only for models that support it).
System prompt — the agent's role and instructions.
Tools — choose from the built-in tool catalog.
MCP servers — remote MCP servers for extra tools.
Connectors — curated integrations (Gmail, hosted MCP services) from the connector catalog.
Environment / VM — an optional default VM template (+ repos) for the agent's runs. Leave it as None for an HTTP-only agent.

POST /v1/agents. Only name and model are required; everything else is optional.

curl https://agents.clusterbase.dev/v1/agents \
  -H "Authorization: Bearer $CLUSTER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "code-reviewer",
    "model": "claude-opus-4-8",
    "system": "You review pull requests for correctness and clarity.",
    "tools": [{ "name": "web_search" }],
    "reasoning_effort": "high",
    "metadata": { "team": "platform" }
  }'

The response is the full agent at version: 1.

Models

An agent's model must be one the service supports. Fetch the live catalog — each entry includes the context window, whether it can reason, and which reasoning levels it accepts:

curl https://agents.clusterbase.dev/v1/models \
  -H "Authorization: Bearer $CLUSTER_TOKEN"

{
  "data": [
    {
      "id": "claude-opus-4-8",
      "owned_by": "anthropic",
      "context_window": 1000000,
      "can_reason": true,
      "reasoning_levels": ["low", "medium", "high"]
    }
  ]
}

Treat GET /v1/models as the source of truth rather than hard-coding a model list. The Console's model picker is populated from this endpoint.

Tools

tools is a list of { "name": "..." } references to built-in tools. Fetch the catalog of attachable tools:

curl https://agents.clusterbase.dev/v1/tools \
  -H "Authorization: Bearer $CLUSTER_TOKEN"
# → { "data": [{ "name": "web_search", "description": "..." }, ...] }

Some tools (shell, file read/write, patch) only function when the session runs inside a VM environment. For external tools served over MCP, see Vaults & MCP.

mcp_services is a list of curated connector ids — hosted MCP services and native integrations such as Gmail — enabled for every turn. The ids are validated against the connector catalog on create and patch. The agent definition stores only the ids: at run time, the tools resolve with the session owner's connections, so each user acts with their own credentials.

Reasoning effort

For models where can_reason is true, set reasoning_effort to one of minimal, low, medium, high, xhigh, or max. The allowed set is validated per model — a value the model doesn't support is rejected. Omit it to use the model's default.

Versioning

Editing an agent with PATCH /v1/agents/{id} produces a new version. The patch is tri-state per field:

Omit a field to leave it unchanged.
Send null to clear a clearable field (system, reasoning_effort, org_id, environment).
Send a value to set it. tools, mcp_servers, and mcp_services are full replaces (send [] to clear them).

version is required in the body for optimistic concurrency — if it doesn't match the current version, the request returns 409 Conflict.

curl -X PATCH https://agents.clusterbase.dev/v1/agents/agt_3f9c2a \
  -H "Authorization: Bearer $CLUSTER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "version": 1,
    "system": "You review PRs for correctness, clarity, and security.",
    "reasoning_effort": "max"
  }'
# → agent at version 2

Existing sessions are unaffected — each session keeps running the version it was created with. To inspect history:

curl https://agents.clusterbase.dev/v1/agents/agt_3f9c2a/versions \
  -H "Authorization: Bearer $CLUSTER_TOKEN"

Archiving & deleting

There are two ways to remove an agent, and they differ in what survives.

Archive soft-deletes. Existing sessions persist, but the agent stops appearing in lists and can no longer start new sessions. Nothing is destroyed.

curl -X POST https://agents.clusterbase.dev/v1/agents/agt_3f9c2a/archive \
  -H "Authorization: Bearer $CLUSTER_TOKEN"

Delete is permanent. DELETE /v1/agents/{id} removes the whole aggregate — every version, plus its sessions and their events, runs, schedules, triggers, and deployments. It works for manifest-applied agents too. If the agent has active work, the request returns 409 — wait for it to finish or cancel it first.

curl -X DELETE https://agents.clusterbase.dev/v1/agents/agt_3f9c2a \
  -H "Authorization: Bearer $CLUSTER_TOKEN"
# → 204

When in doubt, archive — you can't get a deleted agent back.