> For the complete documentation index, see [llms.txt](https://docs.interactive.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.interactive.ai/agents/concepts/glossaries-and-macros.md). # Glossaries & macros > **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](/agents/concepts/policies.md) and [routines](/agents/concepts/routines.md). > > YAML examples follow **manifest schema 6.1.1**. Manifest and content shapes are schema-versioned and differ across runtime versions — see [Versioning & compatibility](/agents/operations/versioning.md). ## Glossaries A glossary defines domain-specific terms so the agent interprets customer language correctly and uses your vocabulary in replies: ```yaml 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 | Meaning | | ------------------------- | ----------------------- | --------------- | ----------------------------------------------- | | `terms` | map of term-key → entry | yes (≥ 1 entry) | The glossary body. Keys are stable identifiers. | | `terms..name` | string | yes | The term as written. | | `terms..description` | string | yes (non-empty) | The definition the agent works from. | | `terms..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 injected into the agent's context on every turn. ```yaml agent_config: context: glossaries: - id: rental-terms version: 2 ``` * Terms influence both understanding (a customer saying "self-ban" is recognised as self-exclusion) and production (the agent uses your preferred names). * Glossary content is part of the trace snapshot, so traces show exactly which definitions were active when a turn ran. * Because every term costs prompt space on every turn, keep glossaries to vocabulary that is genuinely ambiguous or business-specific. Product catalog data belongs in [tools](/agents/concepts/tools.md) or the [knowledge base](/agents/concepts/knowledge-base.md), not the glossary. ## Macros A macro is one reusable block of message text: ```yaml 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 | 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: ```yaml 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: ```yaml - 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](/agents/concepts/routines.md) — where macros plug in * [Prompts, language & preamble](/agents/concepts/prompts.md) — the other text-shaping levers * [Manifest & content schemas](/agents/reference/manifest.md) — reference syntax --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.interactive.ai/agents/concepts/glossaries-and-macros.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.