afv-library/skills/developing-agentforce/assets/patterns/bidirectional-routing.agent

# Bidirectional Routing Pattern
# Navigate to a specialist topic and return with results
#
# ★ When To Use This Pattern:
#   - Main topic needs specialized processing then returns
#   - "Consult a specialist" pattern (like asking an expert)
#   - Complex workflows where you leave, do work, then come back
#   - Alternative to cramming everything into one topic
#
# ★ Key Insight:
#   Standard transitions (@utils.transition) are one-way.
#   For round-trip routing, store the "return address" in a variable.
#   The specialist topic transitions back when done.
#
# ★ Architecture Decision:
#   Use this when you want separation of concerns:
#   - Main topic: Orchestration and user interaction
#   - Specialist topic: Focused, complex processing
#
# This is a PARTIAL template - integrate into a complete agent file

variables:
	# ... standard linked variables ...
	return_topic: mutable string = ""
		description: "Topic to return to after specialist consultation"
	specialist_result: mutable string = ""
		description: "Result from specialist topic"
	consultation_status: mutable string = ""
		description: "Status of specialist consultation"

# Main orchestration topic
start_agent main_hub:
	label: "Main Hub"
	description: "Central hub that routes to specialists and handles results"

	reasoning:
		instructions: ->
			| You are the main coordinator.
			| When user needs specialized help:
			| - For pricing questions, consult the pricing specialist
			| - For technical issues, consult the technical specialist
			|
			| After specialist returns, communicate their findings to the user.
			|
			| Current specialist result: {!@variables.specialist_result}
			| Consultation status: {!@variables.consultation_status}
		actions:
			# Route to pricing specialist (store return address first)
			consult_pricing: @utils.transition to @topic.pricing_specialist
				available when @variables.consultation_status != "in_progress"

			# Route to technical specialist
			consult_technical: @utils.transition to @topic.technical_specialist
				available when @variables.consultation_status != "in_progress"

			end_conversation: @utils.transition to @topic.farewell

# Pricing specialist topic
topic pricing_specialist:
	label: "Pricing Specialist"
	description: "Handles complex pricing calculations and returns results"

	actions:
		calculate_price:
			description: "Calculates complex pricing"
			inputs:
				product_id: string
					description: "Product to price"
				quantity: number
					description: "Quantity requested"
			outputs:
				final_price: number
					description: "Calculated price"
				discount_applied: string
					description: "Any discounts applied"
			target: "flow://Calculate_Complex_Pricing"

	# Mark consultation as in progress when entering
	before_reasoning:
		set @variables.consultation_status = "in_progress"
		set @variables.return_topic = "main_hub"

	reasoning:
		instructions: ->
			| You are the pricing specialist.
			| Focus ONLY on pricing questions.
			| Calculate the price and prepare your findings.
			| When done, return to the main hub with your results.
		actions:
			calculate: @actions.calculate_price
				with product_id=...
				with quantity=...
				set @variables.specialist_result = @outputs.final_price

			# Return to main hub with results
			return_with_results: @utils.transition to @topic.main_hub

	# Mark consultation complete when leaving
	after_reasoning:
		set @variables.consultation_status = "completed"

# Technical specialist topic
topic technical_specialist:
	label: "Technical Specialist"
	description: "Handles technical troubleshooting and returns results"

	actions:
		diagnose_issue:
			description: "Diagnoses technical issues"
			inputs:
				symptoms: string
					description: "Reported symptoms"
			outputs:
				diagnosis: string
					description: "Technical diagnosis"
				solution: string
					description: "Recommended solution"
			target: "flow://Technical_Diagnosis"

	before_reasoning:
		set @variables.consultation_status = "in_progress"
		set @variables.return_topic = "main_hub"

	reasoning:
		instructions: ->
			| You are the technical specialist.
			| Focus ONLY on technical issues.
			| Diagnose the problem and prepare your findings.
			| When done, return to the main hub with your results.
		actions:
			diagnose: @actions.diagnose_issue
				with symptoms=...
				set @variables.specialist_result = @outputs.diagnosis

			return_with_results: @utils.transition to @topic.main_hub

	after_reasoning:
		set @variables.consultation_status = "completed"

topic farewell:
	label: "Farewell"
	description: "Ends the conversation"

	reasoning:
		instructions: ->
			| Thank the user and say goodbye.

# ★ Alternative: Simple one-way transitions (when you don't need to return)
#
# If the specialist doesn't need to return results to a coordinator,
# use simple transitions without the return_topic pattern:
#
# go_orders: @utils.transition to @topic.orders
# go_billing: @utils.transition to @topic.billing
#
# The bidirectional pattern adds complexity - only use when needed.