# How to Implement Pause and Resume in Autogen Group Chats

> Easily add pause and resume to Autogen group chats by implementing on_pause and on_resume methods. Control group chat execution with team.pause() and team.resume() for seamless agent communication and workflow management.

- Repository: [Microsoft/autogen](https://github.com/microsoft/autogen)
- Tags: how-to-guide
- Published: 2026-03-07

---

**To implement pause and resume functionality in Autogen group chats, implement the `on_pause` and `on_resume` methods in your agents, then call `team.pause()` and `team.resume()` to broadcast control events through the runtime.**

The **microsoft/autogen** framework enables interactive control over multi-agent workflows through built-in pause and resume capabilities. This functionality allows you to suspend and resume group chat execution programmatically, which is essential for managing long-running or resource-intensive agent conversations. Understanding the internal architecture and agent responsibilities ensures you implement robust pause-aware agents that respond correctly to control signals.

## Architecture of Pause and Resume

The pause and resume system relies on a distributed event model where the `BaseGroupChat` coordinates with individual agents through the `AgentRuntime`. Understanding these components is crucial for implementing reliable control flows.

### Core Components

The implementation spans four key files in the `autogen_agentchat` package:

- **`BaseGroupChat`** ([`python/packages/autogen-agentchat/src/autogen_agentchat/teams/_group_chat/_base_group_chat.py`](https://github.com/microsoft/autogen/blob/main/python/packages/autogen-agentchat/src/autogen_agentchat/teams/_group_chat/_base_group_chat.py)): Implements the high-level `pause()` and `resume()` methods and manages the team lifecycle
- **`GroupChatPause` and `GroupChatResume`** ([`python/packages/autogen-agentchat/src/autogen_agentchat/teams/_group_chat/_events.py`](https://github.com/microsoft/autogen/blob/main/python/packages/autogen-agentchat/src/autogen_agentchat/teams/_group_chat/_events.py)): Pydantic event models transmitted via RPC to signal state changes
- **`BaseChatAgent`** ([`python/packages/autogen-agentchat/src/autogen_agentchat/base/_chat_agent.py`](https://github.com/microsoft/autogen/blob/main/python/packages/autogen-agentchat/src/autogen_agentchat/base/_chat_agent.py)): Abstract base class defining the `on_pause` and `on_resume` hooks that agents must implement
- **[`_chat_agent_container.py`](https://github.com/microsoft/autogen/blob/main/_chat_agent_container.py)** ([`python/packages/autogen-agentchat/src/autogen_agentchat/teams/_group_chat/_chat_agent_container.py`](https://github.com/microsoft/autogen/blob/main/python/packages/autogen-agentchat/src/autogen_agentchat/teams/_group_chat/_chat_agent_container.py)): Routes incoming pause/resume events to the concrete agent implementations

### How Pause Works

When you invoke `team.pause()`, the `BaseGroupChat` executes a precise sequence defined in lines 88–100 of [`_base_group_chat.py`](https://github.com/microsoft/autogen/blob/main/_base_group_chat.py):

1. **Initialization Check**: The method verifies `self._initialized` is true, raising a `RuntimeError` if the team has not been started (lines 88–90)
2. **Participant Notification**: Iterates through `self._participant_topic_types` and sends `GroupChatPause()` events to each participant via `runtime.send_message()` (lines 91–96)
3. **Manager Notification**: Sends a `GroupChatPause()` event to the group chat manager itself (lines 97–100)
4. **Agent Handling**: Each participant receives the event in its container ([`_chat_agent_container.py`](https://github.com/microsoft/autogen/blob/main/_chat_agent_container.py) lines 177–183) and forwards the call to the agent's `on_pause` method

### How Resume Works

The `resume()` method mirrors the pause logic exactly (lines 36–46 of the `resume` method in [`_base_group_chat.py`](https://github.com/microsoft/autogen/blob/main/_base_group_chat.py)), broadcasting `GroupChatResume` events instead. The container code at line 192 of [`_chat_agent_container.py`](https://github.com/microsoft/autogen/blob/main/_chat_agent_container.py) invokes the agent's `on_resume` method when the event arrives.

## Implementing Pause-Aware Agents

Agents must explicitly implement `on_pause` and `on_resume` to react to control signals. The framework only notifies agents; suspending actual work is the agent's responsibility.

### Minimal Agent Implementation

Here is a complete `CounterAgent` that demonstrates proper pause/resume handling by checking an internal flag during long-running operations:

```python
import asyncio
from autogen_agentchat.agents import BaseChatAgent
from autogen_agentchat.messages import TextMessage
from autogen_core import CancellationToken

class CounterAgent(BaseChatAgent):
    def __init__(self, name: str):
        super().__init__(name=name, description="Counts while not paused")
        self._paused = False
        self.counter = 0

    @property
    def produced_message_types(self):
        return [TextMessage]

    async def on_messages(self, messages, cancellation_token: CancellationToken):
        # Simulate work that respects the pause flag

        while not self._paused:
            await asyncio.sleep(0.1)
            self.counter += 1
        # Return an empty TextMessage to keep the contract

        return Response(chat_message=TextMessage(source=self.name, content=""))

    async def on_pause(self, cancellation_token: CancellationToken):
        self._paused = True

    async def on_resume(self, cancellation_token: CancellationToken):
        self._paused = False

    async def close(self):
        # Clean‑up if needed

        pass

```

If an agent does not implement these methods, pause and resume calls become **no-ops**, which is the intended behavior for agents that do not require granular control.

## Controlling Group Chat Execution

Use the `RoundRobinGroupChat` or other `BaseGroupChat` subclasses with a runtime to orchestrate pause and resume operations.

### Practical Usage Example

This example demonstrates running a team, pausing execution to halt agent processing, and resuming to continue the workflow:

```python
import asyncio
from autogen_agentchat.teams import RoundRobinGroupChat
from autogen_core import SingleThreadedAgentRuntime

async def demo():
    runtime = SingleThreadedAgentRuntime()
    runtime.start()

    agent = CounterAgent(name="counter")
    team = RoundRobinGroupChat([agent], runtime=runtime, max_turns=5)

    # Run the team in the background

    team_task = asyncio.create_task(team.run())

    # Let the agent count for a moment

    await asyncio.sleep(1)
    print("counter =", agent.counter)          # → > 0

    # Pause the chat – the agent should stop counting

    await team.pause()
    await asyncio.sleep(1)
    print("still paused, counter =", agent.counter)  # → unchanged

    # Resume the chat – counting continues

    await team.resume()
    await asyncio.sleep(1)
    print("after resume, counter =", agent.counter)  # → increased

    # Shut down

    await team.terminate()
    await runtime.stop()
    await team_task

asyncio.run(demo())

```

Note that pause and resume are **ephemeral operations**—they do not alter the team's saved state. To persist progress across sessions, call `team.save_state()` before pausing and `team.load_state()` after restarting.

## Testing and Verification

The official test suite in [`python/packages/autogen-agentchat/tests/test_group_chat_pause_resume.py`](https://github.com/microsoft/autogen/blob/main/python/packages/autogen-agentchat/tests/test_group_chat_pause_resume.py) validates the exact behavior described above. The test verifies that:

- `assert curr_counter == agent.counter` immediately after pause (line 21), confirming the agent stops making progress
- `assert curr_counter < agent.counter` after resume (line 36), confirming the agent resumes processing

You should implement similar assertions in your own test suites to ensure your agents correctly respect pause boundaries.

## Summary

- **BaseGroupChat** provides the `pause()` and `resume()` API that broadcasts control events to all participants
- **GroupChatPause** and **GroupChatResume** events are transmitted via the `AgentRuntime` to every agent and the manager
- **Agent responsibility**: Implement `on_pause` and `on_resume` in your `BaseChatAgent` subclasses to set internal flags that suspend active processing
- **State persistence**: Pause and resume do not affect saved state; use `save_state()` and `load_state()` for persistence
- **Error handling**: Calling `pause()` before `run()` raises a `RuntimeError` due to the initialization check at lines 88–90 of [`_base_group_chat.py`](https://github.com/microsoft/autogen/blob/main/_base_group_chat.py)

## Frequently Asked Questions

### What happens if I call pause() before starting the team?

Calling `team.pause()` before `team.run()` raises a `RuntimeError` because the `BaseGroupChat` checks `self._initialized` at lines 88–90 of [`_base_group_chat.py`](https://github.com/microsoft/autogen/blob/main/_base_group_chat.py). You must initialize the team by calling `run()` first to establish the runtime connections and participant topics.

### Do all agents need to implement on_pause and on_resume?

No, these methods are optional. If an agent does not implement `on_pause` and `on_resume`, the pause and resume calls become no-ops for that specific agent, as noted in the docstring at line 70 of [`_base_group_chat.py`](https://github.com/microsoft/autogen/blob/main/_base_group_chat.py). Only agents with long-running operations or external resource management need to implement these hooks.

### Does pausing a group chat affect its saved state?

No, pause and resume are ephemeral operations that only send control signals through the runtime. They do not modify the internal state representation used by `save_state()` and `load_state()`. To preserve progress across application restarts, explicitly call `save_state()` before shutting down and `load_state()` when reconstructing the team.

### How does the runtime deliver pause events to agents?

The `AgentRuntime` uses RPC-style message passing. When `pause()` is called, `BaseGroupChat` sends `GroupChatPause` events to each participant's `AgentId` and to the manager. The [`_chat_agent_container.py`](https://github.com/microsoft/autogen/blob/main/_chat_agent_container.py) receives these messages and forwards them to the concrete agent's `on_pause` method at lines 177–183, ensuring each agent processes the signal within its own execution context.