Run books

What to do, step by step, when something goes wrong. Each run book uses only what you can see and do yourself, in LightHouse and in your own account.

An agent is failing

1. Find it. Agents → Hub, filtered to failing, or GET /api/v1/agents?status=failing. GET /api/v1/attention lists it too.
2. Open its last run. The run map shows which step failed, its status, its model and its duration.
3. Check its dependencies. An agent whose needs failed is skipped, not failed: fix the first failure in the chain.
4. Check the safeguards. Security and context → Safeguards, or GET /api/v1/refusals: a refusal for a cap, a kill switch, screening or grounding stops a call by design.
5. Check the deployment. GET /api/v1/health, or the health tool: a gateway or job reported down or degraded explains every agent on it.
6. Stop it while you look, if its failures cost or annoy: a handler pauses it (agent.pause). See Suspension.
7. Fix and release. A change to the card or its code goes through the release gate; to go back, make the last version that passed current. See Versioning and rollback.

A cap is reached

1. See which. GET /api/v1/budgets lists each scope’s cap and spend; GET /api/v1/refusals shows calls refused for it.
2. Decide whether the cap is right. A cap is reached by design when an agent loops or a job grows. Check the agent’s runs and cost per run in Spend → Cost first.
3. To raise it, a person does: a handler’s budget.set for one agent (raising needs a role your deployment’s policy names, and never goes past its ceiling), or a client_admin changes the limit under Spend → Limits. A machine key cannot.
4. To keep it, do nothing: calls past the cap are refused until the period resets (UTC day or month), or the cap is raised.

See Limits and alerts.

A connector stops indexing

1. Check the card. Setup and admin → Connectors: a failing, expiring or disconnected state, and the failures over the last 7 days.
2. Check the knowledge base. Agents → Knowledge: the last successful ingest, and failures by class (auth, permission, not_found, rate_limited, timeout, network, parse, config).
3. By class:
   • auth or permission: the credential expired, was revoked or lost access. Replace it in your secret store; for a LightHouse connection, connect again.
   • rate_limited or timeout: the provider slowed the pull. It retries on its next schedule; widen the schedule if it persists.
   • config: the source card is wrong (a missing repository, a bad URL). Fix the card.
   • parse: an item could not be read. For a folder, a file type it does not accept stops the pull, naming the file.
4. Run it once by hand and read its note: written N, unchanged N, quarantined N, removed N. The cursor advances only when every item was written, so a failed pull is repeated in full, never skipped.

See Connect your estate.