> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rerun.build/llms.txt
> Use this file to discover all available pages before exploring further.

# Agents

> List Boxes, read an agent in full, create, update and delete agents.

An agent lives inside a Box. Start from `list_spaces` when you need a `spaceId`, and from `list_agents` when you need an `agentId`: every other tool on this page takes one of those two.

## list\_spaces

Lists the Boxes of the workspace with how many agents each one holds.

Takes no arguments.

```json Response theme={"system"}
{
  "spaces": [
    { "id": "…", "name": "Main Box", "agentCount": 3, "createdAt": "2026-07-04T10:12:00.000Z" }
  ]
}
```

## list\_agents

Lists the agents of the workspace, newest first.

<ParamField body="spaceId" type="string">
  Restrict the list to one Box.
</ParamField>

Each agent carries `id`, `name` (the display name), `handle` (the mention and call key), `description`, `status`, `space_id` and `created_at`. The `id` is what every other tool takes as `agentId`.

## get\_agent

The full picture of one agent in a single call. Read this before changing anything.

<ParamField body="agentId" type="string" required />

Returns the agent identity (`handle`, `name`, `description`), its `soul` (the system prompt), its model settings (`provider`, `model`, `temperature`, `stepLimit`), its enabled `tools` families, its `selfImprovement` flags, its `setup` answer with the install instructions behind it, its custom `mcpServers`, and summaries of its `skills`, `schedules`, `triggers` and `connectors`.

Skills and scheduled tasks are summarised here. Use [`get_skill`](/api/tools/skills) and [`list_schedules`](/api/tools/schedules) for their full text.

<Note>
  `get_agent` deliberately omits trigger URLs, because a trigger URL carries a secret. Use [`list_triggers`](/api/tools/triggers) to read them on purpose.
</Note>

## create\_agent

Creates an agent and places it on the board. It is visible in the app immediately.

<ParamField body="name" type="string" required>
  Free display name, for example `Content Manager`.
</ParamField>

<ParamField body="soul" type="string">
  The system prompt, in markdown. Who the agent is, what it owns, how it works. This is the single most important field, so write it properly rather than leaving it empty.
</ParamField>

<ParamField body="description" type="string">
  One line on what this agent is for.
</ParamField>

<ParamField body="spaceId" type="string">
  Optional when the workspace has a single Box. With several Boxes, the call fails and lists them so you can pick.
</ParamField>

<ParamField body="connectors" type="string[]">
  Catalog slugs to declare on the agent. The response gives each one its real status. See [Connectors](/api/tools/connectors).
</ParamField>

<ParamField body="provider" type="string">
  One of `rerun`, `anthropic`, `claude`, `codex`, `openai`, `google`, `openrouter`.
</ParamField>

<ParamField body="model" type="string" />

<ParamField body="temperature" type="number" />

<ParamField body="stepLimit" type="number">
  Maximum number of tool-calling steps in one run.
</ParamField>

<ParamField body="tools" type="object">
  Capability families, all on by default, for example `{"shell": false, "browser": false}`. See [Configure an agent](/agents/configure) for the list.
</ParamField>

<ParamField body="selfImprovement" type="object">
  Defaults to everything on. `{"allowSoulEdit": false, "allowToolInstall": false}` pins the agent to the prompt and the tools you gave it.
</ParamField>

<ParamField body="setup" type="object">
  The guided setup this agent runs on the account of whoever installs it from a template. `required` is a boolean and is mandatory inside the object. `prompt` is required when `required` is `true`, and is addressed to the agent, not to the user.
</ParamField>

<Warning>
  An agent created with defaults may rewrite its own prompt and install its own tools. Pass `selfImprovement` explicitly when that is not what you want.
</Warning>

```json Response theme={"system"}
{
  "agentId": "…",
  "name": "Content Manager",
  "handle": "content_manager",
  "spaceId": "…",
  "active": true,
  "connectors": [{ "slug": "notion", "name": "Notion", "status": "needs_auth" }]
}
```

`active: false` means the creation succeeded but the plan has no free agent slot, so the agent will not run until one frees up. An `inactiveReason` explains it.

## update\_agent

Updates an agent. Every field is optional and only what you pass changes.

<ParamField body="agentId" type="string" required />

<ParamField body="name" type="string">
  Display name only. It does not change the handle.
</ParamField>

<ParamField body="handle" type="string">
  The mention and call key. Changing it breaks every `@handle` written into another agent prompt.
</ParamField>

<ParamField body="soul" type="string">
  Full replacement of the system prompt, in markdown.
</ParamField>

<ParamField body="description" type="string" />

<ParamField body="provider" type="string" />

<ParamField body="model" type="string" />

<ParamField body="temperature" type="number" />

<ParamField body="stepLimit" type="number" />

<ParamField body="tools" type="object">
  Capability families to toggle, for example `{"shell": false, "browser": true}`.
</ParamField>

<ParamField body="selfImprovement" type="object" />

<ParamField body="setup" type="object" />

Renaming is safe. `name` is only what is displayed, and the handle other agents call with `@handle` stays put. Move the handle only when you mean to.

The response lists the fields that were actually written in `updated`.

## delete\_agent

Permanently deletes an agent with its skills, scheduled tasks, memory and workspace files. Irreversible.

<ParamField body="agentId" type="string" required />

<ParamField body="confirm" type="boolean" required>
  Must be `true`. See [Destructive tools](/api/protocol#destructive-tools).
</ParamField>