Skip to main content
Two declarations carry an agent’s behavior. Capabilities state what it can do; policies state what must hold before it does. Both are business statements the runtime enforces — never prompts, never function schemas.

​
Capabilities

A capability is one thing the agent can do, in one folder: capabilities/<id>/capability.yaml.
The key difference from tool-calling: the author never writes the orchestration. The runtime routes to the capability on use_when, works out each fact in needs — from context, sources, derivations, or by asking the caller in that fact’s own words — and only then proposes the action. reads names the sources consulted; changes names what the action writes, and a changes capability takes a confirm read-back — an irreversible write without one refuses to build.

​
Policies: the gates

A policy is a gate: a condition that must hold before an action proceeds, and what to do when it doesn’t. Agent-wide policies live in policies/global.yaml; capability-scoped ones sit next to the capability.
  • requires fails closed — if the condition is unknown, the action does not proceed. forbids fails open. Choosing between them is choosing what happens when the world is uncertain.
  • applies_to names capabilities, or targets every write ({effect: writes}).
  • otherwise says what happens at the gate: refuse, must_say, offer, ask.
  • intent is the reason — it appears in the trace as the because of every enforcement.
Because a gate is a predicate over established facts, it cannot be talked around: gating on what a caller merely claims (a conversation fact) is itself a build error — ownership and identity gate on verified facts.

​
Obligations: the reply-level guardrails

Alongside gates, the policies files carry obligations — constraints on the reply itself: things the agent must never say or must always include (must, must_say), optionally scoped by when or by standing state. This is where the old notion of “guardrails” lives — as checked rules, not advisory prose.

​
Four surfaces, one question each

The engine separates refusal into four surfaces — most authoring confusion is putting a rule on the wrong one: Together with confirmation (explicit consent before an irreversible write, with an expiry — a question left hanging is not consent), these give every rule one home and every enforcement a readable trace.