# Building agents



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

## Create an agent [#create-an-agent]

<Tabs items="['Console', 'API']">
  <Tab value="Console">
    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](/docs/agents/vaults-and-mcp) servers for extra tools.
    * **Connectors** — curated integrations (Gmail, hosted MCP services) from the
      [connector catalog](/docs/agents/vaults-and-mcp#connectors).
    * **Environment / VM** — an optional default VM template (+ repos) for the agent's
      runs. Leave it as *None* for an HTTP-only agent.
  </Tab>

  <Tab value="API">
    `POST /v1/agents`. Only `name` and `model` are required; everything else is
    optional.

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

## Models [#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:

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

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

<Callout>
  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.
</Callout>

## Tools [#tools]

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

```bash
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](/docs/agents/environments). For external tools served
over MCP, see [Vaults & MCP](/docs/agents/vaults-and-mcp).

## Connectors [#connectors]

`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](/docs/agents/vaults-and-mcp#connectors)
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 [#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 [#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 &#x2A;*`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`.

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

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

## Archiving & deleting [#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.

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

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