# 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

```mermaid
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**

1. Give the section a **Name**. The name is the title the agent sees in the map
   (*Rescheduling a booking*).
2. Choose a **Category**, and the **Agent Type** the section applies to (or
   **All**).
3. Under **Kind**, choose **Section (a situation)**.
4. Enter a **Path**: lower-case words and dashes, folders with a slash —
   `booking/reschedule`. One section per path.
5. 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.
6. 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.
7. 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.
8. **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**

1. 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.
2. **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*.
3. 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.
4. **What the prompt will carry** shows the sentence the settings produce and a
   preview of the map exactly as the prompt will carry it.
5. **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.

## Related

- [Tools, Knowledge and Memory](/help/voice-agents/tools-and-knowledge) — the
  voice agent's Tools tab, where `read_instructions` is ticked.
- [Brain Browser Walkthrough](/help/knowledge/overview) — where the facts go.