MultiTopicNavigation

Overview

This recipe demonstrates how to build agents with multiple topics and navigate between them. Topics allow you to organize complex agents into specialized conversation modes, each handling a specific phase or capability of the interaction.

Agent Flow

mermaid

%%{init: {'theme':'neutral'}}%%
graph TD
    A[Start] --> B[start_agent: topic_selector]
    B --> C{User Intent}
    C -->|Browse| D[Transition to hotel_browse]
    C -->|View Booking| E[Transition to hotel_confirmation]
    D --> F[hotel_browse Topic]
    F --> G[search_hotels Action]
    G --> H{User Ready to Book?}
    H -->|Yes| I[Transition to hotel_booking]
    H -->|Continue| G
    I --> J[hotel_booking Topic]
    J --> K[create_booking Action]
    K --> L[Auto-transition to hotel_confirmation]
    L --> M[hotel_confirmation Topic]
    M --> N[Display Confirmation]
    N --> O{New Booking?}
    O -->|Yes| P[Transition to hotel_browse]
    P --> F
    O -->|No| Q[End]
    E --> M

Key Concepts

Multiple topic blocks: Defining several topics in one agent
Topic transitions: Moving between topics with @utils.transition to @topic.name
Transition after action: Using transition to in action blocks
Topic specialization: Each topic handles a specific responsibility
State sharing: Variables are global across all topics
Conditional transitions: Using available when on transition actions

How It Works

Multi-Topic Architecture

Instead of one topic handling everything, create specialized topics:

agentscript

start_agent topic_selector:
   description: "Welcome users and determine their hotel service needs"

   reasoning:
      actions:
         browse_hotels: @utils.transition to @topic.hotel_browse
            description: "Browse and search for available hotels"

         view_booking: @utils.transition to @topic.hotel_confirmation
            description: "View existing booking confirmations"
            available when @variables.booking_confirmed == True

topic hotel_browse:
   description: "Browse available hotels and view information"

topic hotel_booking:
   description: "Handle hotel booking and reservation"

topic hotel_confirmation:
   description: "Confirm booking and provide details"

Topic Transitions with @utils.transition

Move between topics using @utils.transition to @topic.name:

agentscript

reasoning:
   actions:
      proceed_to_booking: @utils.transition to @topic.hotel_booking
         description: "Move to booking when user wants to reserve a hotel"

Conditional Transition Availability

Use available when to control when transitions are possible:

agentscript

actions:
   view_booking: @utils.transition to @topic.hotel_confirmation
      description: "View existing booking confirmations"
      available when @variables.booking_confirmed == True

Automatic Transition After Action

Transition after an action completes using transition to:

agentscript

actions:
   create_booking: @actions.create_booking
      with hotel_name=...
      with check_in=@variables.check_in_date
      with check_out=@variables.check_out_date
      set @variables.hotel_name = @inputs.hotel_name
      set @variables.booking_id = @outputs.booking_id
      set @variables.booking_confirmed = True
      # Automatically move to confirmation after booking
      transition to @topic.hotel_confirmation

Storing Action Inputs

Capture inputs that the LLM provides:

agentscript

actions:
   search_hotels: @actions.search_hotels
      with location=...
      with check_in=...
      with check_out=...
      set @variables.check_in_date = @inputs.check_in
      set @variables.check_out_date = @inputs.check_out

Key Code Snippets

Complete Topic: Hotel Browse

agentscript

topic hotel_browse:
   description: "Browse available hotels and view information"

   actions:
      search_hotels:
         description: "Search for available hotels"
         inputs:
            location: string
               description: "City or location to search for hotels in"
            check_in: string
               description: "Check-in date in ISO format (YYYY-MM-DD)"
            check_out: string
               description: "Check-out date in ISO format (YYYY-MM-DD)"
         outputs:
            hotels: list[object]
               description: "List of available hotel objects"
         target: "flow://SearchHotels"

   reasoning:
      instructions:->
         | Help users find the perfect hotel.

           Current search criteria:

         if @variables.check_in_date:
            | - Check-in: {!@variables.check_in_date}
         else:
            | - Check-in: Not set

         if @variables.check_out_date:
            | - Check-out: {!@variables.check_out_date}
         else:
            | - Check-out: Not set

         | When users are ready to book, use the proceed_to_booking action.

      actions:
         search_hotels: @actions.search_hotels
            with location=...
            with check_in=...
            with check_out=...
            transition to @topic.hotel_booking

         proceed_to_booking: @utils.transition to @topic.hotel_booking
            description: "Move to booking when user wants to reserve a hotel"

Complete Topic: Hotel Booking

agentscript

topic hotel_booking:
   description: "Handle hotel booking and reservation"

   actions:
      create_booking:
         description: "Creates a hotel reservation"
         inputs:
            hotel_name: string
               description: "Name of the hotel to book"
            check_in: string
               description: "Check-in date"
            check_out: string
               description: "Check-out date"
         outputs:
            booking_id: string
               description: "Unique booking confirmation identifier"
            success: boolean
               description: "Whether the booking was created successfully"
         target: "flow://CreateBooking"

   reasoning:
      instructions:->
         | Complete the booking for the customer.

           Booking details:

         if @variables.hotel_name:
            | - Hotel: {!@variables.hotel_name}
         else:
            | - Hotel: Not selected

         | - Check-in: {!@variables.check_in_date}
           - Check-out: {!@variables.check_out_date}

         | Once booking is complete, transition to hotel_confirmation topic.

      actions:
         create_booking: @actions.create_booking
            with hotel_name=...
            with check_in=...
            with check_out=...
            set @variables.booking_id = @outputs.booking_id
            set @variables.booking_confirmed = @outputs.success
            transition to @topic.hotel_confirmation

         go_to_confirmation: @utils.transition to @topic.hotel_confirmation
            description: "Move to confirmation after successful booking"

Complete Topic: Hotel Confirmation

agentscript

topic hotel_confirmation:
   description: "Confirm booking and provide details"

   reasoning:
      instructions:->
         | The booking has been confirmed!

           Confirmation details:
           - Booking ID: {!@variables.booking_id}
           - Hotel: {!@variables.hotel_name}
           - Check-in: {!@variables.check_in_date}
           - Check-out: {!@variables.check_out_date}

           Provide these details to the customer and ask if they need anything else.
           If they want to make another booking, use start_new_booking action.

      actions:
         start_new_booking: @utils.transition to @topic.hotel_browse
            description: "Start a new hotel search and booking"

Try It Out

Example: Complete Booking Flow

start_agent routes to hotel_browse

text

Agent: Welcome to our hotel booking service! I can help you browse hotels, make bookings, or answer questions.

User: I need a hotel in San Francisco for March 15-17

[Agent calls search_hotels action]
[Stores: check_in_date="2025-03-15", check_out_date="2025-03-17"]

Agent: I found several hotels in San Francisco for March 15-17:
       1. Bay View Hotel - $180/night
       2. Downtown Plaza - $150/night
       3. Airport Inn - $100/night

       Which one interests you?

User: I'll take the Bay View Hotel

Agent: Excellent choice! Let me help you book the Bay View Hotel.

[Agent calls proceed_to_booking → transitions to hotel_booking]

text

Agent: I'm ready to complete your booking at Bay View Hotel.
       - Check-in: March 15
       - Check-out: March 17

       Please confirm these details are correct.

User: Yes, that's correct

[Agent calls create_booking action]
[Stores: hotel_name="Bay View Hotel", booking_id="BK789456"]
[Auto-transitions to hotel_confirmation]

[Now in hotel_confirmation topic]

text

Agent: Your booking is confirmed! 🎉

       Confirmation details:
       - Booking ID: BK789456
       - Hotel: Bay View Hotel
       - Check-in: March 15
       - Check-out: March 17

       You'll receive a confirmation email shortly.
       Would you like to make another booking?

User: No, that's all. Thanks!

Agent: You're welcome! Have a wonderful stay!

Multi-Topic Design Patterns

Linear Workflow

text

browse → booking → confirmation

Good for: Checkout processes, onboarding, step-by-step wizards

Hub-and-Spoke

text

main_menu → { product_info, order_status, support }
         ↓
      main_menu (return)

Good for: Customer service, multi-purpose assistants

Bidirectional Flow

text

browse ↔ booking ↔ confirmation

Good for: Exploratory interfaces, comparison shopping

Best Practices

Topic Naming

Good: hotel_browse, payment_processing, account_settings

Poor: topic1, main, do_stuff

Transition Descriptions

Good:

agentscript

proceed_to_booking: @utils.transition to @topic.hotel_booking
   description: "Move to booking when user wants to reserve a hotel"

Poor:

agentscript

go_next: @utils.transition to @topic.next
   description: "Go next"

State Management

Store state in variables before transitioning:

agentscript

actions:
   search_hotels: @actions.search_hotels
      with check_in=...
      set @variables.check_in_date = @inputs.check_in
      # State preserved for next topic

What's Next

TopicDelegation: Learn about delegation (consulting other topics)
MultiTopicOrchestration: Handle complex workflows with 4+ topics
SystemInstructionOverrides: Customize behavior per topic
DynamicActionRouting: Control action availability

Testing

Test Case 1: Happy Path

Start in browse → search → select → book → confirm
Verify all transitions work

Test Case 2: State Persistence

Set check_in_date in browse
Transition to booking
Verify date still accessible

Test Case 3: Multiple Bookings

Complete one booking
Use start_new_booking
Complete second booking

MultiTopicNavigation ​

Overview ​

Agent Flow ​

Key Concepts ​

How It Works ​

Multi-Topic Architecture ​

Topic Transitions with @utils.transition ​

Conditional Transition Availability ​

Automatic Transition After Action ​

Storing Action Inputs ​

Key Code Snippets ​

Complete Topic: Hotel Browse ​

Complete Topic: Hotel Booking ​

Complete Topic: Hotel Confirmation ​

Try It Out ​

Example: Complete Booking Flow ​

Multi-Topic Design Patterns ​

Linear Workflow ​

Hub-and-Spoke ​

Bidirectional Flow ​

Best Practices ​

Topic Naming ​

Transition Descriptions ​

State Management ​

What's Next ​

Testing ​

Test Case 1: Happy Path ​

Test Case 2: State Persistence ​

Test Case 3: Multiple Bookings ​

MultiTopicNavigation

Overview

Agent Flow

Key Concepts

How It Works

Multi-Topic Architecture

Topic Transitions with @utils.transition

Conditional Transition Availability

Automatic Transition After Action

Storing Action Inputs

Key Code Snippets

Complete Topic: Hotel Browse

Complete Topic: Hotel Booking

Complete Topic: Hotel Confirmation

Try It Out

Example: Complete Booking Flow

Multi-Topic Design Patterns

Linear Workflow

Hub-and-Spoke

Bidirectional Flow

Best Practices

Topic Naming

Transition Descriptions

State Management

What's Next

Testing

Test Case 1: Happy Path

Test Case 2: State Persistence

Test Case 3: Multiple Bookings