agents.yaml declares agents as map entries keyed by id. The key is also the role name used
to fulfill required_agents.
Fields
string
The agent identifier (matches the map key).
string
The role this agent fulfills; matches the map key.
string
Provider-agnostic model alias:
cheap, regular, or frontier (resolved to a concrete model
per backend by llm.models). The older model_tier field is retired and rejected at boot.list
The events the agent receives. May be empty for coordinator roles.
list
The events the agent may emit. Each gets an auto-generated
emit_{event} tool. Defaults to
empty.object
A scripted stand-in for the model:
mock: {kind: python, module: mocks/assistant.py} (path
resolves from the bundle root, even for child-flow agents). Used when the platform runs
mock execution (swarm test, the mock backend); a real backend does not execute it. It does
not currently waive the boot credential check — see the testing page.boolean
false (default): a fresh conversation per task. true: one durable conversation per
(run, agent, flow instance) — requires the agent’s flow to have per-instance identity, and
fails at boot with a teaching error otherwise. Replaces the retired
conversation_mode/session_scope pair, which is rejected at load.string
Named workspace from
policy.yaml’s workspace_classes; controls the agent’s /workspace
scope. See Agent workspaces.string
The escalation and hierarchy parent. Not a messaging grant.
integer
Turn budget before the session is terminated.
list
Declared tools, resolved against the merged registry.
list
Platform permissions (see Permissions).
string
A named permission set from policy; explicit
permissions extend it.object
Which entity fields the agent’s generated
save_*/update_* tools may write, keyed by
entity type.object
Host capabilities (
bash, web_search, file_io), each a boolean. Default all false.list
Immutable reference files under the flow’s
data/ directory, read via read_flow_data.Example
agents.yaml