# Subagent Delegation vs Transition Pattern
# Understanding the difference between delegation and permanent handoffs
#
# ★ KEY CONCEPTS:
#
#   DELEGATION (@subagent.* syntax):
#   - Syntax: action_name: @subagent.subagent_name
#   - Control CAN return to the calling subagent
#   - Use for: consulting specialists, sub-tasks, getting help
#
#   TRANSITION (@utils.transition syntax):
#   - Syntax: action_name: @utils.transition to @subagent.subagent_name
#   - PERMANENT handoff - control does NOT return
#   - Use for: menu navigation, workflow stages, permanent routing
#
# ★ When To Use Each:
#   DELEGATION: "Consult an expert then continue here"
#   TRANSITION: "Go to this subagent and stay there"
#
# ★ Implementation Note:
#   If delegation syntax does not work in your deployment method, use explicit
#   transitions. For a fixed caller, transition directly back without state.
#
# This is a COMPLETE template - customize metadata and task instructions.

system:
    instructions: |
        You coordinate general and specialist help. Delegate a bounded
        consultation when its result is needed in the current task. Use a
        transition only when the user's work should continue in another
        request handler.
    messages:
        welcome: "Hello! How can I help?"
        error: "I couldn't complete that request."

access:
    default_agent_user: "agent@company.salesforce.com"

config:
    developer_name: "Delegation_Routing_Agent"
    agent_label: "Delegation and Transition"
    description: "Demonstrates returning delegation and one-way transitions"

language:
    default_locale: "en_US"

start_agent main_hub:
    label: "Main Help"
    description: "Coordinates general requests and bounded expert consultations"

    reasoning:
        instructions: ->
            | Answer general questions directly. For a bounded expert question,
              delegate to the specialist and use the returned answer. For an
              order request, transition to order help.
        actions:
            consult_expert: @subagent.specialist
                description: "Consult a specialist, receive the result, and continue the current task"
            go_orders: @utils.transition to @subagent.orders
                description: "Move permanently to order help"

subagent specialist:
    label: "Specialist"
    description: "Answers bounded expert questions delegated by the main help task"

    reasoning:
        instructions: ->
            | Provide a focused answer to the delegated expert question. Do not
              broaden the task or route elsewhere.

subagent orders:
    label: "Order Help"
    description: "Handles order questions after a one-way transition"

    reasoning:
        instructions: ->
            | Help with the user's order question. If the user changes intent,
              return to general request handling.
        actions:
            back_to_main: @utils.transition to @subagent.main_hub
                description: "Return after the user changes intent"

# ═══════════════════════════════════════════════════════════════
# PATTERN 1: Subagent Delegation (can return)
# ═══════════════════════════════════════════════════════════════

# Delegation syntax in reasoning.actions:
#
# reasoning:
#    actions:
#       # Delegation - specialist CAN return control to this subagent
#       consult_expert: @subagent.specialist_subagent
#          description: "Consult specialist for complex questions"
#          available when @variables.needs_expert_help == True
#
# The specialist subagent processes the request and control returns
# to the original subagent when done.

# ═══════════════════════════════════════════════════════════════
# PATTERN 2: Transition (permanent handoff)
# ═══════════════════════════════════════════════════════════════

# Transition syntax in reasoning.actions:
#
# reasoning:
#    actions:
#       # Transition - permanent move to orders subagent
#       go_orders: @utils.transition to @subagent.orders
#
# Control moves to orders subagent and STAYS there.
# User continues in that subagent until another transition occurs.

# ═══════════════════════════════════════════════════════════════
# PATTERN 3: Explicit Fixed Return (fallback pattern)
# ═══════════════════════════════════════════════════════════════

# If delegation is unavailable and the caller is fixed:
#
# # In the caller:
# go_specialist: @utils.transition to @subagent.specialist
#
# # In the specialist:
# return_home: @utils.transition to @subagent.main_hub
#
# Store a dynamic return address only when one specialist serves multiple
# callers and deterministic logic reads, clears, and resets that address.

# ═══════════════════════════════════════════════════════════════
# COMPARISON TABLE
# ═══════════════════════════════════════════════════════════════
#
# | Feature              | Delegation        | Transition              |
# |----------------------|-------------------|-------------------------|
# | Syntax               | @subagent.name       | @utils.transition to    |
# | Returns to caller?   | YES               | NO                      |
# | Use in actions:      | YES               | YES                     |
# | Use in lifecycle:    | NO                | YES (bare syntax)       |
# | Best for             | Consult & return  | Menu/workflow routing   |
#
# ═══════════════════════════════════════════════════════════════