Skip to main content

Documentation Index

Fetch the complete documentation index at: https://koreai-v2-home-nav.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

This page documents multi-agent orchestration constructs (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 the SUPERVISOR: 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.
SUPERVISOR: Travel_Supervisor
VERSION: "2.0"
DESCRIPTION: "Routes customers to booking, support, or sales specialists"
GOAL: "Route requests to the right specialist with full context preservation"

PERSONA: |
  Professional travel booking assistant. Friendly, efficient, and helpful.
  Routes requests quickly and transparently.

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

AGENTS:
  - REF: ./agents/flight_search.agent.abl
    ALIAS: Flight_Search
    CAPABILITIES: [flight_booking, fare_search, seat_selection]
    CHANNELS: [web, mobile, voice]
    REQUIRES_VALIDATION: false

  - REF: ./agents/support.agent.abl
    ALIAS: Support_Agent
    CAPABILITIES: [booking_management, cancellation, refund]
    REQUIRES_VALIDATION: true

Agent reference properties

PropertyTypeRequiredDefaultDescription
REFstringYesFile path to the agent’s ABL definition.
ALIASstringYesLocal name used in routing rules and handoff targets.
CAPABILITIESstring[]YesList of capability tags describing what the agent can do.
CHANNELSstring[]NoChannels this agent supports (e.g., web, mobile, voice).
REQUIRES_VALIDATIONbooleanNofalseWhether 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

ROUTING:
  - NAME: escalation_route
    DESCRIPTION: "Route frustrated or explicitly requesting human"
    PRIORITY: 1
    WHEN: intent.category == "escalation" OR user.frustration_detected == true
    THEN: ROUTE_TO Live_Agent_Transfer
    FLAGS: [set_active]

  - NAME: booking_route
    PRIORITY: 5
    WHEN: intent.category == "new_booking"
    THEN: ROUTE_TO Sales_Agent
Alternatively, routing can be declared using the HANDOFF: block within a Supervisor, following the same syntax as agent handoffs:
HANDOFF:
  - TO: Sales_Agent
    WHEN: intent.category == "new_booking"
    CONTEXT:
      pass: [search_context, user_preferences, budget]
      summary: "User looking to book new travel"
    RETURN: false

Routing rule properties

PropertyTypeRequiredDefaultDescription
NAMEstringYesUnique name for the routing rule.
DESCRIPTIONstringNoHuman-readable description.
PRIORITYnumberYesEvaluation order. Lower values are evaluated first.
WHENstringYesCondition expression that must be true for this rule to activate.
THENRoutingActionYesAction to take. See Routing actions.
FLAGSstring[]NoBehavioral flags. See Routing flags.
CONSTRAINTSobjectNoAdditional constraints on when this rule applies.

Routing actions

ActionSyntaxDescription
Route to agentROUTE_TO Agent_NameSend the message to a specific agent.
Route to userROUTE_TO_USER "message"Send a message and wait for user input.
Route by variableROUTE_TO_VARIABLE var_nameRoute to the agent named in a variable.
Intent-based routingINTENT_MATCHRoute based on detected intent. See below.
End conversationEND_CONVERSATIONEnd the session.
System actionSYSTEM_ACTION action_nameExecute a system-level action (e.g., handoff).

Intent-based routing

For more granular routing, use INTENT_MATCH with intent-to-agent mappings:
ROUTING:
  - NAME: intent_router
    PRIORITY: 10
    WHEN: true
    THEN:
      INTENT_MATCH:
        - INTENTS: [flight_search, hotel_search]
          ACTION: ROUTE_TO Sales_Agent
        - INTENTS: [manage_booking, cancel_booking]
          ACTION: ROUTE_TO Support_Agent
        FALLBACK: ROUTE_TO Fallback_Handler

Routing flags

FlagEffect
set_activeMark the target agent as the active agent for subsequent messages.
silentRoute without sending a user-visible message.
no_logDo not log this routing decision in the trace store.
priority_boostApply 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:
# Intent-based
WHEN: intent.category == "complaint"

# State-based
WHEN: user.is_authenticated == true AND intent.category == "manage_booking"

# Negation
WHEN: NOT intent.has_specific_request

# Compound
WHEN: intent.unclear == true OR intent.confidence < 0.5

# Variable check
WHEN: handoff_count >= 4

Routing constraint blocks

Add constraints to limit when a rule applies beyond the WHEN condition:
ROUTING:
  - NAME: voice_only_route
    PRIORITY: 3
    WHEN: intent.category == "voice_action"
    THEN: ROUTE_TO Voice_Agent
    CONSTRAINTS:
      channels: [voice]
      requiresState: [user.is_authenticated]
      ignoreIntents: [greeting, farewell]
ConstraintTypeDescription
ignoreIntentsstring[]Intents that should not trigger this rule.
channelsstring[]Channels where this rule applies (e.g., [web, voice]).
requiresStatestring[]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:
  user:
    is_authenticated:
      type: boolean
      required: false
      default: false
      description: "Whether the user has been authenticated"
    language:
      type: string
      required: false
      source: user
  system:
    routing_failures:
      type: number
      required: false
      default: 0
      source: system
State variables follow the same VariableDefinition structure as agent variables, with the addition of namespace grouping.

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.
POLICIES:
  - NAME: no_direct_booking
    DESCRIPTION: "Supervisor must not make bookings directly"
    RULES:
      forbiddenWhen: intent.category == "booking" AND active_agent IS NOT SET
      behavior: "Route to Sales_Agent instead of handling directly"

  - NAME: auth_required_for_account
    DESCRIPTION: "Account operations require authentication"
    RULES:
      allowedWhen: user.is_authenticated == true
      triggerSignal: "auth_required"

Policy properties

PropertyTypeRequiredDefaultDescription
NAMEstringYesUnique policy name.
DESCRIPTIONstringNoHuman-readable description.
RULESobjectYesPolicy rule definitions. See below.

Policy rule properties

PropertyTypeRequiredDefaultDescription
allowedWhenstringNoCondition under which the action is allowed.
forbiddenWhenstringNoCondition under which the action is forbidden.
triggerSignalstringNoSignal to emit when the policy is triggered.
behaviorstringNoDescription of the expected behavior when triggered.

Communication settings

Communication settings define the Supervisor’s language, tone, and vocabulary preferences.
COMMUNICATION:
  language: en
  formality: neutral
  pronouns:
    use: "we"
    avoid: "I"
  vocabulary:
    prefer: [assist, help, guide]
    avoid: [unfortunately, regrettably]
  constraints:
    - "Never reveal internal agent names to the user"
    - "Always explain why a transfer is happening"

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

The BEHAVIOR block defines whether the Supervisor can respond directly to users or must always route to an agent.
BEHAVIOR:
  canRespondDirectly: false
  allowedDirectActions: [greet, clarify_intent]
  forbiddenActions: [make_booking, process_payment, access_account]
PropertyTypeRequiredDefaultDescription
canRespondDirectlybooleanYesWhether the Supervisor can send messages directly to users.
allowedDirectActionsstring[]No[]Actions the Supervisor can perform directly.
forbiddenActionsstring[]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

HANDOFF:
  - TO: Compliance_Officer
    WHEN: sanctions_clear == false
    PRIORITY: 0
    CONTEXT:
      pass: [customer_id, beneficiary_name, amount, sanctions_match_score]
      summary: "Wire flagged during sanctions screening (score: {{sanctions_match_score}})."
      history: full
      grant_memory: [user.compliance_notes]
    RETURN: true
    ON_RETURN: "resume_if_cleared"
    MAP:
      compliance_decision: sanctions_clear
      review_notes: compliance_review_notes

Properties

PropertyTypeRequiredDefaultDescription
TOstringYesTarget agent name.
WHENstringYesCondition that triggers the handoff.
PRIORITYnumberNoEvaluation priority. Lower values are evaluated first when multiple handoff rules match.
CONTEXTobjectYesContext to pass to the target agent. See Context.
RETURNbooleanYesWhether control should return to this agent after the target completes.
ON_RETURNstringNoInstruction for handling the return (e.g., step to resume at).
MAPRecord<string,string>NoReturn value mapping. Keys are target agent result fields; values are parent variable names.
REMOTEobjectNoRemote agent configuration. Same structure as DELEGATE remote.
ASYNCbooleanNofalseUse async dispatch with push notifications for remote agents.
ASYNC_TIMEOUTnumberNoTimeout in seconds for async handoff.

Handoff context

The CONTEXT block defines what information the target agent receives.
PropertyTypeRequiredDefaultDescription
passstring[]YesSession variable names to include in the handoff context.
summarystringYesHuman-readable summary of why the handoff is occurring. Supports {{}} interpolation.
historystringNoConversation history strategy. See History strategies.
grant_memorystring[]NoPersistent memory paths to grant the target agent access to.

History strategies

The history property controls how much conversation history the target agent receives.
ValueBehavior
noneNo conversation history is passed.
summary_onlyOnly the summary text is passed, no raw messages.
fullThe complete conversation history is passed.
last_NThe last N messages are passed. Specify as last_n: 10.
CONTEXT:
  pass: [customer_id, amount]
  summary: "Customer needs fraud review."
  history: last_n: 10

Return expectations

When RETURN: true, the calling agent pauses and waits for the target agent to complete. Upon return:
  1. The MAP block (if present) writes the target’s result fields into the parent’s session variables.
  2. The ON_RETURN instruction guides what happens next (e.g., resume a step, re-evaluate conditions).
When RETURN: false, the handoff is a one-way transfer. The calling agent’s session ends.

Async dispatch

For remote agents, set ASYNC: true to dispatch the handoff asynchronously. The calling agent receives a notification when the remote agent completes rather than blocking.
HANDOFF:
  - TO: External_Review
    WHEN: requires_external_review == true
    CONTEXT:
      pass: [case_id, documents]
      summary: "Documents require external review."
    RETURN: true
    REMOTE:
      location: remote
      endpoint: "https://review.partner.com/api/v1/submit"
      protocol: a2a
    ASYNC: true
    ASYNC_TIMEOUT: 3600

Memory grants

Use grant_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.
CONTEXT:
  pass: [user_id, booking_reference]
  summary: "User needs to authenticate to manage booking."
  grant_memory: [user.last_verified_at]

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

DELEGATE:
  - AGENT: Sanctions_Screening
    WHEN: beneficiary_name IS SET AND beneficiary_country IS SET
    PURPOSE: "Screen beneficiary against OFAC SDN and EU sanctions lists"
    INPUT:
      name: beneficiary_name
      account: beneficiary_account
      country: beneficiary_country
    RETURNS:
      cleared: sanctions_clear
      match_score: sanctions_match_score
    USE_RESULT: "Block if match_score > 85. Proceed only if cleared."
    TIMEOUT: "15s"
    ON_FAILURE: escalate

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_FAILURE | 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

The INPUT block maps values from the parent agent’s session context into the sub-agent’s input parameters:
INPUT:
  name: beneficiary_name          # parent's beneficiary_name -> sub-agent's "name" parameter
  account: beneficiary_account
  amount: amount
The RETURNS block maps the sub-agent’s result fields back into the parent’s session variables:
RETURNS:
  cleared: sanctions_clear        # sub-agent's "cleared" field -> parent's sanctions_clear
  match_score: sanctions_match_score

Delegate failure strategies

ValueBehavior
respondSend a message and continue. Requires FAILURE_MESSAGE.
continueSilently continue without the sub-agent’s result.
escalateTrigger human escalation.
retryRetry the delegation. Accepts a count for max retries.
Structured failure example:
ON_FAILURE:
  type: retry
  count: 2

Remote agent support

DELEGATE supports invoking agents running on remote services. Add a REMOTE block to configure the connection.
DELEGATE:
  - AGENT: External_Compliance
    WHEN: amount > 10000
    PURPOSE: "External compliance check for high-value transfers"
    INPUT:
      transaction_id: wire_reference
      amount: amount
    RETURNS:
      approved: compliance_approved
    USE_RESULT: "Proceed only if approved."
    REMOTE:
      location: remote
      endpoint: "https://compliance.partner.com/api/v1/check"
      protocol: a2a
      auth:
        type: bearer
      timeout: "30s"

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.
DELEGATE:
  - AGENT: Sanctions_Screening
    WHEN: beneficiary_name IS SET
    PURPOSE: "Screen beneficiary"
    INPUT:
      name: beneficiary_name
    RETURNS:
      cleared: sanctions_clear

  - AGENT: Fraud_Detection
    WHEN: amount IS SET
    PURPOSE: "Score fraud risk"
    INPUT:
      amount: amount
      account: source_account
    RETURNS:
      score: fraud_score
When multiple DELEGATE entries have their conditions satisfied simultaneously, the runtime can execute them in parallel (fan-out). Each delegation runs independently, and results are mapped back into the parent context as each completes.

ESCALATE

ESCALATE transfers the conversation to a human operator. It is designed for situations where the agent cannot or should not continue autonomously.

Syntax

ESCALATE:
  triggers:
    - WHEN: sanctions_screening_unavailable == true AND retry_count >= 2
      REASON: "Sanctions screening service down. Compliance check cannot be bypassed."
      PRIORITY: critical
      TAGS: [compliance, service_outage]

    - WHEN: user.requests_human == true
      REASON: "Customer requesting human specialist."
      PRIORITY: medium
      TAGS: [human_request]

  context_for_human:
    - customer_id
    - customer_name
    - amount
    - conversation_history

  routing:
    queue: "wire_operations_l2"
    skill_tags: [wire_transfer, compliance]
    priority_boost: 1

  on_human_complete:
    - IF human.resolved == true: COMPLETE
    - IF human.needs_agent == true: HANDOFF to specified_agent

Trigger properties

PropertyTypeRequiredDefaultDescription
WHENstringYesCondition that triggers escalation.
REASONstringYesHuman-readable reason for the escalation.
PRIORITYstringYesPriority level: low, medium, high, or critical.
TAGSstring[]NoTags for routing and categorization in the human agent queue.

Priority levels

LevelUse case
lowNon-urgent requests (e.g., general feedback).
mediumStandard requests (e.g., customer asks to speak with a human).
highUrgent issues (e.g., service outages, repeated failures).
criticalImmediate attention required (e.g., compliance violations, fraud).

Context for human

The context_for_human block lists session variable names to include in the escalation package. The human agent sees these values in their interface.
context_for_human:
  - customer_id
  - customer_name
  - source_account
  - amount
  - fraud_score
  - conversation_history
You can also use structured context items with templates:
context_for_human:
  - NAME: case_summary
    TEMPLATE: "Customer {{customer_name}} requesting wire of {{amount}} {{currency}}"
    INCLUDE: [fraud_score, sanctions_match_score]

Routing configuration

The routing block controls how the escalation is routed in the human agent system.
PropertyTypeRequiredDefaultDescription
queuestringNoTarget queue name in the human agent system.
skill_tagsstring[]NoRequired skills for the human agent.
priority_boostnumberNoAdditional priority boost applied to the queue entry.

Post-completion actions

The on_human_complete block defines what happens after the human agent finishes.
on_human_complete:
  - IF human.resolved == true: COMPLETE
  - IF human.needs_agent == true: HANDOFF to specified_agent
  - IF human.needs_followup == true: CONTINUE
Each entry has a 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 a WHEN expression and an optional response.

Syntax

COMPLETE:
  - WHEN: confirmation_number IS SET AND transfer_status == "released"
    RESPOND: |
      Your wire transfer has been executed successfully.

      **Confirmation:** {{confirmation_number}}
      **Amount:** {{amount}} {{currency}}
      **To:** {{beneficiary_name}}
      **Estimated Arrival:** {{estimated_arrival}}
    STORE: "wire_transfers"

  - WHEN: transfer_status == "queued"
    RESPOND: "Your wire has been queued for the next processing window."

Properties

PropertyTypeRequiredDefaultDescription
WHENstringYesCondition expression. The agent completes when this evaluates to true.
RESPONDstringNoFinal message to the user. Supports {{}} template interpolation.
STOREstringNoCollection 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:
COMPLETE:
  - WHEN: booking_confirmed == true
    RESPOND: "Your booking is confirmed!"
    VOICE:
      ssml: "<speak>Your booking is confirmed!</speak>"
    RICH_CONTENT:
      MARKDOWN: |
        ## Booking Confirmed
        | Detail | Value |
        |--------|-------|
        | Reference | {{booking_ref}} |
        | Date | {{travel_date}} |
    ACTIONS:
      - id: view_itinerary
        type: button
        label: "View Itinerary"

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:
  1. ESCALATE triggers — checked first; critical safety and compliance.
  2. HANDOFF rules — evaluated by priority (lower first).
  3. DELEGATE conditions — evaluated in declaration order.
  4. COMPLETE conditions — checked last.

Complete Supervisor example

SUPERVISOR: Customer_Service_Hub
VERSION: "2.0"
GOAL: "Route customers to the right specialist"

PERSONA: |
  Professional customer service coordinator. Routes requests
  efficiently and preserves context across agent transfers.

HANDOFF:
  - TO: Live_Agent
    WHEN: intent.category == "escalation"
    CONTEXT:
      pass: [user_id, conversation_summary]
      summary: "User requests human assistance"
    RETURN: false

  - TO: Sales_Agent
    WHEN: intent.category == "new_booking"
    CONTEXT:
      pass: [search_context, preferences]
      summary: "User looking to book"
    RETURN: false

ESCALATE:
  triggers:
    - WHEN: routing_failures >= 3
      REASON: "Multiple routing failures"
      PRIORITY: high

ON_ERROR:
  routing_failure:
    RESPOND: "Let me connect you with someone who can help."
    RETRY: 1
    THEN: HANDOFF Live_Agent

COMPLETE:
  - WHEN: handoff_successful == true
    RESPOND: "I've connected you with the right specialist."