The agent spec — the format you cannot break
app/agents/spec.py. Reference page: docs/reference/spec.md (generated from the
docstrings, so the reasoning belongs in the docstring). Concepts:
docs/concepts.md.
The most load-bearing type in the platform: the Builder edits it, the database versions it, the factory instantiates it, and clients export it as YAML into their own git repositories.
The constraint
Old specs must keep loading. A published agent's spec is stored as it was written. A change that only parses new documents is a 500 on every run of something nobody touched.
model_config = ConfigDict(extra="forbid") means an unknown key is a hard error, so
this is not theoretical. SPEC_VERSION is currently 13.
What each change costs
| Change | Cost |
|---|---|
| Add an optional field with a default | Free. Old specs take the default |
| Add a required field | Not allowed. Give it a default, or a mode="before" validator that supplies one |
| Rename a field | A mode="before" validator that moves the old key. CapabilityBindingSpec._fold_the_knowledge_capabilitys_own_rename is the worked example |
| Remove a field | Drop it in a mode="before" validator and log a warning — never let extra="forbid" raise on a stored spec. See _MODEL_SETTINGS_WITHDRAWN |
| Narrow a rule (shorter max, tighter pattern, new enum) | The dangerous one — see below |
| Move behaviour to a capability | Fold the old value into a binding, don't just drop it. _with_thinking_binding is the pattern |
Bump SPEC_VERSION whenever a stored document needs migrating, and write the
migration in the same change.
Narrowing a rule is a data migration
A narrower rule does not only reject new input — it makes existing rows unreadable, and a Pydantic model that refuses to validate one field of one row takes down the whole listing endpoint with a 500.
IngestionConfig and its OCR language codes are the worked example outside the
spec: ocr_language went from "anything 2–16 characters" to Tesseract's
^[a-z]{3}(\+[a-z]{3})*$, and every row written before it held "en". The data
migration shipped in the same revision.
If you narrow anything in a spec field, the same applies: find every stored value first, and migrate it in the same change.
Two invariants a migration must preserve
Idempotence. An explicitly-set value wins over a migrated one, so re-reading a spec the validator already migrated changes nothing. Both existing validators are written this way; keep it.
Refusal at publish, never at run time. An unknown capability id, an ungranted
scope, a tool_approval keyed on a tool that does not exist, an unrenderable tool
name, a secret_id of the wrong kind or from another organization, a personal MCP
connection — all refused while somebody is looking at a form. Validation added to the
runner instead is a broken agent in production rather than a red field in the Builder.
app/services/agent_registry.py owns publish validation. _tool_override_problems is
the shape to copy: collect every problem and report them together.
What the spec deliberately excludes
Anything about where it runs (surfaces, channels, exposures) and who may use it (owner, sharing). Those are deployment and access facts; keeping them out is what lets the same spec be exported, reviewed and reused across organizations.
It also carries no secret values — only secret_id references. A spec goes into a
client's git repository.
YAML
to_yaml keeps spec order rather than sorting, so a diff reflects what changed rather
than where it happens to sort, and UUIDs become strings so the file round-trips
through any reader. from_yaml raises ValueError on a non-mapping document, because
a list or a bare string reaches Pydantic as an unhelpful type error.
Round-trip is part of the contract: spec == AgentSpec.from_yaml(spec.to_yaml()).
Test
tests/test_agent_spec_and_factory.py. Every migration needs a test that loads a
verbatim old document — not one built from the current model, which cannot fail.
Plus the round-trip, the duplicate-capability refusal, and each publish refusal.
app/agents/** is held to 100%. See the backend-tests skill.
