# Agents

> An agent is a versioned card: its job, its model, its tools, its caps and its approvals.

An **agent** is one card in a pack’s catalogue: a versioned declaration of the job it does, the tools it may use, the model it may call, its budget, whether its work has an effect outside the run, and how much autonomy it has. The engine runs an agent only under its card, and grants nothing the card does not list.

## The agent card

A pack’s catalogue is a YAML file kept in your own repository. Each card declares:

| Field                  | What it says                                                                                                                                   |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                   | The card’s name in its pack                                                                                                                    |
| `purpose`              | What it is for, in one line                                                                                                                    |
| `executor`             | How it runs: `python` (a function), `command` (a program) or `claude-code`                                                                     |
| `overseer`             | The named person answerable for it                                                                                                             |
| `budget_usd`           | Its spending cap per run, enforced by the [gateway](/concepts/gateway/)                                                                        |
| `tools`                | The whole list of tools it may use; nothing else is granted                                                                                    |
| `model`                | A model or a tier, checked by the gateway                                                                                                      |
| `needs`                | The cards whose output it is given                                                                                                             |
| `produces`             | The artefact that proves it ran; a card that writes nothing has failed                                                                         |
| `effect`               | `internal` (writes only to the run’s own store) or `external` (sends, publishes or writes into one of your systems). The default is `external` |
| `autonomy`             | For an external effect: 0, 1 or 2 (below)                                                                                                      |
| `timeout_s`, `retries` | How long it may take, and how often it is retried                                                                                              |

A malformed catalogue is refused whole: a half-loaded catalogue would run some agents under rules nobody reviewed. To write one, see [In code](/build/code/).

## Packs and agent IDs

Cards are grouped in **packs**: one catalogue, one team’s agents, with one autonomy ceiling. An agent’s ID is `<pack>:<card>`, for example `research:summary`. The pack is a lower-case slug; the card is letters, digits and `._:-`. The API and MCP use this ID everywhere.

## Autonomy

Autonomy governs actions with consequence, so only an `external` card is gated.

| Level           | Shown as       | What happens to its output                                                         |
| --------------- | -------------- | ---------------------------------------------------------------------------------- |
| internal effect | `internal`     | Runs unattended; it writes only to the run’s own store                             |
| 0               | `draft`        | A draft. Nothing downstream may use it                                             |
| 1               | `sign-off`     | Waits for a named person to approve it in LightHouse                               |
| 2               | `pre-approved` | Goes ahead within a standing pre-approval’s limits; otherwise waits, as at level 1 |

A pack’s ceiling can lower a card’s level, never raise it. The default ceiling is 1: a pack opts in to level 2 by saying `ceiling: 2`. Level 3 and above are refused. See [Approvals](/concepts/approvals/).

## Live state

LightHouse shows each agent’s state from what its deployment has reported, never a guess:

| State               | Means                                                                   |
| ------------------- | ----------------------------------------------------------------------- |
| `running`           | It has called a model in the last ten minutes, since its last run ended |
| `idle`              | No record says otherwise                                                |
| `failing`           | Its last run failed                                                     |
| `paused`            | The kill switch is on for it, its pack or the whole tenant              |
| `awaiting-sign-off` | Its last run’s output is waiting for a person                           |

## In LightHouse and the API

- **Agents → Hub** lists every agent with its state, spend and last run; **Agents → Map** draws how they hand work to each other.
- `GET /api/v1/agents` (filter by `status`), `GET /api/v1/agents/{agent_id}`, `GET /api/v1/agent-map`: see the [Read reference](/api/reference/read/#agents-list).
- MCP: [`agents`](/mcp/tools/agents/), [`agent`](/mcp/tools/agent/), [`agent_map`](/mcp/tools/agent-map/).

A card’s instructions, command and prompts never leave your account. LightHouse sees its settings, and its `purpose` only if the pack chooses to publish it.

Source: https://docs.atlanticagenticlabs.com/concepts/agents/