Defining agents and prompts

An agent is an LLM worker that reacts to events. When an event reaches its inbox, the platform loads the agent’s prompt and tools; the agent reasons and calls tools; and it emits events. It never writes entity state directly: it emits, and a system node decides what to persist.

The agent contract

An agent is declared as a map entry in agents.yaml. The key is the agent’s id (its address) and, by default, the role name it fulfills (used to resolve prompts/<role>.md and to match required_agents in schema.yaml), so you usually do not write id: or role: inside the entry.

resolver-agent:                       # map key = agent id = role (the default)
  model: regular
  permissions_bundle: worker
  manager_fallback: support-coordinator
  subscriptions: [ticket.assigned]
  emit_events: [ticket.resolved, ticket.escalated]
  memory: true
  max_turns_per_task: 10
  entity_writes:
    ticket:
      save: [resolution]

Field	Purpose
`model`	Provider-agnostic model alias: `cheap`, `regular`, or `frontier`. Resolved per backend by `llm.models`.
`subscriptions`	The events the agent receives.
`emit_events`	The events it may emit (each gets an auto-generated `emit_*` tool).
`memory`	`false` (default): a fresh conversation each task. `true`: one durable conversation per flow instance.
`permissions_bundle`	A named permission set from `policy.yaml`; combined with any inline `permissions`. See Tools.
`manager_fallback`	Which agent this one escalates to. Setting it does not by itself let the two message each other — that comes from permissions.
`entity_writes`	Narrow, explicitly granted exceptions to the emit-only rule: the fields the agent’s generated `save_`/`update_` tools may write. Anything not listed still goes through an event.
`max_turns_per_task`	Turn budget before the session is terminated.
`type`	Optional classification label (defaults to `generic`); used to tag agents, for example by division. Does not change tool or permission gating.
`role`	Optional override; defaults to the map key. Set it when the prompt file is named differently from the id, so the runtime loads `prompts/<role>.md` instead of `prompts/<map-key>.md`.

Memory scope is derived from the flow’s instance model — one conversation per flow instance, so in a mode: template flow that means one per instance/entity. memory: true on a flow with no per-instance identity (a plain root flow) fails at boot with an error explaining why: there is no flow-instance owner to scope the conversation to.

What an agent can call

You list only declared tools in tools. Beyond those, every agent automatically gets:

Universal tools: agent_message, mailbox_send.
Emit tools: emit_{event_name} for each entry in emit_events.
Role-scoped entity tools: read_*, save_*, update_*, generated from the entity contract and entity_writes.
read_flow_data: generated only when a flow-scoped agent declares flow_data_access, to read deploy-time reference files shipped with the flow.

Host capabilities (bash, web_search, file_io) are gated separately by the native_tools field, a channel independent of tools and permissions. See Tools.

Prompts

Each agent has a markdown prompt at prompts/{agent-id}.md. Prompts use {{variable}} placeholders, substituted at session creation from four sources, in priority order:

Instance variables
Policy values
Entity-state fields
A small runtime-token allowlist (current_date, agent_id, flow_instance_path)

Substitution is plain string replacement with no logic, and a variable that resolves nowhere is left as-is.

# Resolver

You resolve assigned support tickets using the ticket body and your judgment.

- If confident, save the resolution and emit `ticket.resolved`.
- If the issue needs account access or a human, emit `ticket.escalated` with a reason.

SLA: {{sla_hours}} hours.

The platform appends a short environment postamble (the workspace mount paths) to every prompt. It does not list tools; the model sees those through the tool definitions.

Keeping reviewers independent

To stop two agents from sharing context, give a role two pools — separate agent entries for the same role with different subscriptions — and route originals to one and appeals to the other. Same prompt, separate sessions, no shared context.

reviewer-first-pass:
  role: reviewer
  subscriptions: [review.requested]
reviewer-appeals:
  role: reviewer
  subscriptions: [review.appealed]

The older model_tier and conversation_mode/session_scope fields are retired; model and memory replace them.

Getting started

Core concepts

Build a flow

Handlers

Patterns

Operating Swarm

Defining agents and prompts

The agent contract

What an agent can call

Prompts

Keeping reviewers independent

​The agent contract

​What an agent can call

​Prompts

​Keeping reviewers independent

The agent contract

What an agent can call

Prompts

Keeping reviewers independent