Build your first agent and run it — in the Console or over the API — in a couple of minutes.

Quickstart

This guide builds a simple web-search agent and runs it. You'll do it once in the Console, then see the equivalent API calls.

Build an agent

The Console gives you two ways to create an agent:

Agent builder — describe the agent in plain language and a meta-agent builds it for you. Open Agents → New, then try a prompt like "Create a web-search agent on claude-haiku-4-5". The builder can also add tools, configure MCP servers, and create vaults as you chat.
Agent form — fill in the fields directly: Name, Model, optional Reasoning effort, System prompt, Tools, MCP servers, and an optional Environment / VM.

Either way you end up with a saved agent you can run, schedule, and edit.

Create an agent with POST /v1/agents. Only name and model are required.

curl https://agents.clusterbase.dev/v1/agents \
  -H "Authorization: Bearer $CLUSTER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "researcher",
    "model": "claude-haiku-4-5",
    "system": "You are a concise research assistant. Cite your sources.",
    "tools": [{ "name": "web_search" }]
  }'

The response is the created agent, including its server-assigned id and version:

{
  "id": "agt_3f9c2a",
  "name": "researcher",
  "model": "claude-haiku-4-5",
  "system": "You are a concise research assistant. Cite your sources.",
  "tools": [{ "name": "web_search" }],
  "version": 1,
  "created_at": "2026-06-16T12:00:00Z",
  "updated_at": "2026-06-16T12:00:00Z"
}

Open the agent and start a session. Type a message in the chat — for example "What shipped in the latest TypeScript release?" — and watch the agent's reasoning, tool calls, and reply stream into the transcript in real time. Use the stop button to interrupt a turn.

Start a session on the agent:

curl https://agents.clusterbase.dev/v1/sessions \
  -H "Authorization: Bearer $CLUSTER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "agent": "agt_3f9c2a" }'
# → { "id": "ses_8b1d4e", "agent_id": "agt_3f9c2a", "agent_version": 1, ... }

Append a message — note that events are always submitted as a batch under events:

curl https://agents.clusterbase.dev/v1/sessions/ses_8b1d4e/events \
  -H "Authorization: Bearer $CLUSTER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      { "type": "user.message", "content": [{ "type": "text", "text": "What shipped in the latest TypeScript release?" }] }
    ]
  }'

Stream the agent's response over Server-Sent Events:

curl -N https://agents.clusterbase.dev/v1/sessions/ses_8b1d4e/events/stream \
  -H "Authorization: Bearer $CLUSTER_TOKEN"

data: {"type":"session.status_running","id":"evt_01",...}
data: {"type":"agent.tool_use","id":"evt_02","tool":"web_search","input":{"query":"..."},...}
data: {"type":"agent.message","id":"evt_03","content":[{"type":"text","text":"..."}],...}
data: {"type":"session.status_idle","id":"evt_04","stop_reason":{"type":"end_turn"},...}

Where to go next

Building agents — models, tools, system prompts, versioning.
Sessions & events — the full event stream and how to drive a turn.
Schedules and triggers — run agents automatically.

Getting a token

$CLUSTER_TOKEN is a Bearer JWT from Sign in with Cluster. See Authentication.

Quickstart

Quickstart

Build an agent

Run it

Where to go next

On this page