Document supervisor / dynamic routing pattern in Core API doc

[ekzhu]

Scenario description: #5399 (comment)

Discussed in #5399

[ekzhu]

@glarunsingh I will need your assistance to complete this documentation example.

Can you provide me with a chain of events that occur in your scenario, and the triggers for each event. E.g., what triggers the user's interaction with each agent, are there situation when multiple agents can be called upon, but what are the criteria to choose?

[glarunsingh]

Hi @ekzhu,

Good day to you!

The following is my use case:

This is a chat application where users enter responses, and the LLM responds based on their intent, switching between different states accordingly.

We are developing this application for our client’s insurance users. Once they sign up for our insurance platform, they can log in to this application using the same credentials.

Objectives

As of now, we are planning to support three major objectives:

1. Healthcare (general health tips/symptom checker)
2. Provider Calling (doctor appointment booking)
3. Claims Status Update

App Flow

When a user opens the app, it will display a welcome message stating that it can provide support for the above three areas.

If a user has any symptoms, they can discuss them with the application.

Example

If a user says, “I have a headache,” the LLM will recognize this as a Healthcare State based on predefined prompts. The system should maintain this state and follow the corresponding rules.

Healthcare State Rules

• If the symptom is mild, the system will proceed to check vitals in the next step by triggering a third-party SDK.
• If the symptom is severe, the system will transition to the Provider Calling (doctor appointment) State.

Provider Calling State

• The system retrieves the user’s location.
• Based on the user's insurance coverage, it identifies available healthcare providers nearby.
• It collects details such as the preferred appointment date and time.
• It then contacts the provider’s office via a third-party application to complete the appointment booking.

The Healthcare and Provider Calling states are interconnected in some scenarios.

Example

• If a user directly says, "I want to book a doctor’s appointment," the system should immediately trigger the Provider Calling state.
• Even in the middle of a conversation, if the user wants to switch from symptom checking to appointment booking (or vice versa) or check their claims, the system should be able to transition seamlessly between states.

Claims Status Inquiry

• If a user requests claim details, the system should provide the claim status (e.g., Open, In Progress, Completed, Rejected, etc.).
• There are multiple tools involved in retrieving claims data for this state.

Implementation

Currently, we have built this application using Python with conditional logic. However, we are looking for a framework that can help us achieve this more efficiently.

Please let me know if you need any further details.

[glarunsingh]

@raimondasl Sorry for the delay in response. Please mark it as needs triage and i'll be happy to assist.

[raimondasl]

@glarunsingh : I am not sure why you want needs-triage flag on this issue. You are working with @ekzhu on this issue, which means there is no need for needs-triage flag. Thank you.

[ekzhu]

@glarunsingh thanks for the update. I will try to create an example sometime next week.

[glarunsingh]

Hi @ekzhu, any updates? This week, we need to decide which agentic framework to use so we can move forward with our use case. I'm really eager to work with AutoGen for our project. Can you provide some guidance?

[ekzhu]

@glarunsingh thanks for the reminder. I may not have time this week to come up with the example. I can jump on it next week.

The general idea is that you probably need two things: (1) an observable state for determining which agent user should be talking to and what are possible next states that can be moved to and (2) agents don't share message history.

Right now the Swarm team in AgentChat has an implicit state which is the whole conversation history, and for each agent, there can be a constrained list of next agents. Each agent can also hand off to the user. The only thing that may (or may not) cause issue is all agents share the same conversation history with the user.

Do you want to take a look at Swarm first?

[glarunsingh]

Sure, I'll check with the Swarm and come back.