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

# Agent & Capabilities

> How Overmind models your agent — one graph per project, made of capabilities discovered by a local scan, described by agent-authored cards, and confirmed by telemetry.

export const Ascii = ({lines}) => <pre className="om-ascii">{lines.join("\n")}</pre>;

Your **agent** in Overmind is the product itself: one per project, mapped as a graph of **capabilities**. A capability is one purpose the product serves — triage tickets, answer from the knowledge base, resolve a dispute. Each capability record joins two sides: static structure from your repository (entry points, prompts, tools, modes, call edges) and runtime behaviour from telemetry (traces, task executions, live scores). Everything else on the platform hangs off capabilities — traces bind to one, datasets are aligned to one, eval sets belong to one, optimisation runs edit a capability's code, and trained models are benchmarked against the model a capability runs in production.

## How capabilities get into Overmind

<Ascii
  lines={[
"╔══════════════════════╗                               ╔═ Overmind ══════╗",
"║      Local repo      ║                               ║                 ║",
"║chassis → cards → sync╟────POST /api/v1/sync/─────┐   ║                 ║",
"╚══════════════════════╝                           │   ║  ╔════════════╗ ║",
"                                                   ├───╫─▶║ Capability ║ ║",
"╔══════════════════════╗                           │   ║  ╚════════════╝ ║",
"║ Production telemetry ╟──overmind.capability.id───┘   ║                 ║",
"╚══════════════════════╝                               ║                 ║",
"                                                       ╚═════════════════╝",
]}
/>

<Ascii
  lines={[
"╔═ Overmind ═════════════════════════════════════════════════════╗",
"║                  ┌───────┬────────────┬──────────────┐         ║",
"║                  │       ▼            ▼              ▼         ║",
"║ ╔════════════╗   │  ╔════════╗  ╔══════════╗  ╔════════════╗   ║",
"║ ║ Capability ╟───┤  ║ Traces ║  ║ Datasets ║  ║ Eval sets  ║   ║",
"║ ╚════════════╝   │  ╚════════╝  ╚══════════╝  ╚════════════╝   ║",
"║                  │                                             ║",
"║                  └────────────┬──────────────────────┐         ║",
"║                               ▼                      ▼         ║",
"║                     ╔═══════════════════╗   ╔════════════════╗ ║",
"║                     ║ Optimisation runs ║   ║ Trained models ║ ║",
"║                     ╚═══════════════════╝   ╚════════════════╝ ║",
"║                                                                ║",
"╚════════════════════════════════════════════════════════════════╝",
]}
/>

### The scan

Discovery runs in your repository, not on the server. `/overmind setup` in your coding agent drives it; `overmind chassis` and `overmind sync` are the CLI halves. See the [CLI](/platform/cli).

<Steps>
  <Step title="overmind chassis">
    Prints a deterministic AST inventory of Python functions and call edges under the repository root. `/overmind setup` runs this first; the digest is ground truth the cards must not contradict.
  </Step>

  <Step title="Author the cards">
    The coding agent reads the source against that chassis and writes one capability per product purpose into `overmind.toml` — name, slug, entry point, prompt, tools, and a **card**: task, input/output contract, success criteria, failure modes, and a trajectory map of anchors with `file#Lstart-Lend` provenance. Roles inside one orchestration — a crew, a graph of workers, a supervisor with specialists — are **modes** of the one capability that orchestration serves, not separate capabilities. There is no server-side model call.
  </Step>

  <Step title="overmind sync">
    POSTs `overmind.toml` to `POST /api/v1/sync`. The response carries assigned capability ids, and the CLI writes them back. The first sync with an account-scoped key creates the project and mints the project-scoped key the MCP entry uses.
  </Step>
</Steps>

After code changes: `/overmind setup` again, then `overmind sync`. A trajectory entry whose anchors are not call-graph reachable from its entry is stamped `verified = false`.

### What the server does with a sync

`POST /api/v1/sync` reconciles the snapshot with the project's capabilities. Then, per capability:

* **Identity is carried**, in order: the toml `id` → the toml `slug` → a new record. A capability the push no longer includes becomes a leftover (`archived = true` in the toml on the next `sync down`).
* **Behaviours are minted from the trajectory map**: one contract per mapped route, with an entry anchor, the ordered anchors that follow it, and its tool set. Behaviours are what [trace scoring](/agent-testing/trace-scoring#behaviours-and-bindings) binds production traffic to; the Console labels the column **Task**.
* **The Default eval set is preloaded** for every created, remounted or card-changed capability: Tier-0 rule-based checks compiled from the card, Tier-1 generative LLM judges grounded in it, and per-behaviour outcome and step judges for trace scoring. See [Eval](/agent-testing/eval#authoring).

### A scan never deletes

A capability the push no longer includes becomes a **leftover**: it keeps its id and data, leaves the agent view, shows a **Not in latest scan** badge, and remounts in place when a later push reproduces it. `slug` in `overmind.toml` is the server identity — rename a capability by editing `name`, never `slug`.

To remove a capability yourself, use **Delete capability** at the bottom of its page (`DELETE /api/capabilities/{id}/`). The record is soft-deleted: it leaves lists, scans and identity lookup, its traces, datasets and runs stay, and its inference alias stops serving. Because a deleted capability is invisible to later syncs, the next push of the same code mints a fresh record.

### Telemetry

Spans carrying `overmind.capability.id` — set with [`init(capability_id=...)`](/tracing/sdk-python#init) or a `capability(..., id=)` scope — bind to that capability. The value is the capability's UUID or its toml `slug`; both resolve, and both are stable through renames. `overmind.capability.name` is a display label and never binds.

Ingest never creates a capability. An identity the project does not know leaves the span **unbound**: it is stored, browsable under Observability's Unbound filter, and binds retroactively when a later push makes the identity resolvable. `confirmed_at` is stamped on the capability the first time a span binds to one of its behaviours; the capability page shows **Confirmed** or **Unconfirmed** accordingly. A capability created by hand (`POST /api/capabilities/`) carries an **Observed** badge instead, because no scan can confirm or retire it.

## The agent page

**Agent** in the sidebar opens the product view: the capability grid, or the onboarding prompt while the project is still empty. Open a capability for its page.

<Frame caption="The Agent page: one card per capability with its model, traffic, and live score.">
  <img src="https://mintcdn.com/overmind-b84ae13c/OG-4bZDDAnV78HJp/images/platform/agent-home.jpg?fit=max&auto=format&n=OG-4bZDDAnV78HJp&q=85&s=c7a67ea8444ed7f455519175b297bc4f" alt="Agent page with the capability grid" width="1512" height="794" data-path="images/platform/agent-home.jpg" />
</Frame>

The header carries the name (editable in place), copyable **capability id** and **project id** chips, the slug, the badges — **Declared** or **Inferred** (whether the manifest named it), **Confirmed** or **Unconfirmed**, **Not in latest scan** — and a **Last push** line linking to the project's scan report. **View traces** opens the capability's filtered Observability view. Below it, one scrolling page:

* **Facts** — the model the capability serves through (or the live deployed model behind its alias) and its source path.
* **Prompt** — the system prompt lifted from your code, one per mode when the capability has several.
* **Trajectory map** — the entry point, each behaviour's steps with the tools they may use, and its terminal, as an interactive graph.
* **Components** — every anchor, tool and utility the scan found, with file-level provenance.
* **Dataset** — datasets aligned to this capability. See [Datasets](/core/datasets).
* **Eval metrics** — the capability's eval sets and evaluators, with score history over its runs. See [Eval](/agent-testing/eval).
* **Models** — the production model and any models trained on this capability's data, linking into [Models](/models/training) and [Inference](/models/inference).

<Frame caption="A capability page: facts, the prompt, and the trajectory map with two behaviours.">
  <img src="https://mintcdn.com/overmind-b84ae13c/OG-4bZDDAnV78HJp/images/platform/capability-page.jpg?fit=max&auto=format&n=OG-4bZDDAnV78HJp&q=85&s=c204175f06983862d5b2499ffabb1b7b" alt="Capability page with facts bar, prompt card and trajectory map" width="1456" height="821" data-path="images/platform/capability-page.jpg" />
</Frame>

<Frame caption="The trajectory map expanded: the entry point, each behaviour's steps and the tools they may use, and its terminal.">
  <img src="https://mintcdn.com/overmind-b84ae13c/OG-4bZDDAnV78HJp/images/platform/capability-flow.jpg?fit=max&auto=format&n=OG-4bZDDAnV78HJp&q=85&s=71fd50e9ba3f32142f7592218d8de4db" alt="Trajectory map fullscreen view" width="1456" height="821" data-path="images/platform/capability-flow.jpg" />
</Frame>

The Agent page is the record of the latest sync: each capability with its card, behaviours, and whether telemetry has confirmed it.

## Instrumentation

Which of a capability's anchors emit telemetry is answered by the traces themselves: a task execution's route shows the contract anchors it matched, and a behaviour with no executions has none. To close a gap, ask your coding agent: the `get_instrumentation_plan` MCP tool returns placement tickets (file, qualname, decorator, required scope) for the project or one capability, and `verify_instrumentation` grades a fresh trace against the contract without writing anything. The `/overmind ensure-tracing` command runs that loop. See [MCP](/platform/mcp).

## API

```bash theme={"dark"}
# The whole agent graph: current capabilities, their edges, and the latest scan
curl -H "X-Api-Key: $OVERMIND_API_KEY" "https://api.overmindlab.ai/api/agent/?project={project_id}"

# List capabilities / one capability
curl -H "X-Api-Key: $OVERMIND_API_KEY" "https://api.overmindlab.ai/api/capabilities/"
curl -H "X-Api-Key: $OVERMIND_API_KEY" "https://api.overmindlab.ai/api/capabilities/{id}/"

# The evaluation spec and the selectable system prompts
curl -H "X-Api-Key: $OVERMIND_API_KEY" "https://api.overmindlab.ai/api/capabilities/{id}/eval_spec/"
curl -H "X-Api-Key: $OVERMIND_API_KEY" "https://api.overmindlab.ai/api/capabilities/{id}/prompts/"

# Behaviours and how well the eval set covers each one
curl -H "X-Api-Key: $OVERMIND_API_KEY" "https://api.overmindlab.ai/api/behaviours/"
curl -H "X-Api-Key: $OVERMIND_API_KEY" "https://api.overmindlab.ai/api/behaviours/coverage/?capability={id}"

# Pull the reconciled snapshot (leftovers come back archived)
curl -H "X-Api-Key: $OVERMIND_API_KEY" "https://api.overmindlab.ai/api/v1/sync?project_id={project_id}"
```

`GET /api/capabilities/` returns current capabilities unless `?status=` asks for leftovers. `PATCH /api/capabilities/{id}/` updates mutable fields, including `model` and `active_model`. `POST /api/v1/sync` is what `overmind sync` speaks; it takes API-key auth and requires `project_id` to be in the key's scope (a project-scoped key supplies its one project). Through MCP: `inspect_capability_health`, `query_failures`, and the `overmind://capabilities/{capability}` resource. See the [REST API](/platform/api) for the full surface.

## Good to know

* **The baseline matters.** The capability's `model` field is what training benchmarks and optimiser baselines measure against. The card is where the model gets named when the codebase resolves models through a role chain rather than a literal.
* **Commit `overmind.toml`.** It carries the ids and the authored cards that keep identity and semantics stable across syncs. `.overmind/credentials.toml` holds the project key and is excluded from git by `overmind sync`.
* **Pin identity in code.** `overmind.init(capability_id="<slug-or-uuid>")` or a `capability(..., id=)` scope stamps `overmind.capability.id` on every span inside. Ingest binds by that id alone.