Configuring Termination Conditions for Group Chat Sessions in AutoGen

AutoGen terminates group chat sessions when a TerminationCondition evaluates to True, using built-in strategies like message limits, text mentions, or timeouts that can be combined with logical operators.

Configuring termination conditions for group chat sessions ensures that multi-agent conversations in the microsoft/autogen repository halt gracefully when objectives are met, budgets are exhausted, or specific signals appear in the message history. The framework provides an extensible hierarchy of termination components that integrate seamlessly with RoundRobinGroupChat and other team implementations.

Understanding the TerminationCondition Architecture

The termination system centers on the abstract base class TerminationCondition defined in autogen_agentchat/base/_termination.py. This class implements a callable interface that the chat runtime invokes after each turn:

await termination_condition(messages) → Optional[bool]

When the condition returns a truthy value, the group chat stops and optionally returns a termination message to the caller. Because TerminationCondition inherits from Component, instances can be serialized in YAML or JSON component configs for reuse across AutoGen Studio, CLI tools, or custom agents.

Concrete implementations reside in autogen_agentchat/conditions/_terminations.py, which defines ready-made strategies for common scenarios. The runtime stores each message as a Message subclass (TextMessage, StopMessage, HandoffMessage, etc.) in autogen_agentchat/teams/_group_chat/_events.py, allowing termination conditions to inspect message types, content, sources, and metadata.

Built-in Termination Conditions for Group Chat Sessions

AutoGen provides eleven concrete termination strategies that cover signal-based, budget-based, and time-based criteria:

• StopMessageTermination – Halts when any participant sends a StopMessage, typically used for explicit user or system shutdown signals.
• MaxMessageTermination – Enforces a hard limit on conversation length via the max_messages parameter.
• TextMentionTermination – Scans text messages for a specific string (e.g., "TERMINATE") from defined source agents.
• HandoffTermination – Triggers when a HandoffMessage targets a specific name, useful for human-in-the-loop workflows.
• TimeoutTermination – Stops the session after a wall-clock timeout in seconds.
• TokenUsageTermination – Monitors cumulative token consumption and terminates when a model-specific budget is exceeded.
• ExternalTermination – Delegates the decision to an external async predicate function.
• SourceMatchTermination – Verifies that the latest message originates from a specific source (e.g., "assistant").
• TextMessageTermination – Generic regex or substring matching for text content.
• FunctionCallTermination – Ends the session after a specific function call appears in the message history.

Combining Multiple Termination Conditions

Complex workflows often require multiple exit criteria. AutoGen supports logical composition through AndTerminationCondition and OrTerminationCondition, exposed via Python's bitwise operators & and |:

from autogen_agentchat import (
    RoundRobinGroupChat,
    TextMentionTermination,
    MaxMessageTermination,
)

termination = TextMentionTermination("TERMINATE") | MaxMessageTermination(max_messages=30)
team = RoundRobinGroupChat([assistant], termination_condition=termination)

await team.run()

The | operator creates an OrTerminationCondition, causing the group chat to stop when either the text mention appears or the message limit is reached. Similarly, & creates an AndTerminationCondition requiring all criteria to be satisfied simultaneously.

Practical Implementation Examples

Text Mention with Source Filtering

This pattern from python/samples/agentchat_chainlit/app_team.py terminates when a specific agent emits an approval keyword:

from autogen_agentchat import RoundRobinGroupChat, TextMentionTermination

termination = TextMentionTermination("APPROVE", sources=["critic"])
group_chat = RoundRobinGroupChat([assistant, critic], termination_condition=termination)

await group_chat.run()

The chat stops only when the "critic" agent includes "APPROVE" in a message.

Handoff-Based Termination

Used in python/packages/autogen-ext/examples/mcp_example_server.py for human-in-the-loop scenarios:

from autogen_agentchat import RoundRobinGroupChat, HandoffTermination

termination = HandoffTermination(target="final")
team = RoundRobinGroupChat([assistant], termination_condition=termination)

await team.run()

This configuration pauses the automation when the assistant requests a handoff to the "final" human reviewer.

Timeout Protection

From python/samples/core_async_human_in_the_loop/main.py, this prevents runaway conversations:

from autogen_agentchat import RoundRobinGroupChat, TimeoutTermination

termination = TimeoutTermination(seconds=300)  # 5-minute limit

team = RoundRobinGroupChat([assistant, user], termination_condition=termination)

await team.run()

Key Source Files and References

File	Purpose	Link
autogen_agentchat/conditions/_terminations.py	Concrete implementations of all built-in termination strategies and logical combinators.	https://github.com/microsoft/autogen/blob/main/python/packages/autogen-agentchat/src/autogen_agentchat/conditions/_terminations.py
autogen_agentchat/base/_termination.py	Abstract base class TerminationCondition defining the callable interface and component wiring.	https://github.com/microsoft/autogen/blob/main/python/packages/autogen-agentchat/src/autogen_agentchat/base/_termination.py
autogen_agentchat/teams/_group_chat/_events.py	GroupChatTermination model and message event definitions used during serialization.	https://github.com/microsoft/autogen/blob/main/python/packages/autogen-agentchat/src/autogen_agentchat/teams/_group_chat/_events.py
python/samples/agentchat_chainlit/app_team.py	Real-world example of TextMentionTermination with source filtering.	https://github.com/microsoft/autogen/blob/main/python/samples/agentchat_chainlit/app_team.py
python/samples/core_async_human_in_the_loop/main.py	Demonstrates TimeoutTermination for human-in-the-loop workflows.	https://github.com/microsoft/autogen/blob/main/python/samples/core_async_human_in_the_loop/main.py

Summary

• TerminationCondition is the abstract base class in autogen_agentchat/base/_termination.py that powers all group chat exit logic.
• Built-in strategies include message limits, text mentions, timeouts, token budgets, and handoff signals, all defined in autogen_agentchat/conditions/_terminations.py.
• Use the | (OR) and & (AND) operators to compose multiple conditions for complex workflows.
• Pass the configured condition to RoundRobinGroupChat (or other team classes) via the termination_condition parameter.
• All termination components are serializable via the Component base class, enabling reuse across AutoGen Studio and configuration files.

Frequently Asked Questions

How do I stop a group chat when a specific word is mentioned?

Use TextMentionTermination and pass the target string to its constructor. You can optionally restrict monitoring to specific agent sources using the sources parameter. For example, TextMentionTermination("TERMINATE", sources=["assistant"]) stops the chat only when the assistant emits that keyword.

Can I combine multiple termination conditions in AutoGen?

Yes. AutoGen supports logical composition through the | (OR) and & (AND) operators. The expression condition_a | condition_b creates an OrTerminationCondition that triggers when either criterion is met, while condition_a & condition_b creates an AndTerminationCondition requiring both to be satisfied simultaneously.

What is the difference between StopMessageTermination and TextMentionTermination?

StopMessageTermination monitors for a StopMessage object in the message history, which is a specific message type typically sent by system agents or user interfaces to signal an immediate halt. TextMentionTermination scans the text content of TextMessage objects for a substring match, making it suitable for keyword-based exits embedded in natural language responses.

How do I prevent a group chat from running indefinitely?

Apply MaxMessageTermination to set a hard limit on the number of messages, TimeoutTermination to enforce a wall-clock time limit (e.g., 300 seconds), or TokenUsageTermination to stop when a token budget is exceeded. Combining these via the OR operator provides defense-in-depth against runaway conversations.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}