Agents

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

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.

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.
• MCP: agents, agent, 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.