Situations — instructions read on demand

Split a long agent prompt into sections for specific situations, list them in a short map, and let the agent read one only when the conversation enters it.

Situations — instructions your agent reads when it needs them

A long prompt carries every situation your business ever wrote down, and every call and chat pays for all of it on every turn. A situation is a section of that prompt for one moment in a conversation: a caller who wants to reschedule, a request after hours, someone asking for a person. The agent's instructions keep a short map of these sections — a path, a title, and the words people use — and the agent reads a section with the read_instructions tool when the conversation enters that situation. Sections marked always are written into the prompt as before.

The Tenant Brain answers what is true about your business; a situation says how this agent acts now. Facts belong in the brain, where every agent can read them and a person publishes them; a situation is written in the imperative — if…, ask…, offer…, never…

What you'll need

A tenant admin login to write sections at Settings (the gear icon) → Agents & AI → Prompt Components.
The agent type's manage permission (for example agents:voice:manage) to pick sections on an agent's Situations tab.
A voice, chat, SMS or task agent. Mail and document agents have no read tool, so they have no Situations tab.

How it fits together

flowchart LR
    A["Prompt Components<br/>kind: Section<br/>path · when · mode"] -->|push live| B["Agent's Situations tab<br/>pick the sections"]
    B --> C["Compiled prompt<br/>always sections written in<br/>+ a map of the rest"]
    C -->|conversation enters a situation| D["read_instructions<br/>returns the section once;<br/>later a reference"]

Write a section

Settings (the gear icon) → Agents & AI → Prompt Components → New Component

Give the section a Name. The name is the title the agent sees in the map (Rescheduling a booking).
Choose a Category, and the Agent Type the section applies to (or All).
Under Kind, choose Section (a situation).
Enter a Path: lower-case words and dashes, folders with a slash — booking/reschedule. One section per path.
Choose a Mode:
- Read on demand (listed in the map) — the usual choice. The agent reads the section when the situation arises.
- Always in the prompt — written into every conversation, like a component.
For a section read on demand, fill When people say… with the words a caller or customer uses when this situation arises, comma-separated (up to twelve): move my appointment, reschedule, another day. They go into the map, so the agent knows when to read.
Write the Content: what the agent does in this situation, in the imperative. Keep it under about 3,000 characters; a section longer than 8,000 is refused.
Save Component, then Push to Live. An agent only sees live sections.

After a save the page may show a lint note. The notes are advice, not errors: section-long when a section would read better split; reads as knowledge when most lines are facts about the business (prices, hours, what you are), which belong in the Tenant Brain; no instructions when no line tells the agent what to do. The notes also appear in the component's row and in its editor until the content changes.

Give an agent its sections

Agents → Agent Types → (the type) → open the agent → Situations tab

Under Your sections, tick the sections this agent should have. Each row shows the path, whether it is Always in the prompt or Read on demand, and the words people say.
Platform sections are written by the platform for every workspace and marked Platform; tick the optional ones you want. Platform sections in the System category reach every agent of the type without being listed, and appear in the map marked platform.
If read_instructions is not ticked on the agent's Tools tab, the tab says so and offers Enable read_instructions (and list_instructions). Without the tool every selected section is written into the prompt in full — nothing is lost, but nothing is saved either.
What the prompt will carry shows the sentence the settings produce and a preview of the map exactly as the prompt will carry it.
Save Changes, then promote when you are ready.

Budgets

Two numbers size the mechanism for this agent; both follow a platform default until you set them.

Setting	Default	Range	What it does
Map budget (characters)	6,000	1,000–20,000	How much of the map the prompt may carry. The map keeps whole lines in path order; past the budget it ends with one line saying how many more there are, and the agent can list them with `list_instructions`.
Read budget (characters)	8,000	1,000–20,000	What one `read_instructions` call may return. The first section is trimmed before a second one is dropped.

Voice and SMS agents pay for every character in time before the first word, so the defaults or lower suit them; a task agent can take more.

What happens during a conversation

The agent reads a section once. If the same situation arises again later in the conversation, the tool returns a reference — already provided earlier in this conversation; those instructions apply again here — instead of the text. If the section changed since, the agent gets the current text and a note saying so.
On a call the agent never reads a path or a title aloud; in chat it never shows one. Paths and titles are for the agent.
A section an agent read appears in Instructions used on the conversation, beside the knowledge it used, with its version and time.

Troubleshooting

The section is not on the Situations tab. It is not pushed live, it is inactive, or its Agent Type does not include this agent's type (or All). Check the component's row for Live vN.
The agent followed the section without reading it. Its mode is Always in the prompt, or the agent has no read_instructions tool, so the section was written in full. Both are shown on the Situations tab.
Two sections use the same path. The save refuses it: one section per path. If a platform section uses a path you also use, your section wins for your agents.

Tools, Knowledge and Memory — the voice agent's Tools tab, where read_instructions is ticked.
Brain Browser Walkthrough — where the facts go.