A programming framework for agentic AI
feat: Pause and Resume for AgentChat Teams and Agents (#5887)
Eric Zhu58a558354930
diff --git a/python/packages/autogen-agentchat/src/autogen_agentchat/agents/_base_chat_agent.py b/python/packages/autogen-agentchat/src/autogen_agentchat/agents/_base_chat_agent.pyindex b2e4e4fde..94b89235d 100644--- a/python/packages/autogen-agentchat/src/autogen_agentchat/agents/_base_chat_agent.py+++ b/python/packages/autogen-agentchat/src/autogen_agentchat/agents/_base_chat_agent.py@@ -190,6 +190,20 @@ class BaseChatAgent(ChatAgent, ABC, ComponentBase[BaseModel]):"""Resets the agent to its initialization state."""...+ async def on_pause(self, cancellation_token: CancellationToken) -> None:+ """Called when the agent is paused while running in its :meth:`on_messages` or+ :meth:`on_messages_stream` method. This is a no-op by default in the+ :class:`BaseChatAgent` class. Subclasses can override this method to+ implement custom pause behavior."""+ pass++ async def on_resume(self, cancellation_token: CancellationToken) -> None:+ """Called when the agent is resumed from a pause while running in+ its :meth:`on_messages` or :meth:`on_messages_stream` method.+ This is a no-op by default in the :class:`BaseChatAgent` class.+ Subclasses can override this method to implement custom resume behavior."""+ pass+async def save_state(self) -> Mapping[str, Any]:"""Export state. Default implementation for stateless agents."""return BaseState().model_dump()@@ -199,5 +213,7 @@ class BaseChatAgent(ChatAgent, ABC, ComponentBase[BaseModel]):BaseState.model_validate(state)async def close(self) -> None:- """Called when the runtime is closed"""+ """Release any resources held by the agent. This is a no-op by default in the+ :class:`BaseChatAgent` class. Subclasses can override this method to+ implement custom close behavior."""passdiff --git a/python/packages/autogen-agentchat/src/autogen_agentchat/base/_chat_agent.py b/python/packages/autogen-agentchat/src/autogen_agentchat/base/_chat_agent.pyindex 34f0f37ee..ec885ee7f 100644--- a/python/packages/autogen-agentchat/src/autogen_agentchat/base/_chat_agent.py+++ b/python/packages/autogen-agentchat/src/autogen_agentchat/base/_chat_agent.py@@ -66,6 +66,18 @@ class ChatAgent(ABC, TaskRunner, ComponentBase[BaseModel]):"""Resets the agent to its initialization state."""...+ @abstractmethod+ async def on_pause(self, cancellation_token: CancellationToken) -> None:+ """Called when the agent is paused. The agent may be running in :meth:`on_messages` or+ :meth:`on_messages_stream` when this method is called."""+ ...++ @abstractmethod+ async def on_resume(self, cancellation_token: CancellationToken) -> None:+ """Called when the agent is resumed. The agent may be running in :meth:`on_messages` or+ :meth:`on_messages_stream` when this method is called."""+ ...+@abstractmethodasync def save_state(self) -> Mapping[str, Any]:"""Save agent state for later restoration"""@@ -78,5 +90,5 @@ class ChatAgent(ABC, TaskRunner, ComponentBase[BaseModel]):@abstractmethodasync def close(self) -> None:- """Called when the runtime is stopped or any stop method is called"""+ """Release any resources held by the agent."""...diff --git a/python/packages/autogen-agentchat/src/autogen_agentchat/base/_team.py b/python/packages/autogen-agentchat/src/autogen_agentchat/base/_team.pyindex 0d25edf6d..4cbdc9741 100644--- a/python/packages/autogen-agentchat/src/autogen_agentchat/base/_team.py+++ b/python/packages/autogen-agentchat/src/autogen_agentchat/base/_team.py@@ -15,6 +15,20 @@ class Team(ABC, TaskRunner, ComponentBase[BaseModel]):"""Reset the team and all its participants to its initial state."""...+ @abstractmethod+ async def pause(self) -> None:+ """Pause the team and all its participants. This is useful for+ pausing the :meth:`autogen_agentchat.base.TaskRunner.run` or+ :meth:`autogen_agentchat.base.TaskRunner.run_stream` methods from+ concurrently, while keeping them alive."""+ ...++ @abstractmethod+ async def resume(self) -> None:+ """Resume the team and all its participants from a pause after+ :meth:`pause` was called."""+ ...+@abstractmethodasync def save_state(self) -> Mapping[str, Any]:"""Save the current state of the team."""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.pyindex 14485e747..ff6731b03 100644--- 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@@ -27,7 +27,7 @@ from ...messages import ()from ...state import TeamStatefrom ._chat_agent_container import ChatAgentContainer-from ._events import GroupChatReset, GroupChatStart, GroupChatTermination+from ._events import GroupChatPause, GroupChatReset, GroupChatResume, GroupChatStart, GroupChatTerminationfrom ._sequential_routed_agent import SequentialRoutedAgentevent_logger = logging.getLogger(EVENT_LOGGER_NAME)@@ -565,6 +565,97 @@ class BaseGroupChat(Team, ABC, ComponentBase[BaseModel]):# Indicate that the team is no longer running.self._is_running = False+ async def pause(self) -> None:+ """Pause its participants when the team is running by calling their+ :meth:`~autogen_agentchat.base.ChatAgent.on_pause` method via direct RPC calls.++ .. attention::++ This is an experimental feature introduced in v0.4.9 and may subject+ to change or removal in the future.++ The team must be initialized before it can be paused.++ Different from termination, pausing the team does not cause the+ :meth:`run` or :meth:`run_stream` method to return. It calls the+ :meth:`~autogen_agentchat.base.ChatAgent.on_pause` method on each+ participant, and if the participant does not implement the method, it+ will be a no-op.++ .. note::++ It is the responsibility of the agent class to handle the pause+ and ensure that the agent can be resumed later.+ Make sure to implement the :meth:`~autogen_agentchat.agents.BaseChatAgent.on_pause`+ method in your agent class for custom pause behavior.+ By default, the agent will not do anything when called.++ Raises:+ RuntimeError: If the team has not been initialized. Exceptions from+ the participants when calling their implementations of+ :class:`~autogen_agentchat.base.ChatAgent.on_pause` are+ propagated to this method and raised.+ """+ if not self._initialized:+ raise RuntimeError("The group chat has not been initialized. It must be run before it can be paused.")++ # Send a pause message to all participants.+ for participant_topic_type in self._participant_topic_types:+ await self._runtime.send_message(+ GroupChatPause(),+ recipient=AgentId(type=participant_topic_type, key=self._team_id),+ )+ # Send a pause message to the group chat manager.+ await self._runtime.send_message(+ GroupChatPause(),+ recipient=AgentId(type=self._group_chat_manager_topic_type, key=self._team_id),+ )++ async def resume(self) -> None:+ """Resume its participants when the team is running and paused by calling their+ :meth:`~autogen_agentchat.base.ChatAgent.on_resume` method via direct RPC calls.++ .. attention::++ This is an experimental feature introduced in v0.4.9 and may subject+ to change or removal in the future.++ The team must be initialized before it can be resumed.++ Different from termination and restart with a new task, resuming the team+ does not cause the :meth:`run` or :meth:`run_stream` method to return.+ It calls the :meth:`~autogen_agentchat.base.ChatAgent.on_resume` method on each+ participant, and if the participant does not implement the method, it+ will be a no-op.++ .. note::++ It is the responsibility of the agent class to handle the resume+ and ensure that the agent continues from where it was paused.+ Make sure to implement the :meth:`~autogen_agentchat.agents.BaseChatAgent.on_resume`+ method in your agent class for custom resume behavior.++ Raises:+ RuntimeError: If the team has not been initialized. Exceptions from+ the participants when calling their implementations of :class:`~autogen_agentchat.base.ChatAgent.on_resume`+ method are propagated to this method and raised.++ """+ if not self._initialized:+ raise RuntimeError("The group chat has not been initialized. It must be run before it can be resumed.")++ # Send a resume message to all participants.+ for participant_topic_type in self._participant_topic_types:+ await self._runtime.send_message(+ GroupChatResume(),+ recipient=AgentId(type=participant_topic_type, key=self._team_id),+ )+ # Send a resume message to the group chat manager.+ await self._runtime.send_message(+ GroupChatResume(),+ recipient=AgentId(type=self._group_chat_manager_topic_type, key=self._team_id),+ )+async def save_state(self) -> Mapping[str, Any]:"""Save the state of the group chat team.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.pyindex c93f5bd36..0cd456337 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@@ -9,8 +9,10 @@ from ...messages import AgentEvent, ChatMessage, StopMessagefrom ._events import (GroupChatAgentResponse,GroupChatMessage,+ GroupChatPause,GroupChatRequestPublish,GroupChatReset,+ GroupChatResume,GroupChatStart,GroupChatTermination,)@@ -41,7 +43,15 @@ class BaseGroupChatManager(SequentialRoutedAgent, ABC):termination_condition: TerminationCondition | None = None,max_turns: int | None = None,):- super().__init__(description="Group chat manager")+ super().__init__(+ description="Group chat manager",+ sequential_message_types=[+ GroupChatStart,+ GroupChatAgentResponse,+ GroupChatMessage,+ GroupChatReset,+ ],+ )self._name = nameself._group_topic_type = group_topic_typeself._output_topic_type = output_topic_type@@ -193,13 +203,25 @@ class BaseGroupChatManager(SequentialRoutedAgent, ABC):@eventasync def handle_group_chat_message(self, message: GroupChatMessage, ctx: MessageContext) -> None:+ """Handle a group chat message by appending the content to its output message queue."""await self._output_message_queue.put(message.message)@rpcasync def handle_reset(self, message: GroupChatReset, ctx: MessageContext) -> None:- # Reset the group chat manager.+ """Reset the group chat manager. Calling :meth:`reset` to reset the group chat manager+ and clear the message thread."""await self.reset()+ @rpc+ async def handle_pause(self, message: GroupChatPause, ctx: MessageContext) -> None:+ """Pause the group chat manager. This is a no-op in the base class."""+ pass++ @rpc+ async def handle_resume(self, message: GroupChatResume, ctx: MessageContext) -> None:+ """Resume the group chat manager. This is a no-op in the base class."""+ pass+@abstractmethodasync def validate_group_state(self, messages: List[ChatMessage] | None) -> None:"""Validate the state of the group chat given the start messages.diff --git a/python/packages/autogen-agentchat/src/autogen_agentchat/teams/_group_chat/_chat_agent_container.py b/python/packages/autogen-agentchat/src/autogen_agentchat/teams/_group_chat/_chat_agent_container.pyindex f01465d4c..7c86556e2 100644--- a/python/packages/autogen-agentchat/src/autogen_agentchat/teams/_group_chat/_chat_agent_container.py+++ b/python/packages/autogen-agentchat/src/autogen_agentchat/teams/_group_chat/_chat_agent_container.py@@ -5,7 +5,15 @@ from autogen_core import DefaultTopicId, MessageContext, event, rpcfrom ...base import ChatAgent, Responsefrom ...messages import ChatMessagefrom ...state import ChatAgentContainerState-from ._events import GroupChatAgentResponse, GroupChatMessage, GroupChatRequestPublish, GroupChatReset, GroupChatStart+from ._events import (+ GroupChatAgentResponse,+ GroupChatMessage,+ GroupChatPause,+ GroupChatRequestPublish,+ GroupChatReset,+ GroupChatResume,+ GroupChatStart,+)from ._sequential_routed_agent import SequentialRoutedAgent@@ -21,7 +29,15 @@ class ChatAgentContainer(SequentialRoutedAgent):"""def __init__(self, parent_topic_type: str, output_topic_type: str, agent: ChatAgent) -> None:- super().__init__(description=agent.description)+ super().__init__(+ description=agent.description,+ sequential_message_types=[+ GroupChatStart,+ GroupChatRequestPublish,+ GroupChatReset,+ GroupChatAgentResponse,+ ],+ )self._parent_topic_type = parent_topic_typeself._output_topic_type = output_topic_typeself._agent = agent@@ -74,6 +90,16 @@ class ChatAgentContainer(SequentialRoutedAgent):cancellation_token=ctx.cancellation_token,)+ @rpc+ async def handle_pause(self, message: GroupChatPause, ctx: MessageContext) -> None:+ """Handle a pause event by pausing the agent."""+ await self._agent.on_pause(ctx.cancellation_token)++ @rpc+ async def handle_resume(self, message: GroupChatResume, ctx: MessageContext) -> None:+ """Handle a resume event by resuming the agent."""+ await self._agent.on_resume(ctx.cancellation_token)+async def on_unhandled_message(self, message: Any, ctx: MessageContext) -> None:raise ValueError(f"Unhandled message in agent container: {type(message)}")diff --git a/python/packages/autogen-agentchat/src/autogen_agentchat/teams/_group_chat/_events.py b/python/packages/autogen-agentchat/src/autogen_agentchat/teams/_group_chat/_events.pyindex 853b854a4..f705a54c4 100644--- a/python/packages/autogen-agentchat/src/autogen_agentchat/teams/_group_chat/_events.py+++ b/python/packages/autogen-agentchat/src/autogen_agentchat/teams/_group_chat/_events.py@@ -44,3 +44,15 @@ class GroupChatReset(BaseModel):"""A request to reset the agents in the group chat."""...+++class GroupChatPause(BaseModel):+ """A request to pause the group chat."""++ ...+++class GroupChatResume(BaseModel):+ """A request to resume the group chat."""++ ...diff --git a/python/packages/autogen-agentchat/src/autogen_agentchat/teams/_group_chat/_sequential_routed_agent.py b/python/packages/autogen-agentchat/src/autogen_agentchat/teams/_group_chat/_sequential_routed_agent.pyindex 572592f2d..be2cd9eca 100644--- a/python/packages/autogen-agentchat/src/autogen_agentchat/teams/_group_chat/_sequential_routed_agent.py+++ b/python/packages/autogen-agentchat/src/autogen_agentchat/teams/_group_chat/_sequential_routed_agent.py@@ -1,5 +1,5 @@import asyncio-from typing import Any+from typing import Any, Sequencefrom autogen_core import MessageContext, RoutedAgent@@ -36,15 +36,37 @@ class FIFOLock:class SequentialRoutedAgent(RoutedAgent):"""A subclass of :class:`autogen_core.RoutedAgent` that ensures- messages are handled sequentially in the order they arrive."""+ that messages of certain types are processed sequentially+ using a FIFO lock.- def __init__(self, description: str) -> None:+ This is useful for agents that need to maintain a strict order of+ processing messages, such as in a group chat scenario.++++ Args:++ description (str): The description of the agent.+ sequential_message_types (Sequence[Type[Any]]): A sequence of message types that should be+ processed sequentially. If a message of one of these types is received,+ the agent will acquire a FIFO lock to ensure that it is processed+ before any later messages that are also one of these types.+ """++ def __init__(self, description: str, sequential_message_types: Sequence[type[Any]]) -> None:super().__init__(description=description)self._fifo_lock = FIFOLock()+ self._sequential_message_types = sequential_message_typesasync def on_message_impl(self, message: Any, ctx: MessageContext) -> Any | None:- await self._fifo_lock.acquire()- try:- return await super().on_message_impl(message, ctx)- finally:- self._fifo_lock.release()+ if any(isinstance(message, sequential_type) for sequential_type in self._sequential_message_types):+ # Acquire the FIFO lock to ensure that this message is processed+ # in the order it was received.+ await self._fifo_lock.acquire()+ try:+ return await super().on_message_impl(message, ctx)+ finally:+ # Release the FIFO lock to allow the next message to be processed.+ self._fifo_lock.release()+ # If the message is not of a sequential type, process it normally.+ return await super().on_message_impl(message, ctx)diff --git a/python/packages/autogen-agentchat/tests/test_group_chat_pause_resume.py b/python/packages/autogen-agentchat/tests/test_group_chat_pause_resume.pynew file mode 100644index 000000000..ee87f6f4a--- /dev/null+++ b/python/packages/autogen-agentchat/tests/test_group_chat_pause_resume.py@@ -0,0 +1,142 @@+import asyncio+from typing import AsyncGenerator, List, Sequence++import pytest+import pytest_asyncio+from autogen_agentchat.agents import BaseChatAgent+from autogen_agentchat.base import Response+from autogen_agentchat.messages import ChatMessage, TextMessage+from autogen_agentchat.teams import RoundRobinGroupChat+from autogen_core import AgentRuntime, CancellationToken, SingleThreadedAgentRuntime+++class TestAgent(BaseChatAgent):+ """A test agent that does nothing."""++ def __init__(self, name: str, description: str) -> None:+ super().__init__(name=name, description=description)+ self._is_paused = False+ self._tasks: List[asyncio.Task[None]] = []+ self.counter = 0++ @property+ def produced_message_types(self) -> Sequence[type[ChatMessage]]:+ return [TextMessage]++ async def on_messages(self, messages: Sequence[ChatMessage], cancellation_token: CancellationToken) -> Response:+ assert not self._is_paused, "Agent is paused"++ async def _process() -> None:+ # Simulate a repetitive task that runs forever.+ while True:+ if self._is_paused:+ await asyncio.sleep(0.1)+ continue+ else:+ # Simulate a I/O operation that takes time, e.g., a browser operation.+ await asyncio.sleep(0.1)+ self.counter += 1++ curr_task = asyncio.create_task(_process())+ self._tasks.append(curr_task)++ try:+ # This will never return until the task is cancelled, at which point it will+ # raise an exception.+ await curr_task+ except asyncio.CancelledError:+ # The task was cancelled, so we can safely ignore this.+ pass++ return Response(+ chat_message=TextMessage(+ source=self.name,+ content="",+ ),+ )++ async def on_reset(self, cancellation_token: CancellationToken) -> None:+ self.counter = 0++ async def on_pause(self, cancellation_token: CancellationToken) -> None:+ self._is_paused = True++ async def on_resume(self, cancellation_token: CancellationToken) -> None:+ self._is_paused = False++ async def close(self) -> None:+ # Cancel all tasks and wait for them to finish.+ while self._tasks:+ task = self._tasks.pop()+ task.cancel()+ try:+ await task+ except asyncio.CancelledError:+ pass+++@pytest_asyncio.fixture(params=["single_threaded", "embedded"]) # type: ignore+async def runtime(request: pytest.FixtureRequest) -> AsyncGenerator[AgentRuntime | None, None]:+ if request.param == "single_threaded":+ runtime = SingleThreadedAgentRuntime()+ runtime.start()+ yield runtime+ await runtime.stop()+ elif request.param == "embedded":+ yield None+++async def test_group_chat_pause_resume(runtime: AgentRuntime | None) -> None:+ agent = TestAgent(name="test_agent", description="test agent")++ team = RoundRobinGroupChat([agent], runtime=runtime, max_turns=1)++ # Run the team in a separate task.+ team_task = asyncio.create_task(team.run())++ # Get the current counter.+ curr_counter = agent.counter++ # Let the agent process the counter for a while.+ await asyncio.sleep(1)++ # Check that the agent's counter has increased.+ assert curr_counter < agent.counter+ curr_counter = agent.counter++ # Pause the team.+ await team.pause()++ # Wait for a while for the agent to process the pause.+ await asyncio.sleep(1)++ # Get the current counter value.+ curr_counter = agent.counter++ # Wait for a while.+ await asyncio.sleep(1)++ # Check that the agent's counter has not increased.+ assert curr_counter == agent.counter++ # Resume the agent.+ await team.resume()++ # Wait for a while for the agent to process the resume.+ await asyncio.sleep(1)++ # Get the current counter value.+ curr_counter = agent.counter++ # Wait for a while.+ await asyncio.sleep(1)++ # Check that the agent's counter has increased.+ assert curr_counter < agent.counter++ # Clean up -- force the agent to respond and terminate the team.+ await agent.close()++ # Wait for the team to terminate.+ await team_taskdiff --git a/python/packages/autogen-agentchat/tests/test_sequential_routed_agent.py b/python/packages/autogen-agentchat/tests/test_sequential_routed_agent.pyindex 165c68e6d..4d4a46da9 100644--- a/python/packages/autogen-agentchat/tests/test_sequential_routed_agent.py+++ b/python/packages/autogen-agentchat/tests/test_sequential_routed_agent.py@@ -23,7 +23,7 @@ class Message:@default_subscriptionclass _TestAgent(SequentialRoutedAgent):def __init__(self, description: str) -> None:- super().__init__(description=description)+ super().__init__(description=description, sequential_message_types=[Message])self.messages: List[Message] = []@message_handler