# Quickstart



This guide builds a simple web-search agent and runs it. You'll do it once in the
[Console](https://console.clusterbase.ai), then see the equivalent API calls.

## Build an agent [#build-an-agent]

<Tabs items="['Console', 'API']">
  <Tab value="Console">
    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*&#x2A;, then try a prompt like
      &#x2A;"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.
  </Tab>

  <Tab value="API">
    Create an agent with `POST /v1/agents`. Only `name` and `model` are required.

    ```bash
    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`:

    ```json
    {
      "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"
    }
    ```
  </Tab>
</Tabs>

## Run it [#run-it]

<Tabs items="['Console', 'API']">
  <Tab value="Console">
    Open the agent and start a session. Type a message in the chat — for example
    &#x2A;"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.
  </Tab>

  <Tab value="API">
    Start a session on the agent:

    ```bash
    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`:

    ```bash
    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:

    ```bash
    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"},...}
    ```
  </Tab>
</Tabs>

## Where to go next [#where-to-go-next]

* [Building agents](/docs/agents/agents) — models, tools, system prompts, versioning.
* [Sessions & events](/docs/agents/sessions-and-events) — the full event stream and how to drive a turn.
* [Schedules](/docs/agents/schedules) and [triggers](/docs/agents/triggers) — run agents automatically.

<Callout title="Getting a token">
  `$CLUSTER_TOKEN` is a Bearer JWT from [Sign in with Cluster](/docs/ccp/oidc).
  See [Authentication](/docs/agents/api-reference#authentication).
</Callout>