DELEGATE, HANDOFF, ESCALATE, COMPLETE) and the SUPERVISOR: declaration for top-level routing.
SUPERVISOR Declaration
A Supervisor is a top-level orchestrator that routes user messages to the appropriate child agent based on intent, context, and declarative rules. Supervisor documents use theSUPERVISOR: keyword instead of AGENT: and define agent references, routing rules, state schemas, policies, and communication settings.
Overview
While agents handle domain-specific tasks, the Supervisor decides which agent should handle each user message. It does not execute tools or gather information directly; it classifies intent and routes accordingly.Agent references
The Supervisor declares which agents are available for routing. Each reference includes a file path, an alias, and a list of capabilities.Syntax
Agent reference properties
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
REF | string | Yes | — | File path to the agent’s ABL definition. |
ALIAS | string | Yes | — | Local name used in routing rules and handoff targets. |
CAPABILITIES | string[] | Yes | — | List of capability tags describing what the agent can do. |
CHANNELS | string[] | No | — | Channels this agent supports (e.g., web, mobile, voice). |
REQUIRES_VALIDATION | boolean | No | false | Whether the user must be authenticated before routing to this agent. |
Routing rules
Routing rules define conditional logic for directing messages to agents. Rules are evaluated in priority order.Syntax
HANDOFF: block within a Supervisor, following the same syntax as agent handoffs:
Routing rule properties
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
NAME | string | Yes | — | Unique name for the routing rule. |
DESCRIPTION | string | No | — | Human-readable description. |
PRIORITY | number | Yes | — | Evaluation order. Lower values are evaluated first. |
WHEN | string | Yes | — | Condition expression that must be true for this rule to activate. |
THEN | RoutingAction | Yes | — | Action to take. See Routing actions. |
FLAGS | string[] | No | — | Behavioral flags. See Routing flags. |
CONSTRAINTS | object | No | — | Additional constraints on when this rule applies. |
Routing actions
| Action | Syntax | Description |
|---|---|---|
| Route to agent | ROUTE_TO Agent_Name | Send the message to a specific agent. |
| Route to user | ROUTE_TO_USER "message" | Send a message and wait for user input. |
| Route by variable | ROUTE_TO_VARIABLE var_name | Route to the agent named in a variable. |
| Intent-based routing | INTENT_MATCH | Route based on detected intent. See below. |
| End conversation | END_CONVERSATION | End the session. |
| System action | SYSTEM_ACTION action_name | Execute a system-level action (e.g., handoff). |
Intent-based routing
For more granular routing, useINTENT_MATCH with intent-to-agent mappings:
Routing flags
| Flag | Effect |
|---|---|
set_active | Mark the target agent as the active agent for subsequent messages. |
silent | Route without sending a user-visible message. |
no_log | Do not log this routing decision in the trace store. |
priority_boost | Apply a priority boost in the target agent’s queue. |
Conditional routing (WHEN clauses)
WHEN clauses use the same expression syntax as Expressions & functions. Common patterns include:Routing constraint blocks
Add constraints to limit when a rule applies beyond the WHEN condition:| Constraint | Type | Description |
|---|---|---|
ignoreIntents | string[] | Intents that should not trigger this rule. |
channels | string[] | Channels where this rule applies (e.g., [web, voice]). |
requiresState | string[] | State variables that must be set for this rule to activate. |
State schema
The Supervisor can declare a state schema that defines typed variables organized by namespace.State variable properties
| Property | Type | Required | Default | Description | | ------------- | -------------------------------------------- | -------- | ------- | ---------------------------------------------------- | --- | --- | ----------------------------- | |type | See Data types | Yes | — | Variable type. |
| required | boolean | No | false | Whether the variable must have a value. |
| default | any | No | — | Default value. |
| description | string | No | — | Human-readable description. |
| source | system | user | agent | computed | No | — | Origin of the variable value. |
| updatedBy | string[] | No | — | List of agent aliases that can update this variable. |
Policies
Policies define high-level behavioral rules for the Supervisor, constraining what it is allowed and forbidden to do.Policy properties
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
NAME | string | Yes | — | Unique policy name. |
DESCRIPTION | string | No | — | Human-readable description. |
RULES | object | Yes | — | Policy rule definitions. See below. |
Policy rule properties
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
allowedWhen | string | No | — | Condition under which the action is allowed. |
forbiddenWhen | string | No | — | Condition under which the action is forbidden. |
triggerSignal | string | No | — | Signal to emit when the policy is triggered. |
behavior | string | No | — | Description of the expected behavior when triggered. |
Communication settings
Communication settings define the Supervisor’s language, tone, and vocabulary preferences.Communication properties
| Property | Type | Required | Default | Description | | ------------- | ---------- | ---------- | --------- | ----------------------------------------- | --- | ------------------- | |language | string | Yes | — | Primary language code (e.g., en, es). |
| formality | formal | informal | neutral | Yes | — | Communication tone. |
| pronouns | object | No | — | Pronoun preferences (use and avoid). |
| vocabulary | object | No | — | Preferred and avoided vocabulary. |
| constraints | string[] | Yes | — | Communication behavioral constraints. |
Behavior settings
TheBEHAVIOR block defines whether the Supervisor can respond directly to users or must always route to an agent.
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
canRespondDirectly | boolean | Yes | — | Whether the Supervisor can send messages directly to users. |
allowedDirectActions | string[] | No | [] | Actions the Supervisor can perform directly. |
forbiddenActions | string[] | No | [] | Actions the Supervisor must never perform. |
HANDOFF
HANDOFF transfers conversational control from the current agent to another agent, passing context and optionally expecting a return.Syntax
Properties
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
TO | string | Yes | — | Target agent name. |
WHEN | string | Yes | — | Condition that triggers the handoff. |
PRIORITY | number | No | — | Evaluation priority. Lower values are evaluated first when multiple handoff rules match. |
CONTEXT | object | Yes | — | Context to pass to the target agent. See Context. |
RETURN | boolean | Yes | — | Whether control should return to this agent after the target completes. |
ON_RETURN | string | No | — | Instruction for handling the return (e.g., step to resume at). |
MAP | Record<string,string> | No | — | Return value mapping. Keys are target agent result fields; values are parent variable names. |
REMOTE | object | No | — | Remote agent configuration. Same structure as DELEGATE remote. |
ASYNC | boolean | No | false | Use async dispatch with push notifications for remote agents. |
ASYNC_TIMEOUT | number | No | — | Timeout in seconds for async handoff. |
Handoff context
TheCONTEXT block defines what information the target agent receives.
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
pass | string[] | Yes | — | Session variable names to include in the handoff context. |
summary | string | Yes | — | Human-readable summary of why the handoff is occurring. Supports {{}} interpolation. |
history | string | No | — | Conversation history strategy. See History strategies. |
grant_memory | string[] | No | — | Persistent memory paths to grant the target agent access to. |
History strategies
Thehistory property controls how much conversation history the target agent receives.
| Value | Behavior |
|---|---|
none | No conversation history is passed. |
summary_only | Only the summary text is passed, no raw messages. |
full | The complete conversation history is passed. |
last_N | The last N messages are passed. Specify as last_n: 10. |
Return expectations
WhenRETURN: true, the calling agent pauses and waits for the target agent to complete. Upon return:
- The
MAPblock (if present) writes the target’s result fields into the parent’s session variables. - The
ON_RETURNinstruction guides what happens next (e.g., resume a step, re-evaluate conditions).
RETURN: false, the handoff is a one-way transfer. The calling agent’s session ends.
Async dispatch
For remote agents, setASYNC: true to dispatch the handoff asynchronously. The calling agent receives a notification when the remote agent completes rather than blocking.
Memory grants
Usegrant_memory to give the target agent access to specific persistent memory paths. Without this, the target agent cannot read or write the parent’s persistent variables.
DELEGATE
DELEGATE invokes a sub-agent synchronously, waits for it to complete, and maps the result back into the calling agent’s context. The sub-agent runs in its own scope and does not have direct access to the parent’s session variables.Syntax
Properties
| Property | Type | Required | Default | Description | | ----------------- | ----------------------- | -------- | ------- | ------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | |AGENT | string | Yes | — | Name of the sub-agent to invoke. |
| WHEN | string | Yes | — | Condition that must be true for delegation to occur. |
| PURPOSE | string | Yes | — | Description of why this delegation exists. Included in trace events. |
| INPUT | Record<string,string> | Yes | — | Input mapping. Keys are sub-agent parameter names; values are expressions from the parent’s context. |
| RETURNS | Record<string,string> | Yes | — | Output mapping. Keys are sub-agent result fields; values are parent context variable names to write to. |
| USE_RESULT | string | Yes | — | Instructions for interpreting the sub-agent’s result. |
| TIMEOUT | string | No | — | Maximum time to wait for the sub-agent. Format: "Ns" (seconds). |
| ON_FAIL | string | object | No | — | Action when the sub-agent fails or times out. See Failure strategies. |
| FAILURE_MESSAGE | string | No | — | Message to display when delegation fails. |
Input/output mapping
TheINPUT block maps values from the parent agent’s session context into the sub-agent’s input parameters:
RETURNS block maps the sub-agent’s result fields back into the parent’s session variables:
Delegate failure strategies
| Value | Behavior |
|---|---|
respond | Send a message and continue. Requires FAILURE_MESSAGE. |
continue | Silently continue without the sub-agent’s result. |
escalate | Trigger human escalation. |
retry | Retry the delegation. Accepts a count for max retries. |
Remote agent support
DELEGATE supports invoking agents running on remote services. Add aREMOTE block to configure the connection.
Remote properties
| Property | Type | Required | Default | Description | | ---------- | -------- | -------- | ------- | ------------------------------------- | ---------------------------------------------------------------------- | |location | local | remote | No | local | Whether the agent is co-located or remote. |
| endpoint | string | No | — | URL for remote agent invocation. |
| protocol | a2a | rest | No | — | Communication protocol. a2a for Agent-to-Agent, rest for REST API. |
| auth | object | No | — | Authentication configuration. |
| timeout | string | No | — | Override timeout for the remote call. |
FAN_OUT
FAN_OUT executes multiple delegate calls in parallel and collects their results. This is useful when several independent sub-agents need to process data simultaneously.ESCALATE
ESCALATE transfers the conversation to a human operator. It is designed for situations where the agent cannot or should not continue autonomously.Syntax
Trigger properties
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
WHEN | string | Yes | — | Condition that triggers escalation. |
REASON | string | Yes | — | Human-readable reason for the escalation. |
PRIORITY | string | Yes | — | Priority level: low, medium, high, or critical. |
TAGS | string[] | No | — | Tags for routing and categorization in the human agent queue. |
Priority levels
| Level | Use case |
|---|---|
low | Non-urgent requests (e.g., general feedback). |
medium | Standard requests (e.g., customer asks to speak with a human). |
high | Urgent issues (e.g., service outages, repeated failures). |
critical | Immediate attention required (e.g., compliance violations, fraud). |
Context for human
Thecontext_for_human block lists session variable names to include in the escalation package. The human agent sees these values in their interface.
Routing configuration
Therouting block controls how the escalation is routed in the human agent system.
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
queue | string | No | — | Target queue name in the human agent system. |
skill_tags | string[] | No | — | Required skills for the human agent. |
priority_boost | number | No | — | Additional priority boost applied to the queue entry. |
Post-completion actions
Theon_human_complete block defines what happens after the human agent finishes.
condition and an action. The action can be COMPLETE (end the conversation), HANDOFF (transfer to another agent), or CONTINUE (resume the current agent).
COMPLETE
COMPLETE defines the conditions under which the agent considers its task finished. Each completion condition specifies aWHEN expression and an optional response.
Syntax
Properties
| Property | Type | Required | Default | Description |
|---|---|---|---|---|
WHEN | string | Yes | — | Condition expression. The agent completes when this evaluates to true. |
RESPOND | string | No | — | Final message to the user. Supports {{}} template interpolation. |
STORE | string | No | — | Collection or path name to store the completion result for analytics. |
Rich content in completion
COMPLETE responses support voice configuration and rich content, the same as any RESPOND:Completion evaluation
Completion conditions are evaluated after every turn, in declaration order. The first matching condition triggers completion. If no condition matches, the agent continues the conversation.Context Passing
Evaluation order across constructs
When multiple multi-agent constructs apply on the same turn, the runtime evaluates them in this order:- ESCALATE triggers — checked first; critical safety and compliance.
- HANDOFF rules — evaluated by priority (lower first).
- DELEGATE conditions — evaluated in declaration order.
- COMPLETE conditions — checked last.
Complete Supervisor example
Related pages
- NLU — intent classification that drives routing decisions
- Memory & Constraints — session and persistent state used in routing conditions
- Expressions & functions — condition syntax for WHEN clauses
- Lifecycle & hooks — ON_START and hooks that interact with multi-agent flows
- Rich Content & Expressions — formatting for RESPOND and COMPLETE messages