Glossaries & macros

Glossaries inject domain vocabulary into every turn; macros are reusable text blocks interpolated into routine chat nodes via ${macro-id}.

Context — Two small content types complete the configuration model: glossaries (domain vocabulary the agent must understand) and macros (reusable text blocks for routine chat nodes). Both live in the platform's versioned catalog, like policies and routines.

YAML examples follow manifest schema 6.1.5. Manifest and content shapes are schema-versioned and differ across runtime versions — see Versioning & compatibility.

Glossaries

A glossary defines domain-specific terms so the agent interprets customer language correctly and uses your vocabulary in replies:

terms:
  self-exclusion:
    name: Self-exclusion
    description: >
      A voluntary account lock a customer chooses to restrict their own
      access for a fixed period. Distinct from a company-imposed
      suspension.
    synonyms:
      - self-ban
      - cooling-off lock
  one-way-rental:
    name: One-way rental
    description: >
      A rental where the drop-off location differs from the pickup
      location. Incurs a flat 50 EUR fee at DriveAway.

Entry fields

Field	Type	Required	Default	Meaning
terms	map of term-key → entry	yes (≥ 1 entry)	—	The glossary body. Keys are stable identifiers.
terms.<key>.name	string	yes	—	The term as written.
terms.<key>.description	string	yes (non-empty)	—	The definition the agent works from.
terms.<key>.synonyms	list of strings	no	—	Alternative phrasings customers use.
id	string	no	—	Optional stable identifier for the set.

Behaviour

• Glossaries are referenced from the manifest and merged: all terms from all referenced glossaries are combined into one term store at boot.

  agent_config:
    context:
      glossaries:
        - id: rental-terms
          version: 2

• Each turn, the engine injects only the terms most relevant to the conversation — a semantic-similarity retrieval capped at 20 terms — not the entire merged glossary. A glossary set larger than 20 terms never injects all of them into a single turn's context.

• Terms influence both understanding (a customer saying "self-ban" is recognised as self-exclusion) and production (the agent uses your preferred names).

• The trace snapshot is built once at config-apply/boot and records which glossary sets are pinned (id, version, description, term keys) — it shows which glossaries are configured, not the per-turn retrieved subset or the full term definitions.

• Retrieved terms cost prompt space on every turn, and a larger merged glossary competes for the same 20-term retrieval budget. Keep glossaries to vocabulary that is genuinely ambiguous or business-specific. Product catalog data belongs in tools or the knowledge base, not the glossary.

Macros

A macro is one reusable block of message text:

text: >
  Free cancellation applies up to 24 hours before pickup — you get a full
  refund. Within 24 hours of pickup, one day's rental rate is
  non-refundable and the remainder is returned to your original payment
  method within five business days.

Field	Type	Required	Default	Meaning
text	string	yes (non-empty)	—	The macro body injected at the call site.
id	string	no	—	Optional stable identifier.

Declaring macros in the manifest

Macros are pinned in the manifest's catalog, alongside routines, policies, and glossaries:

agent_config:
  context:
    macros:
      - id: cancellation-policy
        version: 3
      - id: handoff-followup
        version: 1

Using a macro: ${macro-id} interpolation in chat_state

A chat node interpolates a macro inline — the token is replaced by the macro's text body at the pinned version when the routine is compiled:

  - id: explain-cancellation
    chat_state: |
      Here's how cancellation works for your booking:

      ${cancellation-policy}

      Would you like me to go ahead and cancel it?
    transitions:
      - to: await-decision

Rules:

• Only chat_state interpolates. tool_instruction, think, and description take literal text — a ${…} there is not expanded.

• Macro ids must match [a-zA-Z][a-zA-Z0-9_-]*; a malformed token is rejected at validation time.

• Every interpolated id must be pinned in context.macros; an unresolved reference fails the boot.

When to use a macro vs. repeating chat_state

Use a macro when the same carefully-worded explanation appears at several points (across nodes or across routines) and must stay consistent — regulatory wording, fee explanations, escalation scripts. For one-off instructions, plain chat_state is simpler and keeps the routine self-contained.

See also

• Routines — where macros plug in

• Prompts, language & preamble — the other text-shaping levers

• Manifest & content schemas — reference syntax