Skip to main content
vocabulary.yaml declares the agent’s typed vocabulary: facts (values the agent can know) and records (things it can hold instances of). Everything the agent decides is downstream of these — capabilities name the facts they need, policies gate on them, derivations compute them, and replies read them back.

​
Facts

A fact is one typed value with a meaning:
known_from is the seam between language and state. It declares whether a value arrives from the host at session open (given), is said by the caller (conversation), is fetched from a system (source), or is computed from other facts (derived). Once a value is established, everything downstream of it — gates, arithmetic, branching — is deterministic. Facts can also carry a shape check (looks_like), sensitivity flags (sensitive, public: false), and asking behavior (never_ask, once).

​
Records

A record is a thing the agent holds instances of — an order, a claim, a booking — with a key, fields, and optionally a lifecycle:
The record’s fields are simply the facts scoped to it (order.id, order.total, …). The state machine — states and transitions — makes lifecycle rules enforceable: a transition that isn’t declared can’t happen. A record holding several rows at once (search results, a cart) is a collection.

​
How the vocabulary is used

  • Capabilities list the facts they need — the runtime establishes each one from its known_from, asking the caller only with that fact’s ask_as.
  • Policies gate on facts and record state: requires: order.status is "delivered".
  • Derivations compute new facts from existing ones — thresholds, eligibility, totals.
  • Replies read facts back to the caller using their means, so the agent describes values the way the business does.
Declare a noun once, and every capability, gate, and reply speaks the same language.