Skip to content

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.py
index 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."""
pass
diff --git a/python/packages/autogen-agentchat/src/autogen_agentchat/base/_chat_agent.py b/python/packages/autogen-agentchat/src/autogen_agentchat/base/_chat_agent.py
index 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."""
+ ...
+
@abstractmethod
async def save_state(self) -> Mapping[str, Any]:
"""Save agent state for later restoration"""
@@ -78,5 +90,5 @@ class ChatAgent(ABC, TaskRunner, ComponentBase[BaseModel]):
@abstractmethod
async 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.py
index 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."""
+ ...
+
@abstractmethod
async 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.py
index 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 TeamState
from ._chat_agent_container import ChatAgentContainer
-from ._events import GroupChatReset, GroupChatStart, GroupChatTermination
+from ._events import GroupChatPause, GroupChatReset, GroupChatResume, GroupChatStart, GroupChatTermination
from ._sequential_routed_agent import SequentialRoutedAgent
event_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.py
index 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, StopMessage
from ._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 = name
self._group_topic_type = group_topic_type
self._output_topic_type = output_topic_type
@@ -193,13 +203,25 @@ class BaseGroupChatManager(SequentialRoutedAgent, ABC):
@event
async 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)
@rpc
async 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
+
@abstractmethod
async 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.py
index 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, rpc
from ...base import ChatAgent, Response
from ...messages import ChatMessage
from ...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_type
self._output_topic_type = output_topic_type
self._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.py
index 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.py
index 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, Sequence
from 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_types
async 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.py
new file mode 100644
index 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_task
diff --git a/python/packages/autogen-agentchat/tests/test_sequential_routed_agent.py b/python/packages/autogen-agentchat/tests/test_sequential_routed_agent.py
index 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_subscription
class _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