Skip to main content
Context is the working material a model has on a turn. Keep the useful facts, make their source clear, and pass only what the next step needs. Store the smallest durable fact needed later: a tool result can be large, but the value you pass forward should be small. For the settings behind this guide, see How a turn is built, Memory and state, and Context size, compaction, and budgets.

Where to keep each value

Don’t store every utterance as a variable. Choose storage by lifetime, authority, visibility, and who needs the value.
  • READONLY: true stops every model in the project from writing the value. on_result, SET, and hooks still write it.
  • Declared session variables go into every model call in full, with no size cap. Keep them to IDs, flags, and short strings.
  • An agent with a BEHAVIOR role reads only the values it declares.
  • Row versions stay inside the workflow that checks them.
  • Never store card data, PINs, or passwords in memory.

What the prompt leaves out

Ground answers in knowledge bases

Put policy text that people ask about in many different words in a knowledge base with citations (Project → Resources → Knowledge Bases). The model chooses a knowledge base by its description, so make the description specific. Give the agent the sentence to say when the documents don’t cover a question. “Answer only from the documents” still let Voyager’s policy agent add general knowledge. Set max_search_tokens under compaction: in the agent’s copy of the search tool, so results stay small as the documents grow. Read the search call in the session’s traces, then run the same query in the knowledge base’s Search & Test. Add test questions the documents can’t answer. They catch invented answers. Search applies per-user document permissions only when the session carries the user’s verified identity with an email. Test restricted content with real user identities, because a Studio test chat has none. See Knowledge bases.

Keep model requests small

Each model call carries the system prompt, the conversation history, session memory, and the tool list. Large requests cost time and can crowd out relevant details. Send less first, and compact second:
  1. Select only the columns and rows the agent reads in each table tool’s query.
  2. Add model_context with FIELDS to the agent’s copy of a large workflow tool.
  3. Save the values later turns need with on_result: set.
  4. Give every agent a BEHAVIOR role, and set history on every handoff.
Set compaction once, in the compaction block of the project’s runtime configuration (config/runtime-config.json in an export). Studio’s Runtime Config page shows only the voice profile values. Before you diagnose forgetting, read the request at Project → Operate → Sessions → session → Traces → LLM step → Request. Search it for COMPACTED FOR CHAT HISTORY.
Fix the source before you tune compaction. If a needed value disappears, fix its storage or handoff. Raising every context limit adds cost and latency and leaves the missing-data path broken.

Compaction settings

When tools return large results and latency matters, set tool_results to strategy: structured to remove the summarizing call. An agent can override the project with EXECUTION: compaction:, but one policy per conversation is easier to diagnose.

Rules for model_context

Reduce time and cost

Model calls take most of a turn’s time and cost; tool calls usually take a small share. Read each turn’s calls, tokens, and cost at Project → Operate → Sessions → session → Performance. From Disruption, a delay under three hours needs no second model call:
ABL: result handling
Any other result goes back to the model. A respond: placed directly under on_result is dropped without a warning. Change one lever, rerun the evals, and keep it only if the scores hold. Never remove verification or a write confirmation for speed. Studio shows the Reasoning Pipeline’s Short Circuit on by default, and it skips the orchestrator’s reasoning. Turn it off unless every guarded route carries its check in WHEN. See Tuning for latency.

Parallel tool calls

Tools the model requests in one step run at the same time, so the wait is close to the slowest call. A tool that needs another tool’s result runs in a later step. For an upgrade question, Loyalty requests get_member and get_booking together. It then calls get_upgrade_offer with the flight_id that get_booking saved. An orchestrator asks the model for one tool call at a time unless Multi-Intent Recognition is on. Put parallel lookups in a specialist. In Chat with Agent → Debug → Traces, tools that ran together overlap.

Choose handoff, delegate, tool, or human review

Ask whether control should move, whether a short subtask should return, or whether the work stays within one operation. Don’t use a delegate for a child that needs to ask the user or suspend. Use a returning handoff for that. See Multi-agent orchestration.

Hand off between agents

A receiving agent needs to know why it was called, what has already been verified, what the user asked for, and which values it can trust. Make clear which agent asks the user, which one owns a write, and where control returns. Use this one-line format for the handoff summary:
Reason · verified facts · user goal · next decision · safety limit · unresolved question
For example: the traveler asks to change a disrupted flight; the booking reference matched and the status tool confirmed the delay; offer eligible flights without repeating identity checks; don’t change the booking until the caller confirms the named flight. Set history on every HANDOFF. Without it, the receiver gets the whole conversation. Pass verified values by name, and add a one-line summary. Use summary_only when the passed values carry the request, and a small last_n when you pass nothing. Add EXPECT_RETURN: true when control must come back. The default is false, so without it the transfer is permanent. Write the CONTEXT keys in lowercase; an uppercase PASS: isn’t read. From Concierge:
ABL: handoff
With EXPECT_RETURN: true, the specialist gets a tool to hand back. In its instructions, list the follow-ups it keeps. It hands back only when the user wants something else, and never in the same step as another tool call. Handoffs drawn on the Studio canvas start with auto. Voyager’s Booking and Travel Policy agents use last_n with a count of 4, because Concierge passes them little. Without an ON_RETURN map, values the receiver gathered come back under the same names. Map the values the sender needs, so a returned field can’t overwrite an unrelated one.

Hand off to an external agent

For an external A2A-capable agent, register it in the project’s External Agent Registry and use a remote handoff. The registry owns the endpoint and authentication; the ABL names the registered alias. A successful registry connection test doesn’t prove the live transfer, so test a real session with safe data. See External agent.
ABL: remote handoff

Handle several requests in one message

“My flight to Denver was cancelled. And how many bags can I check?” holds two requests. Turn on Multi-Intent Recognition (Project → Settings → Runtime Config) with the Primary queue strategy. The runtime handles the main request first, then offers the others. Leave the plan to the runtime. The orchestrator’s instructions shouldn’t try to answer both. A yes to a queued offer approves nothing else, so the write tool still asks for its own confirmation. See the how-to guide Handle multiple intents.

Context symptoms and fixes

Check the request size on short and long conversations, especially after tool calls and handoffs. Track selected memory, tool result size, history length, cuts, model calls, and latency.

Debug a missing value

  1. State the missing fact. Name the exact value or decision, not “the model forgot.”
  2. Find its source. Was it spoken, extracted, verified, returned by a tool, or inferred?
  3. Follow the value. Check where it was stored, whether it was visible, and whether the next agent received it.
  4. Read the request. Look for missing context, truncation, stale history, or a newer source that overrides it.
  5. Fix and prove. Add one scenario that fails without the value and passes with the intended context path.
When you read the request, check each part, then search for the markers the platform leaves where it cut something.

Record where a value came from

A value is safer to use when the agent can tell who supplied it, how it was checked, and whether it may have changed. Store provenance beside important context, especially values that control a route, an eligibility decision, or a write. Don’t turn uncertainty into certainty when you summarize. A handoff keeps “caller may prefer the 6:45 p.m. flight” apart from “caller confirmed the 6:45 p.m. flight.” The difference matters when a receiving agent can act on the value.

Retain user memory with care

Persistent memory is useful only when the benefit of reuse justifies keeping the information. Make the purpose, permitted fields, owner, retention period, and deletion path explicit. Follow your organization’s privacy and records rules for personal data. User memory needs an identified user: a verified user ID from your server on web chat, or the caller’s number on a call. Web and phone are separate users.
  • Don’t persist authentication secrets, payment credentials, or unnecessary personal details in model memory.
  • Read a preference from the system that owns it before you copy it into memory.
  • Reconfirm time-sensitive facts instead of trusting an old remembered value.
  • Let people correct a remembered preference, and define what the correction changes downstream.

Context and handoff checklist

  • Is the source of each value clear: user, verified system, or inference?
  • Are verified values stored with the right type and write protection?
  • Does every receiving agent declare the context it accepts?
  • Does the handoff say why it happened and what is still unresolved?
  • Are internal fields hidden from model context when they aren’t needed?
  • Are tool results projected to only the fields used for a decision or answer?
  • Have long sessions been checked for truncation or compacted values?
  • Can the receiver continue without making the person repeat known facts?
  • Can the agent tell an uncertain value from a confirmed choice?