| # Agent Manifest Contract |
|
|
| The manifest is the third stable contract — the declarative description of one |
| agent. Defined by `AgentManifest` (`src/core/manifest.py`), loaded from |
| `config/agents/<name>.yaml`, validated by `validate_agent()`. Adding an agent is |
| dropping in a manifest; no engine edit. |
|
|
| ## Schema |
|
|
| ```yaml |
| name: scene-whisperer # unique slug == actor on emitted events (required) |
| role: worker # worker | judge | observer | reflector |
| persona: > # IDENTITY block, injected verbatim every prompt (required) |
| You are the Seedkeeper ... describe how the wood changed in one sentence. |
| handler: null # optional behaviour binding (see below) |
| |
| # Communication contract |
| subscribes_to: # event kinds that trigger this agent (reactive) |
| - user.injected |
| may_emit: # event kinds this agent is allowed to emit (authority) |
| - world.observed |
| - agent.reflected |
| |
| # Scheduling |
| schedule: |
| tick_every: 1 # also fire every N turns (null = event-driven only; 0 = every turn) |
| max_consecutive: 3 # documented cap (enforcement deferred) |
| |
| # Model (resolved to a concrete small model by the ModelRouter) |
| model_profile: fast # tiny ≤4B | fast ≤7B | balanced ≤13B | strong ≤32B |
| model_endpoint: null # optional: pin ONE specific catalogue model (modal/catalogue.py |
| # endpoint slug, e.g. minicpm-4-1-8b), overriding the tier above |
| |
| # Memory (a view over the ledger, not separate state) |
| memory: |
| window: 6 # recent visible events in the prompt |
| use_salience: false # rank by relevance×recency×importance instead of pure recency |
| salience_top_k: 8 |
| reflection_threshold: null # emit agent.reflected every N visible events (null = off) |
| |
| # Capability grants |
| tools: [] # tool names the ToolRegistry will allow this agent to call |
| |
| # Output shaping |
| output_extra_fields: [] # extra payload fields the model is asked for, e.g. ["emotion"] |
| ``` |
|
|
| ## Field notes |
|
|
| - **`may_emit`** is the safety boundary. An agent's structured output is coerced |
| to one of these kinds; `agent.reflected` is permitted implicitly when reflection |
| is enabled. |
| - **`subscribes_to` vs `schedule.tick_every`** are orthogonal — an agent may be |
| reactive, periodic, or both. Cadence is per-agent; scenarios don't schedule. |
| - **`model_profile`** never names a model; the router (config/env) does. Mix |
| tiers freely across a cast. |
| - **`model_endpoint`** is the escape hatch from tiers to a *specific* served model: |
| a `modal/catalogue.py` endpoint slug the router resolves to that model's live |
| binding (overriding `model_profile`). `null` → route by tier. This is how a cast |
| pins concrete sponsor models — one mind on MiniCPM, the Judge on Nemotron — and what |
| the Fishbowl Lab's per-cast model picker writes. Offline it folds into the |
| deterministic stub like any tier, so demos stay reproducible. See ADR-0022. |
| - **`handler`** stays `null` for the common case (the generic `ManifestAgent`). |
| Set it to a key registered via `@register_handler` for agents that call tools or |
| need custom prompt logic; the YAML still supplies all declarative fields. |
| - **`output_extra_fields`** entries are required strings, except the well-known |
| typed names `winner` and `scores` (optional, engine-typed — ADR-0029). A judge in |
| a competition scenario lists them to make its verdict machine-readable; see |
| [structured-output.md](../architecture/structured-output.md#well-known-typed-fields). |
| - **`memory.*`** layers are pure views over the ledger — see |
| [memory-stack.md](../architecture/memory-stack.md). |
| |
| See also: [manifest-spec.md](../architecture/manifest-spec.md) (detailed guide), |
| [scenario-config.md](scenario-config.md), [world-config.md](world-config.md). |
| |
