Skip to content

A programming framework for agentic AI

Selector group chat that uses LLM to select the next speaker (#3680)

Eric Zhu02ced7c6b3af
diff --git a/python/packages/autogen-agentchat/src/autogen_agentchat/agents/_tool_use_assistant_agent.py b/python/packages/autogen-agentchat/src/autogen_agentchat/agents/_tool_use_assistant_agent.py
index 7e287b75b..ecf02d16d 100644
--- a/python/packages/autogen-agentchat/src/autogen_agentchat/agents/_tool_use_assistant_agent.py
+++ b/python/packages/autogen-agentchat/src/autogen_agentchat/agents/_tool_use_assistant_agent.py
@@ -36,7 +36,7 @@ class ToolUseAssistantAgent(BaseToolUseChatAgent):
registered_tools: List[Tool],
*,
description: str = "An agent that provides assistance with ability to use tools.",
- system_message: str = "You are a helpful AI assistant. Solve tasks using your tools. Reply 'TERMINATE' in the end when the task is completed.",
+ system_message: str = "You are a helpful AI assistant. Solve tasks using your tools.",
):
super().__init__(name=name, description=description, registered_tools=registered_tools)
self._model_client = model_client
diff --git a/python/packages/autogen-agentchat/src/autogen_agentchat/teams/__init__.py b/python/packages/autogen-agentchat/src/autogen_agentchat/teams/__init__.py
index be58b192e..92fc1b98b 100644
--- a/python/packages/autogen-agentchat/src/autogen_agentchat/teams/__init__.py
+++ b/python/packages/autogen-agentchat/src/autogen_agentchat/teams/__init__.py
@@ -1,6 +1,7 @@
-from ._logging import EVENT_LOGGER_NAME, ConsoleLogHandler, FileLogHandler
+from ._logging import EVENT_LOGGER_NAME, TRACE_LOGGER_NAME, ConsoleLogHandler, FileLogHandler
__all__ = [
+ "TRACE_LOGGER_NAME",
"EVENT_LOGGER_NAME",
"ConsoleLogHandler",
"FileLogHandler",
diff --git a/python/packages/autogen-agentchat/src/autogen_agentchat/teams/_events.py b/python/packages/autogen-agentchat/src/autogen_agentchat/teams/_events.py
index ba15fd21a..36268ebdd 100644
--- a/python/packages/autogen-agentchat/src/autogen_agentchat/teams/_events.py
+++ b/python/packages/autogen-agentchat/src/autogen_agentchat/teams/_events.py
@@ -49,3 +49,15 @@ class ToolCallResultEvent(BaseModel):
"""The sender of the tool call result message."""
model_config = ConfigDict(arbitrary_types_allowed=True)
+
+
+class SelectSpeakerEvent(BaseModel):
+ """An event for selecting the next speaker in a group chat."""
+
+ selected_speaker: str
+ """The name of the selected speaker."""
+
+ source: AgentId
+ """The agent ID that selected the speaker."""
+
+ model_config = ConfigDict(arbitrary_types_allowed=True)
diff --git a/python/packages/autogen-agentchat/src/autogen_agentchat/teams/_logging.py b/python/packages/autogen-agentchat/src/autogen_agentchat/teams/_logging.py
index 41fba1948..1c6575e02 100644
--- a/python/packages/autogen-agentchat/src/autogen_agentchat/teams/_logging.py
+++ b/python/packages/autogen-agentchat/src/autogen_agentchat/teams/_logging.py
@@ -10,8 +10,9 @@ from autogen_core.components import FunctionCall, Image
from autogen_core.components.models import FunctionExecutionResult
from ..agents import ChatMessage, MultiModalMessage, StopMessage, TextMessage, ToolCallMessage, ToolCallResultMessage
-from ._events import ContentPublishEvent, ToolCallEvent, ToolCallResultEvent
+from ._events import ContentPublishEvent, SelectSpeakerEvent, ToolCallEvent, ToolCallResultEvent
+TRACE_LOGGER_NAME = "autogen_agentchat"
EVENT_LOGGER_NAME = "autogen_agentchat.events"
ContentType = Union[str, List[Union[str, Image]], List[FunctionCall], List[FunctionExecutionResult]]
@@ -43,14 +44,14 @@ class BaseLogHandler(logging.Handler):
class ConsoleLogHandler(BaseLogHandler):
- def _format_message(
+ def _format_chat_message(
self,
*,
source_agent_id: AgentId | None,
message: ChatMessage,
timestamp: str,
) -> str:
- body = f"{self.serialize_content(message.content)}\nFrom: {message.source}"
+ body = f"{self.serialize_content(message.content)}"
if source_agent_id is None:
console_message = f"\n{'-'*75} \n" f"\033[91m[{timestamp}]:\033[0m\n" f"\n{body}"
else:
@@ -63,13 +64,20 @@ class ConsoleLogHandler(BaseLogHandler):
ts = datetime.fromtimestamp(record.created).isoformat()
if isinstance(record.msg, ContentPublishEvent | ToolCallEvent | ToolCallResultEvent):
sys.stdout.write(
- self._format_message(
+ self._format_chat_message(
source_agent_id=record.msg.source,
message=record.msg.agent_message,
timestamp=ts,
)
)
sys.stdout.flush()
+ elif isinstance(record.msg, SelectSpeakerEvent):
+ sys.stdout.write(
+ f"\n{'-'*75} \n"
+ f"\033[91m[{ts}], {record.msg.source.type}:\033[0m\n"
+ f"\nSelected next speaker: {record.msg.selected_speaker}"
+ )
+ sys.stdout.flush()
else:
raise ValueError(f"Unexpected log record: {record.msg}")
@@ -80,23 +88,26 @@ class FileLogHandler(BaseLogHandler):
self.filename = filename
self.file_handler = logging.FileHandler(filename)
- def _format_entry(self, *, source: AgentId | None, message: ChatMessage, timestamp: str) -> Dict[str, Any]:
- return {
- "timestamp": timestamp,
- "source": source,
- "message": self.serialize_content(message),
- "type": "OrchestrationEvent",
- }
-
def emit(self, record: logging.LogRecord) -> None:
ts = datetime.fromtimestamp(record.created).isoformat()
if isinstance(record.msg, ContentPublishEvent | ToolCallEvent | ToolCallResultEvent):
log_entry = json.dumps(
- self._format_entry(
- source=record.msg.source,
- message=record.msg.agent_message,
- timestamp=ts,
- ),
+ {
+ "timestamp": ts,
+ "source": record.msg.source,
+ "agent_message": self.serialize_content(record.msg.agent_message),
+ "type": record.msg.__class__.__name__,
+ },
+ default=self.json_serializer,
+ )
+ elif isinstance(record.msg, SelectSpeakerEvent):
+ log_entry = json.dumps(
+ {
+ "timestamp": ts,
+ "source": record.msg.source,
+ "selected_speaker": record.msg.selected_speaker,
+ "type": "SelectSpeakerEvent",
+ },
default=self.json_serializer,
)
else:
diff --git a/python/packages/autogen-agentchat/src/autogen_agentchat/teams/group_chat/__init__.py b/python/packages/autogen-agentchat/src/autogen_agentchat/teams/group_chat/__init__.py
index 0ed1545ad..45b6f6bed 100644
--- a/python/packages/autogen-agentchat/src/autogen_agentchat/teams/group_chat/__init__.py
+++ b/python/packages/autogen-agentchat/src/autogen_agentchat/teams/group_chat/__init__.py
@@ -1,3 +1,4 @@
from ._round_robin_group_chat import RoundRobinGroupChat
+from ._selector_group_chat import SelectorGroupChat
-__all__ = ["RoundRobinGroupChat"]
+__all__ = ["RoundRobinGroupChat", "SelectorGroupChat"]
diff --git a/python/packages/autogen-agentchat/src/autogen_agentchat/teams/group_chat/_base_group_chat.py b/python/packages/autogen-agentchat/src/autogen_agentchat/teams/group_chat/_base_group_chat.py
new file mode 100644
index 000000000..30cad5adb
--- /dev/null
+++ b/python/packages/autogen-agentchat/src/autogen_agentchat/teams/group_chat/_base_group_chat.py
@@ -0,0 +1,169 @@
+import uuid
+from abc import ABC, abstractmethod
+from typing import Callable, List
+
+from autogen_core.application import SingleThreadedAgentRuntime
+from autogen_core.base import AgentId, AgentInstantiationContext, AgentRuntime, AgentType, MessageContext, TopicId
+from autogen_core.components import ClosureAgent, TypeSubscription
+from autogen_core.components.tool_agent import ToolAgent
+from autogen_core.components.tools import Tool
+
+from autogen_agentchat.agents._base_chat_agent import ChatMessage
+
+from ...agents import BaseChatAgent, BaseToolUseChatAgent, TextMessage
+from .._base_team import BaseTeam, TeamRunResult
+from .._events import ContentPublishEvent, ContentRequestEvent
+from ._base_chat_agent_container import BaseChatAgentContainer
+from ._base_group_chat_manager import BaseGroupChatManager
+
+
+class BaseGroupChat(BaseTeam, ABC):
+ """The base class for group chat teams.
+
+ To implement a group chat team, first create a subclass of :class:`BaseGroupChatManager` and then
+ create a subclass of :class:`BaseGroupChat` that uses the group chat manager.
+ """
+
+ def __init__(self, participants: List[BaseChatAgent], group_chat_manager_class: type[BaseGroupChatManager]):
+ if len(participants) == 0:
+ raise ValueError("At least one participant is required.")
+ if len(participants) != len(set(participant.name for participant in participants)):
+ raise ValueError("The participant names must be unique.")
+ for participant in participants:
+ if isinstance(participant, BaseToolUseChatAgent) and not participant.registered_tools:
+ raise ValueError(
+ f"Participant '{participant.name}' is a tool use agent so it must have registered tools."
+ )
+ self._participants = participants
+ self._team_id = str(uuid.uuid4())
+ self._base_group_chat_manager_class = group_chat_manager_class
+
+ @abstractmethod
+ def _create_group_chat_manager_factory(
+ self,
+ parent_topic_type: str,
+ group_topic_type: str,
+ participant_topic_types: List[str],
+ participant_descriptions: List[str],
+ ) -> Callable[[], BaseGroupChatManager]: ...
+
+ def _create_participant_factory(
+ self, parent_topic_type: str, agent: BaseChatAgent, tool_agent_type: AgentType | None
+ ) -> Callable[[], BaseChatAgentContainer]:
+ def _factory() -> BaseChatAgentContainer:
+ id = AgentInstantiationContext.current_agent_id()
+ assert id == AgentId(type=agent.name, key=self._team_id)
+ container = BaseChatAgentContainer(parent_topic_type, agent, tool_agent_type)
+ assert container.id == id
+ return container
+
+ return _factory
+
+ def _create_tool_agent_factory(
+ self,
+ caller_name: str,
+ tools: List[Tool],
+ ) -> Callable[[], ToolAgent]:
+ def _factory() -> ToolAgent:
+ return ToolAgent(f"Tool agent for {caller_name}", tools)
+
+ return _factory
+
+ async def run(self, task: str) -> TeamRunResult:
+ """Run the team and return the result."""
+ # Create the runtime.
+ runtime = SingleThreadedAgentRuntime()
+
+ # Constants for the group chat manager.
+ group_chat_manager_agent_type = AgentType("group_chat_manager")
+ group_chat_manager_topic_type = group_chat_manager_agent_type.type
+ group_topic_type = "round_robin_group_topic"
+ team_topic_type = "team_topic"
+
+ # Register participants.
+ participant_topic_types: List[str] = []
+ participant_descriptions: List[str] = []
+ for participant in self._participants:
+ if isinstance(participant, BaseToolUseChatAgent):
+ assert participant.registered_tools is not None and len(participant.registered_tools) > 0
+ # Register the tool agent.
+ tool_agent_type = await ToolAgent.register(
+ runtime,
+ f"tool_agent_for_{participant.name}",
+ self._create_tool_agent_factory(participant.name, participant.registered_tools),
+ )
+ # No subscriptions are needed for the tool agent, which will be called via direct messages.
+ else:
+ # No tool agent is needed.
+ tool_agent_type = None
+
+ # Use the participant name as the agent type and topic type.
+ agent_type = participant.name
+ topic_type = participant.name
+ # Register the participant factory.
+ await BaseChatAgentContainer.register(
+ runtime,
+ type=agent_type,
+ factory=self._create_participant_factory(group_topic_type, participant, tool_agent_type),
+ )
+ # Add subscriptions for the participant.
+ await runtime.add_subscription(TypeSubscription(topic_type=topic_type, agent_type=agent_type))
+ await runtime.add_subscription(TypeSubscription(topic_type=group_topic_type, agent_type=agent_type))
+ # Add the participant to the lists.
+ participant_descriptions.append(participant.description)
+ participant_topic_types.append(topic_type)
+
+ # Register the group chat manager.
+ await self._base_group_chat_manager_class.register(
+ runtime,
+ type=group_chat_manager_agent_type.type,
+ factory=self._create_group_chat_manager_factory(
+ parent_topic_type=team_topic_type,
+ group_topic_type=group_topic_type,
+ participant_topic_types=participant_topic_types,
+ participant_descriptions=participant_descriptions,
+ ),
+ )
+ # Add subscriptions for the group chat manager.
+ await runtime.add_subscription(
+ TypeSubscription(topic_type=group_chat_manager_topic_type, agent_type=group_chat_manager_agent_type.type)
+ )
+ await runtime.add_subscription(
+ TypeSubscription(topic_type=group_topic_type, agent_type=group_chat_manager_agent_type.type)
+ )
+ await runtime.add_subscription(
+ TypeSubscription(topic_type=team_topic_type, agent_type=group_chat_manager_agent_type.type)
+ )
+
+ group_chat_messages: List[ChatMessage] = []
+
+ async def collect_group_chat_messages(
+ _runtime: AgentRuntime, id: AgentId, message: ContentPublishEvent, ctx: MessageContext
+ ) -> None:
+ group_chat_messages.append(message.agent_message)
+
+ await ClosureAgent.register(
+ runtime,
+ type="collect_group_chat_messages",
+ closure=collect_group_chat_messages,
+ subscriptions=lambda: [
+ TypeSubscription(topic_type=group_topic_type, agent_type="collect_group_chat_messages")
+ ],
+ )
+
+ # Start the runtime.
+ runtime.start()
+
+ # Run the team by publishing the task to the team topic and then requesting the result.
+ team_topic_id = TopicId(type=team_topic_type, source=self._team_id)
+ group_chat_manager_topic_id = TopicId(type=group_chat_manager_topic_type, source=self._team_id)
+ await runtime.publish_message(
+ ContentPublishEvent(agent_message=TextMessage(content=task, source="user")),
+ topic_id=team_topic_id,
+ )
+ await runtime.publish_message(ContentRequestEvent(), topic_id=group_chat_manager_topic_id)
+
+ # Wait for the runtime to stop.
+ await runtime.stop_when_idle()
+
+ return TeamRunResult(messages=group_chat_messages)
diff --git a/python/packages/autogen-agentchat/src/autogen_agentchat/teams/group_chat/_base_group_chat_manager.py b/python/packages/autogen-agentchat/src/autogen_agentchat/teams/group_chat/_base_group_chat_manager.py
index 7059e11fd..9ad2d2fd2 100644
--- a/python/packages/autogen-agentchat/src/autogen_agentchat/teams/group_chat/_base_group_chat_manager.py
+++ b/python/packages/autogen-agentchat/src/autogen_agentchat/teams/group_chat/_base_group_chat_manager.py
@@ -1,10 +1,11 @@
import logging
+from abc import ABC, abstractmethod
from typing import List
from autogen_core.base import MessageContext, TopicId
from autogen_core.components import event
-from ...agents import ChatMessage, StopMessage, TextMessage
+from ...agents import StopMessage, TextMessage
from .._events import ContentPublishEvent, ContentRequestEvent
from .._logging import EVENT_LOGGER_NAME
from ._sequential_routed_agent import SequentialRoutedAgent
@@ -12,12 +13,16 @@ from ._sequential_routed_agent import SequentialRoutedAgent
event_logger = logging.getLogger(EVENT_LOGGER_NAME)
-class BaseGroupChatManager(SequentialRoutedAgent):
+class BaseGroupChatManager(SequentialRoutedAgent, ABC):
"""Base class for a group chat manager that manages a group chat with multiple participants.
It is the responsibility of the caller to ensure:
- All participants must subscribe to the group chat topic and each of their own topics.
- The group chat manager must subscribe to the parent topic and the group chat topic.
+ - The agent types of the participants must be unique.
+ - For each participant, the agent type must be the same as the topic type.
+
+ Without the above conditions, the group chat will not function correctly.
Args:
parent_topic_type (str): The topic type of the parent orchestrator.
@@ -51,7 +56,7 @@ class BaseGroupChatManager(SequentialRoutedAgent):
raise ValueError("The group topic type must not be the same as the parent topic type.")
self._participant_topic_types = participant_topic_types
self._participant_descriptions = participant_descriptions
- self._message_thread: List[ChatMessage] = []
+ self._message_thread: List[ContentPublishEvent] = []
@event
async def handle_content_publish(self, message: ContentPublishEvent, ctx: MessageContext) -> None:
@@ -68,13 +73,13 @@ class BaseGroupChatManager(SequentialRoutedAgent):
# Process event from parent.
if ctx.topic_id.type == self._parent_topic_type:
- self._message_thread.append(message.agent_message)
+ self._message_thread.append(message)
await self.publish_message(message, topic_id=group_chat_topic_id)
return
# Process event from the group chat this agent manages.
assert ctx.topic_id.type == self._group_topic_type
- self._message_thread.append(message.agent_message)
+ self._message_thread.append(message)
# If the message is a stop message, publish the last message as a TextMessage to the parent topic.
# TODO: custom handling the final message.
@@ -107,7 +112,8 @@ class BaseGroupChatManager(SequentialRoutedAgent):
participant_topic_id = TopicId(type=speaker_topic_type, source=ctx.topic_id.source)
await self.publish_message(ContentRequestEvent(), topic_id=participant_topic_id)
- async def select_speaker(self, thread: List[ChatMessage]) -> str:
+ @abstractmethod
+ async def select_speaker(self, thread: List[ContentPublishEvent]) -> str:
"""Select a speaker from the participants and return the
topic type of the selected speaker."""
- raise NotImplementedError("Method not implemented")
+ ...
diff --git a/python/packages/autogen-agentchat/src/autogen_agentchat/teams/group_chat/_round_robin_group_chat.py b/python/packages/autogen-agentchat/src/autogen_agentchat/teams/group_chat/_round_robin_group_chat.py
index b58cf28f0..b953e5460 100644
--- a/python/packages/autogen-agentchat/src/autogen_agentchat/teams/group_chat/_round_robin_group_chat.py
+++ b/python/packages/autogen-agentchat/src/autogen_agentchat/teams/group_chat/_round_robin_group_chat.py
@@ -1,23 +1,39 @@
-import uuid
from typing import Callable, List
-from autogen_core.application import SingleThreadedAgentRuntime
-from autogen_core.base import AgentId, AgentInstantiationContext, AgentRuntime, AgentType, MessageContext, TopicId
-from autogen_core.components import ClosureAgent, TypeSubscription
-from autogen_core.components.tool_agent import ToolAgent
-from autogen_core.components.tools import Tool
+from ...agents import BaseChatAgent
+from .._events import ContentPublishEvent
+from ._base_group_chat import BaseGroupChat
+from ._base_group_chat_manager import BaseGroupChatManager
-from autogen_agentchat.agents._base_chat_agent import ChatMessage
-from ...agents import BaseChatAgent, BaseToolUseChatAgent, TextMessage
-from .._base_team import BaseTeam, TeamRunResult
-from .._events import ContentPublishEvent, ContentRequestEvent
-from ._base_chat_agent_container import BaseChatAgentContainer
-from ._round_robin_group_chat_manager import RoundRobinGroupChatManager
+class RoundRobinGroupChatManager(BaseGroupChatManager):
+ """A group chat manager that selects the next speaker in a round-robin fashion."""
+ def __init__(
+ self,
+ parent_topic_type: str,
+ group_topic_type: str,
+ participant_topic_types: List[str],
+ participant_descriptions: List[str],
+ ) -> None:
+ super().__init__(
+ parent_topic_type,
+ group_topic_type,
+ participant_topic_types,
+ participant_descriptions,
+ )
+ self._next_speaker_index = 0
+
+ async def select_speaker(self, thread: List[ContentPublishEvent]) -> str:
+ """Select a speaker from the participants in a round-robin fashion."""
+ current_speaker_index = self._next_speaker_index
+ self._next_speaker_index = (current_speaker_index + 1) % len(self._participant_topic_types)
+ return self._participant_topic_types[current_speaker_index]
-class RoundRobinGroupChat(BaseTeam):
- """A team that runs a group chat with participants taking turns in a round-robin fashion.
+
+class RoundRobinGroupChat(BaseGroupChat):
+ """A team that runs a group chat with participants taking turns in a round-robin fashion
+ to publish a message to all.
If a single participant is in the team, the participant will be the only speaker.
@@ -35,7 +51,7 @@ class RoundRobinGroupChat(BaseTeam):
.. code-block:: python
from autogen_agentchat.agents import ToolUseAssistantAgent
- from autogen_agentchat.teams import RoundRobinGroupChat
+ from autogen_agentchat.teams.group_chat import RoundRobinGroupChat
assistant = ToolUseAssistantAgent("Assistant", model_client=..., registered_tools=...)
team = RoundRobinGroupChat([assistant])
@@ -46,143 +62,28 @@ class RoundRobinGroupChat(BaseTeam):
.. code-block:: python
from autogen_agentchat.agents import CodingAssistantAgent, CodeExecutorAgent
- from autogen_agentchat.teams import RoundRobinGroupChat
+ from autogen_agentchat.teams.group_chat import RoundRobinGroupChat
- coding_assistant = CodingAssistantAgent("Coding Assistant", model_client=...)
- executor_agent = CodeExecutorAgent("Code Executor", code_executor=...)
+ coding_assistant = CodingAssistantAgent("Coding_Assistant", model_client=...)
+ executor_agent = CodeExecutorAgent("Code_Executor", code_executor=...)
team = RoundRobinGroupChat([coding_assistant, executor_agent])
await team.run("Write a program that prints 'Hello, world!'")
"""
def __init__(self, participants: List[BaseChatAgent]):
- if len(participants) == 0:
- raise ValueError("At least one participant is required.")
- if len(participants) != len(set(participant.name for participant in participants)):
- raise ValueError("The participant names must be unique.")
- for participant in participants:
- if isinstance(participant, BaseToolUseChatAgent) and not participant.registered_tools:
- raise ValueError(
- f"Participant '{participant.name}' is a tool use agent so it must have registered tools."
- )
- self._participants = participants
- self._team_id = str(uuid.uuid4())
-
- def _create_factory(
- self, parent_topic_type: str, agent: BaseChatAgent, tool_agent_type: AgentType | None
- ) -> Callable[[], BaseChatAgentContainer]:
- def _factory() -> BaseChatAgentContainer:
- id = AgentInstantiationContext.current_agent_id()
- assert id == AgentId(type=agent.name, key=self._team_id)
- container = BaseChatAgentContainer(parent_topic_type, agent, tool_agent_type)
- assert container.id == id
- return container
-
- return _factory
+ super().__init__(participants, group_chat_manager_class=RoundRobinGroupChatManager)
- def _create_tool_agent_factory(
+ def _create_group_chat_manager_factory(
self,
- caller_name: str,
- tools: List[Tool],
- ) -> Callable[[], ToolAgent]:
- def _factory() -> ToolAgent:
- return ToolAgent(f"Tool agent for {caller_name}", tools)
-
- return _factory
-
- async def run(self, task: str) -> TeamRunResult:
- """Run the team and return the result."""
- # Create the runtime.
- runtime = SingleThreadedAgentRuntime()
-
- # Constants for the group chat manager.
- group_chat_manager_agent_type = AgentType("group_chat_manager")
- group_chat_manager_topic_type = group_chat_manager_agent_type.type
- group_topic_type = "round_robin_group_topic"
- team_topic_type = "team_topic"
-
- # Register participants.
- participant_topic_types: List[str] = []
- participant_descriptions: List[str] = []
- for participant in self._participants:
- if isinstance(participant, BaseToolUseChatAgent):
- assert participant.registered_tools is not None and len(participant.registered_tools) > 0
- # Register the tool agent.
- tool_agent_type = await ToolAgent.register(
- runtime,
- f"tool_agent_for_{participant.name}",
- self._create_tool_agent_factory(participant.name, participant.registered_tools),
- )
- # No subscriptions are needed for the tool agent, which will be called via direct messages.
- else:
- # No tool agent is needed.
- tool_agent_type = None
-
- # Use the participant name as the agent type and topic type.
- agent_type = participant.name
- topic_type = participant.name
- # Register the participant factory.
- await BaseChatAgentContainer.register(
- runtime, type=agent_type, factory=self._create_factory(group_topic_type, participant, tool_agent_type)
+ parent_topic_type: str,
+ group_topic_type: str,
+ participant_topic_types: List[str],
+ participant_descriptions: List[str],
+ ) -> Callable[[], RoundRobinGroupChatManager]:
+ def _factory() -> RoundRobinGroupChatManager:
+ return RoundRobinGroupChatManager(
+ parent_topic_type, group_topic_type, participant_topic_types, participant_descriptions
)
- # Add subscriptions for the participant.
- await runtime.add_subscription(TypeSubscription(topic_type=topic_type, agent_type=agent_type))
- await runtime.add_subscription(TypeSubscription(topic_type=group_topic_type, agent_type=agent_type))
- # Add the participant to the lists.
- participant_descriptions.append(participant.description)
- participant_topic_types.append(topic_type)
-
- # Register the group chat manager.
- await RoundRobinGroupChatManager.register(
- runtime,
- type=group_chat_manager_agent_type.type,
- factory=lambda: RoundRobinGroupChatManager(
- parent_topic_type=team_topic_type,
- group_topic_type=group_topic_type,
- participant_topic_types=participant_topic_types,
- participant_descriptions=participant_descriptions,
- ),
- )
- # Add subscriptions for the group chat manager.
- await runtime.add_subscription(
- TypeSubscription(topic_type=group_chat_manager_topic_type, agent_type=group_chat_manager_agent_type.type)
- )
- await runtime.add_subscription(
- TypeSubscription(topic_type=group_topic_type, agent_type=group_chat_manager_agent_type.type)
- )
- await runtime.add_subscription(
- TypeSubscription(topic_type=team_topic_type, agent_type=group_chat_manager_agent_type.type)
- )
-
- group_chat_messages: List[ChatMessage] = []
-
- async def collect_group_chat_messages(
- _runtime: AgentRuntime, id: AgentId, message: ContentPublishEvent, ctx: MessageContext
- ) -> None:
- group_chat_messages.append(message.agent_message)
-
- await ClosureAgent.register(
- runtime,
- type="collect_group_chat_messages",
- closure=collect_group_chat_messages,
- subscriptions=lambda: [
- TypeSubscription(topic_type=group_topic_type, agent_type="collect_group_chat_messages")
- ],
- )
- # Start the runtime.
- runtime.start()
-
- # Run the team by publishing the task to the team topic and then requesting the result.
- team_topic_id = TopicId(type=team_topic_type, source=self._team_id)
- group_chat_manager_topic_id = TopicId(type=group_chat_manager_topic_type, source=self._team_id)
- await runtime.publish_message(
- ContentPublishEvent(agent_message=TextMessage(content=task, source="user")),
- topic_id=team_topic_id,
- )
- await runtime.publish_message(ContentRequestEvent(), topic_id=group_chat_manager_topic_id)
-
- # Wait for the runtime to stop.
- await runtime.stop_when_idle()
-
- return TeamRunResult(messages=group_chat_messages)
+ return _factory
diff --git a/python/packages/autogen-agentchat/src/autogen_agentchat/teams/group_chat/_round_robin_group_chat_manager.py b/python/packages/autogen-agentchat/src/autogen_agentchat/teams/group_chat/_round_robin_group_chat_manager.py
deleted file mode 100644
index 713859340..000000000
--- a/python/packages/autogen-agentchat/src/autogen_agentchat/teams/group_chat/_round_robin_group_chat_manager.py
+++ /dev/null
@@ -1,29 +0,0 @@
-from typing import List
-
-from ...agents import ChatMessage
-from ._base_group_chat_manager import BaseGroupChatManager
-
-
-class RoundRobinGroupChatManager(BaseGroupChatManager):
- """A group chat manager that selects the next speaker in a round-robin fashion."""
-
- def __init__(
- self,
- parent_topic_type: str,
- group_topic_type: str,
- participant_topic_types: List[str],
- participant_descriptions: List[str],
- ):
- super().__init__(
- parent_topic_type,
- group_topic_type,
- participant_topic_types,
- participant_descriptions,
- )
- self._next_speaker_index = 0
-
- async def select_speaker(self, thread: List[ChatMessage]) -> str:
- """Select a speaker from the participants in a round-robin fashion."""
- current_speaker_index = self._next_speaker_index
- self._next_speaker_index = (current_speaker_index + 1) % len(self._participant_topic_types)
- return self._participant_topic_types[current_speaker_index]
diff --git a/python/packages/autogen-agentchat/src/autogen_agentchat/teams/group_chat/_selector_group_chat.py b/python/packages/autogen-agentchat/src/autogen_agentchat/teams/group_chat/_selector_group_chat.py
new file mode 100644
index 000000000..0d6df0212
--- /dev/null
+++ b/python/packages/autogen-agentchat/src/autogen_agentchat/teams/group_chat/_selector_group_chat.py
@@ -0,0 +1,221 @@
+import logging
+import re
+from typing import Callable, Dict, List
+
+from autogen_core.components.models import ChatCompletionClient, SystemMessage
+
+from ...agents import BaseChatAgent, MultiModalMessage, StopMessage, TextMessage
+from .._events import ContentPublishEvent, SelectSpeakerEvent
+from .._logging import EVENT_LOGGER_NAME, TRACE_LOGGER_NAME
+from ._base_group_chat import BaseGroupChat
+from ._base_group_chat_manager import BaseGroupChatManager
+
+trace_logger = logging.getLogger(TRACE_LOGGER_NAME)
+event_logger = logging.getLogger(EVENT_LOGGER_NAME)
+
+
+class SelectorGroupChatManager(BaseGroupChatManager):
+ """A group chat manager that selects the next speaker using a ChatCompletion
+ model."""
+
+ def __init__(
+ self,
+ parent_topic_type: str,
+ group_topic_type: str,
+ participant_topic_types: List[str],
+ participant_descriptions: List[str],
+ model_client: ChatCompletionClient,
+ selector_prompt: str,
+ allow_repeated_speaker: bool,
+ ) -> None:
+ super().__init__(
+ parent_topic_type,
+ group_topic_type,
+ participant_topic_types,
+ participant_descriptions,
+ )
+ self._model_client = model_client
+ self._selector_prompt = selector_prompt
+ self._previous_speaker: str | None = None
+ self._allow_repeated_speaker = allow_repeated_speaker
+
+ async def select_speaker(self, thread: List[ContentPublishEvent]) -> str:
+ """Selects the next speaker in a group chat using a ChatCompletion client.
+
+ A key assumption is that the agent type is the same as the topic type, which we use as the agent name.
+ """
+ history_messages: List[str] = []
+ for event in thread:
+ msg = event.agent_message
+ source = event.source
+ if source is None:
+ message = ""
+ else:
+ # The agent type must be the same as the topic type, which we use as the agent name.
+ message = f"{source.type}:"
+ if isinstance(msg, TextMessage | StopMessage):
+ message += f" {msg.content}"
+ elif isinstance(msg, MultiModalMessage):
+ for item in msg.content:
+ if isinstance(item, str):
+ message += f" {item}"
+ else:
+ message += " [Image]"
+ else:
+ raise ValueError(f"Unexpected message type in selector: {type(msg)}")
+ history_messages.append(message)
+ history = "\n".join(history_messages)
+
+ # Construct agent roles, we are using the participant topic type as the agent name.
+ roles = "\n".join(
+ [
+ f"{topic_type}: {description}".strip()
+ for topic_type, description in zip(
+ self._participant_topic_types, self._participant_descriptions, strict=True
+ )
+ ]
+ )
+
+ # Construct agent list to be selected, skip the previous speaker if not allowed.
+ if self._previous_speaker is not None and not self._allow_repeated_speaker:
+ participants = [p for p in self._participant_topic_types if p != self._previous_speaker]
+ else:
+ participants = self._participant_topic_types
+ assert len(participants) > 0
+
+ # Select the next speaker.
+ if len(participants) > 1:
+ select_speaker_prompt = self._selector_prompt.format(
+ roles=roles, participants=str(participants), history=history
+ )
+ select_speaker_messages = [SystemMessage(select_speaker_prompt)]
+ response = await self._model_client.create(messages=select_speaker_messages)
+ assert isinstance(response.content, str)
+ mentions = self._mentioned_agents(response.content, self._participant_topic_types)
+ if len(mentions) != 1:
+ raise ValueError(f"Expected exactly one agent to be mentioned, but got {mentions}")
+ agent_name = list(mentions.keys())[0]
+ if (
+ not self._allow_repeated_speaker
+ and self._previous_speaker is not None
+ and agent_name == self._previous_speaker
+ ):
+ trace_logger.warning(f"Selector selected the previous speaker: {agent_name}")
+ else:
+ agent_name = participants[0]
+ self._previous_speaker = agent_name
+ event_logger.info(SelectSpeakerEvent(selected_speaker=agent_name, source=self.id))
+ return agent_name
+
+ def _mentioned_agents(self, message_content: str, agent_names: List[str]) -> Dict[str, int]:
+ """Counts the number of times each agent is mentioned in the provided message content.
+ Agent names will match under any of the following conditions (all case-sensitive):
+ - Exact name match
+ - If the agent name has underscores it will match with spaces instead (e.g. 'Story_writer' == 'Story writer')
+ - If the agent name has underscores it will match with '\\_' instead of '_' (e.g. 'Story_writer' == 'Story\\_writer')
+
+ Args:
+ message_content (Union[str, List]): The content of the message, either as a single string or a list of strings.
+ agents (List[Agent]): A list of Agent objects, each having a 'name' attribute to be searched in the message content.
+
+ Returns:
+ Dict: a counter for mentioned agents.
+ """
+ mentions: Dict[str, int] = dict()
+ for name in agent_names:
+ # Finds agent mentions, taking word boundaries into account,
+ # accommodates escaping underscores and underscores as spaces
+ regex = (
+ r"(?<=\W)("
+ + re.escape(name)
+ + r"|"
+ + re.escape(name.replace("_", " "))
+ + r"|"
+ + re.escape(name.replace("_", r"\_"))
+ + r")(?=\W)"
+ )
+ count = len(re.findall(regex, f" {message_content} ")) # Pad the message to help with matching
+ if count > 0:
+ mentions[name] = count
+ return mentions
+
+
+class SelectorGroupChat(BaseGroupChat):
+ """A group chat team that have participants takes turn to publish a message
+ to all, using a ChatCompletion model to select the next speaker after each message.
+
+ Args:
+ participants (List[BaseChatAgent]): The participants in the group chat,
+ must have unique names and at least two participants.
+ model_client (ChatCompletionClient): The ChatCompletion model client used
+ to select the next speaker.
+ selector_prompt (str, optional): The prompt template to use for selecting the next speaker.
+ Must contain '{roles}', '{participants}', and '{history}' to be filled in.
+ allow_repeated_speaker (bool, optional): Whether to allow the same speaker to be selected
+ consecutively. Defaults to False.
+
+ Raises:
+ ValueError: If the number of participants is less than two or if the selector prompt is invalid.
+
+ Examples:
+
+ A team with multiple participants:
+
+ .. code-block:: python
+
+ from autogen_agentchat.agents import ToolUseAssistantAgent
+ from autogen_agentchat.teams.group_chat import SelectorGroupChat
+
+ travel_advisor = ToolUseAssistantAgent("Travel_Advisor", model_client=..., registered_tools=...)
+ hotel_agent = ToolUseAssistantAgent("Hotel_Agent", model_client=..., registered_tools=...)
+ flight_agent = ToolUseAssistantAgent("Flight_Agent", model_client=..., registered_tools=...)
+ team = SelectorGroupChat([travel_advisor, hotel_agent, flight_agent], model_client=...)
+ await team.run("Book a 3-day trip to new york.")
+ """
+
+ def __init__(
+ self,
+ participants: List[BaseChatAgent],
+ model_client: ChatCompletionClient,
+ *,
+ selector_prompt: str = """You are in a role play game. The following roles are available:
+{roles}.
+Read the following conversation. Then select the next role from {participants} to play. Only return the role.
+
+{history}
+
+Read the above conversation. Then select the next role from {participants} to play. Only return the role.
+""",
+ allow_repeated_speaker: bool = False,
+ ):
+ super().__init__(participants, group_chat_manager_class=SelectorGroupChatManager)
+ # Validate the participants.
+ if len(participants) < 2:
+ raise ValueError("At least two participants are required for SelectorGroupChat.")
+ # Validate the selector prompt.
+ if "{roles}" not in selector_prompt:
+ raise ValueError("The selector prompt must contain '{roles}'")
+ if "{participants}" not in selector_prompt:
+ raise ValueError("The selector prompt must contain '{participants}'")
+ if "{history}" not in selector_prompt:
+ raise ValueError("The selector prompt must contain '{history}'")
+ self._selector_prompt = selector_prompt
+ self._model_client = model_client
+ self._allow_repeated_speaker = allow_repeated_speaker
+
+ def _create_group_chat_manager_factory(
+ self,
+ parent_topic_type: str,
+ group_topic_type: str,
+ participant_topic_types: List[str],
+ participant_descriptions: List[str],
+ ) -> Callable[[], BaseGroupChatManager]:
+ return lambda: SelectorGroupChatManager(
+ parent_topic_type,
+ group_topic_type,
+ participant_topic_types,
+ participant_descriptions,
+ self._model_client,
+ self._selector_prompt,
+ self._allow_repeated_speaker,
+ )
diff --git a/python/packages/autogen-agentchat/tests/test_group_chat.py b/python/packages/autogen-agentchat/tests/test_group_chat.py
index 7c2800c2b..7fabe8253 100644
--- a/python/packages/autogen-agentchat/tests/test_group_chat.py
+++ b/python/packages/autogen-agentchat/tests/test_group_chat.py
@@ -9,9 +9,11 @@ from autogen_agentchat.agents import (
ChatMessage,
CodeExecutorAgent,
CodingAssistantAgent,
+ StopMessage,
+ TextMessage,
ToolUseAssistantAgent,
)
-from autogen_agentchat.teams.group_chat import RoundRobinGroupChat
+from autogen_agentchat.teams.group_chat import RoundRobinGroupChat, SelectorGroupChat
from autogen_core.base import CancellationToken
from autogen_core.components import FunctionCall
from autogen_core.components.code_executor import LocalCommandLineCodeExecutor
@@ -40,8 +42,31 @@ class _MockChatCompletion:
class _EchoAgent(BaseChatAgent):
+ def __init__(self, name: str, description: str) -> None:
+ super().__init__(name, description)
+ self._last_message: str | None = None
+
+ async def on_messages(self, messages: Sequence[ChatMessage], cancellation_token: CancellationToken) -> ChatMessage:
+ if len(messages) > 0:
+ assert isinstance(messages[0], TextMessage)
+ self._last_message = messages[0].content
+ return TextMessage(content=messages[0].content, source=self.name)
+ else:
+ assert self._last_message is not None
+ return TextMessage(content=self._last_message, source=self.name)
+
+
+class _StopAgent(_EchoAgent):
+ def __init__(self, name: str, description: str, *, stop_at: int = 1) -> None:
+ super().__init__(name, description)
+ self._count = 0
+ self._stop_at = stop_at
+
async def on_messages(self, messages: Sequence[ChatMessage], cancellation_token: CancellationToken) -> ChatMessage:
- return messages[-1]
+ self._count += 1
+ if self._count < self._stop_at:
+ return await super().on_messages(messages, cancellation_token)
+ return StopMessage(content="TERMINATE", source=self.name)
def _pass_function(input: str) -> str:
@@ -187,3 +212,166 @@ async def test_round_robin_group_chat_with_tools(monkeypatch: pytest.MonkeyPatch
assert context[2].content[0].content == "pass"
assert context[2].content[0].call_id == "1"
assert context[3].content == "Hello"
+
+
+async def test_selector_group_chat(monkeypatch: pytest.MonkeyPatch) -> None:
+ model = "gpt-4o-2024-05-13"
+ chat_completions = [
+ ChatCompletion(
+ id="id2",
+ choices=[
+ Choice(finish_reason="stop", index=0, message=ChatCompletionMessage(content="agent3", role="assistant"))
+ ],
+ created=0,
+ model=model,
+ object="chat.completion",
+ usage=CompletionUsage(prompt_tokens=0, completion_tokens=0, total_tokens=0),
+ ),
+ ChatCompletion(
+ id="id2",
+ choices=[
+ Choice(finish_reason="stop", index=0, message=ChatCompletionMessage(content="agent2", role="assistant"))
+ ],
+ created=0,
+ model=model,
+ object="chat.completion",
+ usage=CompletionUsage(prompt_tokens=0, completion_tokens=0, total_tokens=0),
+ ),
+ ChatCompletion(
+ id="id2",
+ choices=[
+ Choice(finish_reason="stop", index=0, message=ChatCompletionMessage(content="agent1", role="assistant"))
+ ],
+ created=0,
+ model=model,
+ object="chat.completion",
+ usage=CompletionUsage(prompt_tokens=0, completion_tokens=0, total_tokens=0),
+ ),
+ ChatCompletion(
+ id="id2",
+ choices=[
+ Choice(finish_reason="stop", index=0, message=ChatCompletionMessage(content="agent2", role="assistant"))
+ ],
+ created=0,
+ model=model,
+ object="chat.completion",
+ usage=CompletionUsage(prompt_tokens=0, completion_tokens=0, total_tokens=0),
+ ),
+ ChatCompletion(
+ id="id2",
+ choices=[
+ Choice(finish_reason="stop", index=0, message=ChatCompletionMessage(content="agent1", role="assistant"))
+ ],
+ created=0,
+ model=model,
+ object="chat.completion",
+ usage=CompletionUsage(prompt_tokens=0, completion_tokens=0, total_tokens=0),
+ ),
+ ]
+ mock = _MockChatCompletion(chat_completions)
+ monkeypatch.setattr(AsyncCompletions, "create", mock.mock_create)
+
+ agent1 = _StopAgent("agent1", description="echo agent 1", stop_at=2)
+ agent2 = _EchoAgent("agent2", description="echo agent 2")
+ agent3 = _EchoAgent("agent3", description="echo agent 3")
+ team = SelectorGroupChat(
+ participants=[agent1, agent2, agent3],
+ model_client=OpenAIChatCompletionClient(model=model, api_key=""),
+ )
+ result = await team.run("Write a program that prints 'Hello, world!'")
+ assert len(result.messages) == 6
+ assert result.messages[0].content == "Write a program that prints 'Hello, world!'"
+ assert result.messages[1].source == "agent3"
+ assert result.messages[2].source == "agent2"
+ assert result.messages[3].source == "agent1"
+ assert result.messages[4].source == "agent2"
+ assert result.messages[5].source == "agent1"
+
+
+async def test_selector_group_chat_two_speakers(monkeypatch: pytest.MonkeyPatch) -> None:
+ model = "gpt-4o-2024-05-13"
+ chat_completions = [
+ ChatCompletion(
+ id="id2",
+ choices=[
+ Choice(finish_reason="stop", index=0, message=ChatCompletionMessage(content="agent2", role="assistant"))
+ ],
+ created=0,
+ model=model,
+ object="chat.completion",
+ usage=CompletionUsage(prompt_tokens=0, completion_tokens=0, total_tokens=0),
+ ),
+ ]
+ mock = _MockChatCompletion(chat_completions)
+ monkeypatch.setattr(AsyncCompletions, "create", mock.mock_create)
+
+ agent1 = _StopAgent("agent1", description="echo agent 1", stop_at=2)
+ agent2 = _EchoAgent("agent2", description="echo agent 2")
+ team = SelectorGroupChat(
+ participants=[agent1, agent2],
+ model_client=OpenAIChatCompletionClient(model=model, api_key=""),
+ )
+ result = await team.run("Write a program that prints 'Hello, world!'")
+ assert len(result.messages) == 5
+ assert result.messages[0].content == "Write a program that prints 'Hello, world!'"
+ assert result.messages[1].source == "agent2"
+ assert result.messages[2].source == "agent1"
+ assert result.messages[3].source == "agent2"
+ assert result.messages[4].source == "agent1"
+ # only one chat completion was called
+ assert mock._curr_index == 1 # pyright: ignore
+
+
+async def test_selector_group_chat_two_speakers_allow_repeated(monkeypatch: pytest.MonkeyPatch) -> None:
+ model = "gpt-4o-2024-05-13"
+ chat_completions = [
+ ChatCompletion(
+ id="id2",
+ choices=[
+ Choice(finish_reason="stop", index=0, message=ChatCompletionMessage(content="agent2", role="assistant"))
+ ],
+ created=0,
+ model=model,
+ object="chat.completion",
+ usage=CompletionUsage(prompt_tokens=0, completion_tokens=0, total_tokens=0),
+ ),
+ ChatCompletion(
+ id="id2",
+ choices=[
+ Choice(finish_reason="stop", index=0, message=ChatCompletionMessage(content="agent2", role="assistant"))
+ ],
+ created=0,
+ model=model,
+ object="chat.completion",
+ usage=CompletionUsage(prompt_tokens=0, completion_tokens=0, total_tokens=0),
+ ),
+ ChatCompletion(
+ id="id2",
+ choices=[
+ Choice(finish_reason="stop", index=0, message=ChatCompletionMessage(content="agent1", role="assistant"))
+ ],
+ created=0,
+ model=model,
+ object="chat.completion",
+ usage=CompletionUsage(prompt_tokens=0, completion_tokens=0, total_tokens=0),
+ ),
+ ]
+ mock = _MockChatCompletion(chat_completions)
+ monkeypatch.setattr(AsyncCompletions, "create", mock.mock_create)
+
+ agent1 = _StopAgent("agent1", description="echo agent 1", stop_at=1)
+ agent2 = _EchoAgent("agent2", description="echo agent 2")
+ team = SelectorGroupChat(
+ participants=[agent1, agent2],
+ model_client=OpenAIChatCompletionClient(model=model, api_key=""),
+ allow_repeated_speaker=True,
+ )
+ result = await team.run("Write a program that prints 'Hello, world!'")
+ assert len(result.messages) == 4
+ assert result.messages[0].content == "Write a program that prints 'Hello, world!'"
+ assert result.messages[1].source == "agent2"
+ assert result.messages[2].source == "agent2"
+ assert result.messages[3].source == "agent1"
diff --git a/python/packages/autogen-core/docs/src/agentchat-user-guide/guides/selector-group-chat.ipynb b/python/packages/autogen-core/docs/src/agentchat-user-guide/guides/selector-group-chat.ipynb
new file mode 100644
index 000000000..cc8bd6c26
--- /dev/null
+++ b/python/packages/autogen-core/docs/src/agentchat-user-guide/guides/selector-group-chat.ipynb
@@ -0,0 +1,330 @@
+{
+ "cells": [
+ {
+ "cell_type": "markdown",
+ "metadata": {},
+ "source": [
+ "# Selector Group Chat"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 13,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "import asyncio\n",
+ "from typing import Sequence\n",
+ "\n",
+ "from autogen_agentchat.agents import (\n",
+ " BaseChatAgent,\n",
+ " ChatMessage,\n",
+ " CodingAssistantAgent,\n",
+ " StopMessage,\n",
+ " TextMessage,\n",
+ " ToolUseAssistantAgent,\n",
+ ")\n",
+ "from autogen_agentchat.teams.group_chat import SelectorGroupChat\n",
+ "from autogen_core.base import CancellationToken\n",
+ "from autogen_core.components.models import OpenAIChatCompletionClient\n",
+ "from autogen_core.components.tools import FunctionTool"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 14,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "class UserProxyAgent(BaseChatAgent):\n",
+ " def __init__(self, name: str) -> None:\n",
+ " super().__init__(name, \"A human user.\")\n",
+ "\n",
+ " async def on_messages(self, messages: Sequence[ChatMessage], cancellation_token: CancellationToken) -> ChatMessage:\n",
+ " user_input = await asyncio.get_event_loop().run_in_executor(None, input, \"Enter your response: \")\n",
+ " if \"TERMINATE\" in user_input:\n",
+ " return StopMessage(content=\"User has terminated the conversation.\", source=self.name)\n",
+ " return TextMessage(content=user_input, source=self.name)"
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 15,
+ "metadata": {},
+ "outputs": [],
+ "source": [
+ "async def flight_search(start: str, destination: str, date: str) -> str:\n",
+ " return \"\\n\".join(\n",
+ " [\n",
+ " f\"AC24 from {start} to {destination} on {date} is $500\",\n",
+ " f\"UA23 from {start} to {destination} on {date} is $450\",\n",
+ " f\"AL21 from {start} to {destination} on {date} is $400\",\n",
+ " ]\n",
+ " )\n",
+ "\n",
+ "\n",
+ "async def flight_booking(flight: str, date: str) -> str:\n",
+ " return f\"Booked flight {flight} on {date}\""
+ ]
+ },
+ {
+ "cell_type": "code",
+ "execution_count": 16,
+ "metadata": {},
+ "outputs": [
+ {
+ "name": "stdout",
+ "output_type": "stream",
+ "text": [
+ "\n",
+ "--------------------------------------------------------------------------- \n",
+ "\u001b[91m[2024-10-08T10:10:50.523469]:\u001b[0m\n",
+ "\n",
+ "Help user plan a trip and book a flight.\n",
+ "--------------------------------------------------------------------------- \n",
+ "\u001b[91m[2024-10-08T10:10:51.234858], group_chat_manager:\u001b[0m\n",
+ "\n",
+ "Selected next speaker: User\n",
+ "--------------------------------------------------------------------------- \n",
+ "\u001b[91m[2024-10-08T10:10:55.437051], User:\u001b[0m\n",
+ "\n",
+ "\n",
+ "--------------------------------------------------------------------------- \n",
+ "\u001b[91m[2024-10-08T10:10:55.957366], group_chat_manager:\u001b[0m\n",
+ "\n",
+ "Selected next speaker: TravelAssistant\n",
+ "--------------------------------------------------------------------------- \n",
+ "\u001b[91m[2024-10-08T10:10:58.291558], TravelAssistant:\u001b[0m\n",
+ "\n",
+ "Sure! I can help you plan your trip and provide information on booking a flight. Could you please provide me with the following details?\n",
+ "\n",
+ "1. Your departure city.\n",
+ "2. Your destination.\n",
+ "3. Travel dates (departure and return).\n",
+ "4. Number of travelers and their ages.\n",
+ "5. Any specific preferences or activities you would like to include in your trip?\n",
+ "\n",
+ "Once I have that information, we can get started!\n",
+ "--------------------------------------------------------------------------- \n",
+ "\u001b[91m[2024-10-08T10:10:58.827503], group_chat_manager:\u001b[0m\n",
+ "\n",
+ "Selected next speaker: User\n",
+ "--------------------------------------------------------------------------- \n",
+ "\u001b[91m[2024-10-08T10:11:07.996036], User:\u001b[0m\n",
+ "\n",
+ "Going to toronto from new york \n",
+ "--------------------------------------------------------------------------- \n",
+ "\u001b[91m[2024-10-08T10:11:08.623692], group_chat_manager:\u001b[0m\n",
+ "\n",
+ "Selected next speaker: TravelAssistant\n",
+ "--------------------------------------------------------------------------- \n",
+ "\u001b[91m[2024-10-08T10:11:10.605232], TravelAssistant:\u001b[0m\n",
+ "\n",
+ "Great! Here are a few more details I need to help you plan your trip:\n",
+ "\n",
+ "1. **Departure dates:** When do you plan to leave New York and when will you return?\n",
+ "2. **Number of travelers:** How many people will be traveling with you, and what are their ages?\n",
+ "3. **Preferences:** Do you have any specific preferences for flight times or activities in Toronto? \n",
+ "\n",
+ "Once I have this information, I can assist you further!\n",
+ "--------------------------------------------------------------------------- \n",
+ "\u001b[91m[2024-10-08T10:11:11.070495], group_chat_manager:\u001b[0m\n",
+ "\n",
+ "Selected next speaker: User\n",
+ "--------------------------------------------------------------------------- \n",
+ "\u001b[91m[2024-10-08T10:11:26.768126], User:\u001b[0m\n",
+ "\n",
+ "leaving on december 12 and returning on 17, 2024\n",
+ "--------------------------------------------------------------------------- \n",
+ "\u001b[91m[2024-10-08T10:11:27.365051], group_chat_manager:\u001b[0m\n",
+ "\n",
+ "Selected next speaker: TravelAssistant\n",
+ "--------------------------------------------------------------------------- \n",
+ "\u001b[91m[2024-10-08T10:11:30.335893], TravelAssistant:\u001b[0m\n",
+ "\n",
+ "Thank you for the details! Here’s a summary of the trip so far:\n",
+ "\n",
+ "- **Departure City:** New York\n",
+ "- **Destination:** Toronto\n",
+ "- **Departure Date:** December 12, 2024\n",
+ "- **Return Date:** December 17, 2024\n",
+ "\n",
+ "Now, could you please provide the following additional information?\n",
+ "\n",
+ "1. **Number of travelers and their ages:** How many people will be traveling with you?\n",
+ "2. **Preferences for flights:** Any preferences for morning, afternoon, or evening flights?\n",
+ "3. **Activities:** Any specific activities or attractions you’d like to prioritize in Toronto?\n",
+ "\n",
+ "With this information, I can assist you in finding suitable flights and offer activity suggestions!\n",
+ "--------------------------------------------------------------------------- \n",
+ "\u001b[91m[2024-10-08T10:11:30.822862], group_chat_manager:\u001b[0m\n",
+ "\n",
+ "Selected next speaker: User\n",
+ "--------------------------------------------------------------------------- \n",
+ "\u001b[91m[2024-10-08T10:11:39.547965], User:\u001b[0m\n",
+ "\n",
+ "just myself\n",
+ "--------------------------------------------------------------------------- \n",
+ "\u001b[91m[2024-10-08T10:11:40.110527], group_chat_manager:\u001b[0m\n",
+ "\n",
+ "Selected next speaker: FlightBroker\n",
+ "--------------------------------------------------------------------------- \n",
+ "\u001b[91m[2024-10-08T10:11:45.764773], FlightBroker:\u001b[0m\n",
+ "\n",
+ "Thank you for the information! Here’s what I have so far for your trip:\n",
+ "\n",
+ "- **Departure City:** New York\n",
+ "- **Destination:** Toronto\n",
+ "- **Departure Date:** December 12, 2024\n",
+ "- **Return Date:** December 17, 2024\n",
+ "- **Number of Travelers:** 1 (yourself)\n",
+ "\n",
+ "Now, do you have any preferences for flight times (morning, afternoon, or evening)? Additionally, are there any specific activities or attractions you would like to include in your trip to Toronto? \n",
+ "\n",
+ "Once I have that, I can start searching for flights!\n",
+ "--------------------------------------------------------------------------- \n",
+ "\u001b[91m[2024-10-08T10:11:46.363784], group_chat_manager:\u001b[0m\n",
+ "\n",
+ "Selected next speaker: User\n",
+ "--------------------------------------------------------------------------- \n",
+ "\u001b[91m[2024-10-08T10:11:59.508971], User:\u001b[0m\n",
+ "\n",
+ "any time is fine\n",
+ "--------------------------------------------------------------------------- \n",
+ "\u001b[91m[2024-10-08T10:12:00.072654], group_chat_manager:\u001b[0m\n",
+ "\n",
+ "Selected next speaker: FlightBroker\n",
+ "--------------------------------------------------------------------------- \n",
+ "\u001b[91m[2024-10-08T10:12:01.847222], FlightBroker:\u001b[0m\n",
+ "\n",
+ "[FunctionCall(id='call_lpuPUlo9k3p4VeX0h6jO8yJg', arguments='{\"start\":\"New York\",\"destination\":\"Toronto\",\"date\":\"2024-12-12\"}', name='flight_search')]\n",
+ "--------------------------------------------------------------------------- \n",
+ "\u001b[91m[2024-10-08T10:12:01.848179], tool_agent_for_FlightBroker:\u001b[0m\n",
+ "\n",
+ "[FunctionExecutionResult(content='AC24 from New York to Toronto on 2024-12-12 is $500\\nUA23 from New York to Toronto on 2024-12-12 is $450\\nAL21 from New York to Toronto on 2024-12-12 is $400', call_id='call_lpuPUlo9k3p4VeX0h6jO8yJg')]\n",
+ "--------------------------------------------------------------------------- \n",
+ "\u001b[91m[2024-10-08T10:12:03.512522], FlightBroker:\u001b[0m\n",
+ "\n",
+ "[FunctionCall(id='call_dxxmiR6hVBL9QuneJGNnleR0', arguments='{\"start\":\"Toronto\",\"destination\":\"New York\",\"date\":\"2024-12-17\"}', name='flight_search')]\n",
+ "--------------------------------------------------------------------------- \n",
+ "\u001b[91m[2024-10-08T10:12:03.513405], tool_agent_for_FlightBroker:\u001b[0m\n",
+ "\n",
+ "[FunctionExecutionResult(content='AC24 from Toronto to New York on 2024-12-17 is $500\\nUA23 from Toronto to New York on 2024-12-17 is $450\\nAL21 from Toronto to New York on 2024-12-17 is $400', call_id='call_dxxmiR6hVBL9QuneJGNnleR0')]\n",
+ "--------------------------------------------------------------------------- \n",
+ "\u001b[91m[2024-10-08T10:12:07.337638], FlightBroker:\u001b[0m\n",
+ "\n",
+ "I found some flight options for your trip from New York to Toronto and back. Here are the details:\n",
+ "\n",
+ "### Departure: New York to Toronto on December 12, 2024\n",
+ "1. **Flight AC24**\n",
+ " - Price: $500\n",
+ "2. **Flight UA23**\n",
+ " - Price: $450\n",
+ "3. **Flight AL21**\n",
+ " - Price: $400\n",
+ "\n",
+ "### Return: Toronto to New York on December 17, 2024\n",
+ "1. **Flight AC24**\n",
+ " - Price: $500\n",
+ "2. **Flight UA23**\n",
+ " - Price: $450\n",
+ "3. **Flight AL21**\n",
+ " - Price: $400\n",
+ "\n",
+ "Would you like to book any of these flights? If so, please let me know which flight you'd prefer for both the departure and return!\n",
+ "--------------------------------------------------------------------------- \n",
+ "\u001b[91m[2024-10-08T10:12:07.870903], group_chat_manager:\u001b[0m\n",
+ "\n",
+ "Selected next speaker: User\n",
+ "--------------------------------------------------------------------------- \n",
+ "\u001b[91m[2024-10-08T10:12:22.910467], User:\u001b[0m\n",
+ "\n",
+ "Book the AC flight leaving and UA flight returning\n",
+ "--------------------------------------------------------------------------- \n",
+ "\u001b[91m[2024-10-08T10:12:23.450871], group_chat_manager:\u001b[0m\n",
+ "\n",
+ "Selected next speaker: FlightBroker\n",
+ "--------------------------------------------------------------------------- \n",
+ "\u001b[91m[2024-10-08T10:12:27.273108], FlightBroker:\u001b[0m\n",
+ "\n",
+ "[FunctionCall(id='call_wqkaIBdYjWklWG0GQkYz7FZ0', arguments='{\"flight\": \"AC24\", \"date\": \"2024-12-12\"}', name='flight_booking'), FunctionCall(id='call_QZKtPHpbq2QzNi5y6OgfTcsd', arguments='{\"flight\": \"UA23\", \"date\": \"2024-12-17\"}', name='flight_booking')]\n",
+ "--------------------------------------------------------------------------- \n",
+ "\u001b[91m[2024-10-08T10:12:27.274111], tool_agent_for_FlightBroker:\u001b[0m\n",
+ "\n",
+ "[FunctionExecutionResult(content='Booked flight AC24 on 2024-12-12', call_id='call_wqkaIBdYjWklWG0GQkYz7FZ0'), FunctionExecutionResult(content='Booked flight UA23 on 2024-12-17', call_id='call_QZKtPHpbq2QzNi5y6OgfTcsd')]\n",
+ "--------------------------------------------------------------------------- \n",
+ "\u001b[91m[2024-10-08T10:12:29.585911], FlightBroker:\u001b[0m\n",
+ "\n",
+ "Your flights have been successfully booked!\n",
+ "\n",
+ "- **Departure Flight:** AC24 from New York to Toronto on December 12, 2024.\n",
+ "- **Return Flight:** UA23 from Toronto to New York on December 17, 2024.\n",
+ "\n",
+ "If you need any further assistance with your trip or have any questions about activities in Toronto, feel free to ask! Safe travels!\n",
+ "--------------------------------------------------------------------------- \n",
+ "\u001b[91m[2024-10-08T10:12:30.242282], group_chat_manager:\u001b[0m\n",
+ "\n",
+ "Selected next speaker: User\n",
+ "--------------------------------------------------------------------------- \n",
+ "\u001b[91m[2024-10-08T10:12:39.715695], User:\u001b[0m\n",
+ "\n",
+ "User has terminated the conversation."
+ ]
+ },
+ {
+ "data": {
+ "text/plain": [
+ "TeamRunResult(messages=[TextMessage(source='user', content='Help user plan a trip and book a flight.'), TextMessage(source='User', content=''), TextMessage(source='TravelAssistant', content='Sure! I can help you plan your trip and provide information on booking a flight. Could you please provide me with the following details?\\n\\n1. Your departure city.\\n2. Your destination.\\n3. Travel dates (departure and return).\\n4. Number of travelers and their ages.\\n5. Any specific preferences or activities you would like to include in your trip?\\n\\nOnce I have that information, we can get started!'), TextMessage(source='User', content='Going to toronto from new york '), TextMessage(source='TravelAssistant', content='Great! Here are a few more details I need to help you plan your trip:\\n\\n1. **Departure dates:** When do you plan to leave New York and when will you return?\\n2. **Number of travelers:** How many people will be traveling with you, and what are their ages?\\n3. **Preferences:** Do you have any specific preferences for flight times or activities in Toronto? \\n\\nOnce I have this information, I can assist you further!'), TextMessage(source='User', content='leaving on december 12 and returning on 17, 2024'), TextMessage(source='TravelAssistant', content='Thank you for the details! Here’s a summary of the trip so far:\\n\\n- **Departure City:** New York\\n- **Destination:** Toronto\\n- **Departure Date:** December 12, 2024\\n- **Return Date:** December 17, 2024\\n\\nNow, could you please provide the following additional information?\\n\\n1. **Number of travelers and their ages:** How many people will be traveling with you?\\n2. **Preferences for flights:** Any preferences for morning, afternoon, or evening flights?\\n3. **Activities:** Any specific activities or attractions you’d like to prioritize in Toronto?\\n\\nWith this information, I can assist you in finding suitable flights and offer activity suggestions!'), TextMessage(source='User', content='just myself'), TextMessage(source='FlightBroker', content='Thank you for the information! Here’s what I have so far for your trip:\\n\\n- **Departure City:** New York\\n- **Destination:** Toronto\\n- **Departure Date:** December 12, 2024\\n- **Return Date:** December 17, 2024\\n- **Number of Travelers:** 1 (yourself)\\n\\nNow, do you have any preferences for flight times (morning, afternoon, or evening)? Additionally, are there any specific activities or attractions you would like to include in your trip to Toronto? \\n\\nOnce I have that, I can start searching for flights!'), TextMessage(source='User', content='any time is fine'), TextMessage(source='FlightBroker', content=\"I found some flight options for your trip from New York to Toronto and back. Here are the details:\\n\\n### Departure: New York to Toronto on December 12, 2024\\n1. **Flight AC24**\\n - Price: $500\\n2. **Flight UA23**\\n - Price: $450\\n3. **Flight AL21**\\n - Price: $400\\n\\n### Return: Toronto to New York on December 17, 2024\\n1. **Flight AC24**\\n - Price: $500\\n2. **Flight UA23**\\n - Price: $450\\n3. **Flight AL21**\\n - Price: $400\\n\\nWould you like to book any of these flights? If so, please let me know which flight you'd prefer for both the departure and return!\"), TextMessage(source='User', content='Book the AC flight leaving and UA flight returning'), TextMessage(source='FlightBroker', content='Your flights have been successfully booked!\\n\\n- **Departure Flight:** AC24 from New York to Toronto on December 12, 2024.\\n- **Return Flight:** UA23 from Toronto to New York on December 17, 2024.\\n\\nIf you need any further assistance with your trip or have any questions about activities in Toronto, feel free to ask! Safe travels!'), StopMessage(source='User', content='User has terminated the conversation.')])"
+ ]
+ },
+ "execution_count": 16,
+ "metadata": {},
+ "output_type": "execute_result"
+ }
+ ],
+ "source": [
+ "user_proxy = UserProxyAgent(\"User\")\n",
+ "flight_broker = ToolUseAssistantAgent(\n",
+ " \"FlightBroker\",\n",
+ " description=\"An assistant for booking flights\",\n",
+ " model_client=OpenAIChatCompletionClient(model=\"gpt-4o-mini\"),\n",
+ " registered_tools=[\n",
+ " FunctionTool(flight_search, description=\"Search for flights\"),\n",
+ " FunctionTool(flight_booking, description=\"Book a flight\"),\n",
+ " ],\n",
+ ")\n",
+ "travel_assistant = CodingAssistantAgent(\n",
+ " \"TravelAssistant\",\n",
+ " description=\"A travel assistant\",\n",
+ " model_client=OpenAIChatCompletionClient(model=\"gpt-4o-mini\"),\n",
+ " system_message=\"You are a travel assistant.\",\n",
+ ")\n",
+ "team = SelectorGroupChat(\n",
+ " [user_proxy, flight_broker, travel_assistant], model_client=OpenAIChatCompletionClient(model=\"gpt-4o-mini\")\n",
+ ")\n",
+ "await team.run(\"Help user plan a trip and book a flight.\")"
+ ]
+ }
+ ],
+ "metadata": {
+ "kernelspec": {
+ "display_name": ".venv",
+ "language": "python",
+ "name": "python3"
+ },
+ "language_info": {
+ "codemirror_mode": {
+ "name": "ipython",
+ "version": 3
+ },
+ "file_extension": ".py",
+ "mimetype": "text/x-python",
+ "name": "python",
+ "nbconvert_exporter": "python",
+ "pygments_lexer": "ipython3",
+ "version": "3.12.6"
+ }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}
diff --git a/python/packages/autogen-core/docs/src/agentchat-user-guide/index.md b/python/packages/autogen-core/docs/src/agentchat-user-guide/index.md
index 1a6a6df00..f4f12a3db 100644
--- a/python/packages/autogen-core/docs/src/agentchat-user-guide/index.md
+++ b/python/packages/autogen-core/docs/src/agentchat-user-guide/index.md
@@ -18,4 +18,5 @@ myst:
guides/quickstart
guides/tool_use
+guides/selector-group-chat
```