AutoGen多智能体协作、人机交互与终止条件

一、Agent Team 核心概念详解

1.1 什么是 Agent Team？

在 AutoGen 框架中，Agent Team（多智能体团队）是突破传统单智能体局限的核心功能。它并非单一 AI 独立工作，而是由多个具备特定专业能力的智能代理（AI Agent）组成协作系统，通过明确分工与互动，共同应对复杂任务。
与传统单智能体相比，多智能体团队的差异主要体现在 "能力定位" 和 "工作模式" 上。单智能体更像 "全能型选手"，试图独立处理所有任务，容易在专业深度不足或任务复杂度较高时出现偏差；而多智能体团队则是 "专家协作组"，每个智能体专注某一领域，比如创作、评审、测试等，通过协作弥补单一智能体的短板。
其核心价值集中在四个方面：

**专业分工：**让具备对应技能的智能体处理专属任务，比如让 "创作智能体" 写诗歌，"评审智能体" 查质量，提升任务处理的精准度。
**质量保证：**通过多轮反馈与评审，比如评审智能体对创作内容提出修改建议，创作智能体优化后再提交，逐步提升输出质量。
**复杂问题分解：**将大型任务拆分成子任务，比如 "开发一个完整工具" 可拆分为 "写代码""做测试""写文档"，由不同智能体分别完成，降低任务难度。
**错误纠正：**多个智能体可相互检查，比如测试智能体发现开发智能体代码中的逻辑错误，避免单一智能体遗漏问题。

1.2 团队协作模式

多智能体团队主要通过三种关键机制实现高效协作，确保信息同步与流程有序：

**对话式协作：**智能体之间以 "消息传递" 为核心互动方式，且每个智能体都能查看完整的对话历史。比如创作智能体提交诗歌后，评审智能体可通过历史对话了解创作背景，给出更贴合需求的建议，避免因信息断层导致协作脱节。
**轮询机制：**在 RoundRobinGroupChat（轮询式群聊）模式下，智能体按照预设的固定顺序轮流发言。例如先让创作智能体输出内容，再让评审智能体进行评估，每个智能体发言时都能基于前序对话内容响应，保证协作流程的规律性。
**上下文共享：**所有团队成员共用同一套对话上下文，意味着每个智能体做出决策或输出内容时，都能参考其他智能体的历史操作与反馈，确保整个团队的工作方向一致，不会出现 "各做各的" 的情况。

二、创建第一个Agent Team

2.1 环境准备和基础设置

创建多智能体团队前，需先完成 "模型客户端配置" 这一核心基础工作，它是智能体与 AI 模型（如 GPT-4、GPT-3.5）通信的桥梁。
首先需导入必要的工具库，包括处理异步任务的 asyncio、管理系统环境的 os，以及 AutoGen 框架中与智能体、团队、终止条件相关的模块，还有对接 OpenAI 模型的客户端模块。
随后配置模型客户端，关键参数包括：

model：指定使用的 AI 模型。
api_key：用于验证 OpenAI 服务权限，若已在系统环境变量中设置 "OPENAI_API_KEY"，可省略该参数；若未设置，则需在此处手动填写。
temperature：控制 AI 输出的创造性，取值范围 0-1，值越高（如 0.7），输出内容越灵活有创意；值越低（如 0.2），输出越严谨固定。
配置完成后，可通过打印提示确认模型客户端已就绪，为后续创建智能体做好准备。

python 复制代码

import asyncio
import os
from autogen_agentchat.agents import AssistantAgent
from autogen_agentchat.conditions import TextMentionTermination
from autogen_agentchat.teams import RoundRobinGroupChat
from autogen_agentchat.ui import Console
from autogen_core.models import ModelFamily
from autogen_ext.models.openai import OpenAIChatCompletionClient

# 创建一个自定义的大模型客户端实例（文本模型）
model_client = OpenAIChatCompletionClient(
    model="deepseek-chat",
    base_url="https://api.deepseek.com/v1",
    api_key="sk-xxxxxxxxxx",
    model_info={
        "vision": False,
        "function_calling": True,
        "json_output": True,
        "family": ModelFamily.UNKNOWN,
        "structured_output": True,
        "multiple_system_messages": True
    },
)

print("模型客户端配置完成")

2.2 创建专业化的智能体

智能体是团队的核心组成部分，需根据任务需求创建 "专业化" 角色，示例中重点创建了两种核心智能体：

（1）主要创作智能体（primary_agent）

该智能体的核心定位是 "内容生产者"，负责根据用户需求生成诗歌、故事、技术文档等内容。在创建时，需通过 "system_message" 明确其角色职责与创作原则：

职责：聚焦 "高质量内容创作""创意与专业性平衡""接受反馈改进""保证内容准确有吸引力"，确保创作方向符合需求。
创作原则：针对不同内容类型制定具体标准，比如诗歌需注重韵律、意象与情感，技术文档需结构清晰、术语准确，故事需情节连贯、人物鲜明，让智能体的创作有明确依据。

（2）评审智能体（critic_agent）

该智能体的核心定位是 "质量把控者"，负责评估创作内容的质量并提供改进建议，只有当内容达标时才会批准通过。其 "system_message" 需明确评审职责、标准与批准条件：

职责：涵盖 "全面质量评估""提供建设性改进建议""检查内容准确性 / 一致性 / 完整性""达标后批准"，确保质量审核无遗漏。
评审标准：从内容质量（主题、逻辑）、语言表达（流畅度、用词）、结构组织（层次、重点）、创意价值（新颖性、启发性）四个维度制定标准，让评审有量化依据。
批准条件：仅当所有反馈问题被解决、内容达到专业标准时，回复 "APPROVE"，避免随意批准导致质量不达标。
创建完成后，通过打印提示确认两种智能体已就绪，为组建团队奠定基础。

python 复制代码

# 步骤2：创建主要创作智能体
# 这个智能体负责主要内容生成，如写作、编程等
primary_agent = AssistantAgent(
    name="primary",  # 智能体名称，用于在对话中标识
    description="一位专业的创作助手，擅长诗歌、故事和技术文档创作",
    model_client=model_client,  # 使用的模型客户端
    system_message="""
    你是一位专业的创作助手，擅长诗歌、故事和技术文档创作。
    
    你的职责：
    1. 根据用户需求创作高质量内容
    2. 保持创意和专业性的平衡
    3. 积极接受反馈并进行改进
    4. 确保内容准确且有吸引力
    
    创作原则：
    - 诗歌：注重韵律、意象和情感表达
    - 技术文档：结构清晰、术语准确
    - 故事：情节连贯、人物鲜明
    """,  # 系统提示词，定义智能体的角色和行为
)

print("主要创作智能体创建完成")

# 步骤3：创建评审智能体
# 这个智能体负责质量控制和反馈提供
critic_agent = AssistantAgent(
    name="critic",  # 评审者角色
    description="一位严格但公正的质量评审专家",
    model_client=model_client,
    system_message="""
    你是一位严格但公正的质量评审专家。
    
    你的职责：
    1. 对创作内容进行全面的质量评估
    2. 提供具体、建设性的改进建议
    3. 检查内容的准确性、一致性和完整性
    4. 当内容达到高质量标准时给予批准
    
    评审标准：
    - 内容质量：主题明确、逻辑清晰
    - 语言表达：流畅自然、用词准确
    - 结构组织：层次分明、重点突出
    - 创意价值：新颖独特、有启发性
    
    批准条件：只有当所有反馈点都被妥善解决，内容达到专业标准时，才回复"APPROVE"
    """,
)

print("评审智能体创建完成")

2.3 配置团队终止条件

终止条件是避免团队 "无限循环协作" 的关键，需明确团队何时停止工作。示例中使用 "TextMentionTermination"（文本提及终止）机制，核心逻辑围绕 "关键词检测" 展开：

工作原理：持续监控所有智能体的输出内容，一旦在任意智能体的消息中检测到预设关键词（示例中为 "APPROVE"），立即自动停止团队运行。
核心作用：确保团队在内容达到质量标准（即评审智能体批准）时及时结束任务，既避免协作过度消耗资源，也防止因无终止信号导致的无限对话。
配置完成后，打印提示确认终止条件已生效，确保团队协作有明确的 "结束节点"。

python 复制代码

# 步骤4：定义智能终止条件
# 终止条件决定团队何时停止工作，避免无限循环
termination_condition = TextMentionTermination("APPROVE")
print("终止条件配置完成")

2.4 组建协作团队

组建团队的核心是将已创建的智能体、终止条件与协作模式结合，示例中采用 "RoundRobinGroupChat"（轮询式群聊）作为协作模式，关键配置参数包括：

participants：指定团队成员列表，示例中为 "主要创作智能体 + 评审智能体"，确保团队有明确的 "生产者" 与 "审核者"。
termination_condition：关联已配置的终止条件（TextMentionTermination），让团队知道何时停止。
可选参数：包括 "max_turns"（最大对话轮次，如 10 轮，防止因未检测到关键词导致无限协作）。
组建完成后，通过打印 "团队配置摘要"，明确团队成员、协作模式、停止条件，让开发者清晰了解团队的核心配置。

python 复制代码

# 步骤5：创建多智能体团队
team = RoundRobinGroupChat(
    participants=[primary_agent, critic_agent],  # 团队成员列表
    termination_condition=termination_condition,  # 停止条件
    # max_turns=10  # 可选：最大对话轮次，防止无限循环
)

print("多智能体团队创建完成")
print("团队配置摘要：")
print(f"- 团队成员: {[agent.name for agent in [primary_agent, critic_agent]]}")
print(f"- 协作模式: 轮询协作")
print(f"- 停止条件: 评审通过(APPROVE)")

2.5 运行

运行团队协作任务需通过 "异步函数" 实现，核心步骤包括：

定义异步函数（如 "run_complete_example"），在函数内明确任务需求（示例中为 "创作关于人工智能发展与人类关系的诗歌，体现技术与人性平衡"）。
调用团队的 "run" 方法，传入任务描述，启动协作流程 ------ 此时团队会按照轮询模式，先让创作智能体输出诗歌，再让评审智能体评估，若评审不通过则提出修改建议，创作智能体优化后再次提交，直至评审智能体回复 "APPROVE"。
任务完成后，输出 "任务完成报告"，包括 "停止原因"（如 "检测到 APPROVE"）、"总消息数"（协作过程中产生的消息总量）、"最终结果"（最后一条消息内容，即达标后的诗歌），让开发者了解协作过程与成果。
最后，通过 "if name == "main": asyncio.run (run_complete_example ())" 启动异步函数，正式触发团队协作。

python 复制代码

# 步骤6：运行团队协作任务
async def run_complete_example():
    print("开始团队协作任务...")
    print("任务: 创作一首关于人工智能的诗歌")
    print("-" * 50)

    # 运行团队任务
    result = await team.run(task="请创作一首关于人工智能发展与人类关系的诗歌，要求体现技术与人性的平衡。")

    print("\n" + "=" * 50)
    print("任务完成报告")
    print("=" * 50)
    for message in result.messages:
        if message.source == 'user':
            print(f"- 用户: {message.content}")
        elif message.source == 'primary':
            print(f"- 主要创作智能体: {message.content}")
        elif message.source == 'critic':
            print(f"- 评审智能体: {message.content}")

# 执行示例
if __name__ == "__main__":
    asyncio.run(run_complete_example())

三、团队运行与监控

3.1 实时流式监控

实时流式监控的核心是 "动态跟踪协作过程"，让开发者清晰了解每个智能体的操作、输出内容与资源消耗，示例中通过异步函数 "detailed_stream_monitoring" 实现，关键步骤包括：

明确任务描述：详细定义任务需求（示例中为 "创作关于四季变换与人生哲理的现代诗歌，8-12 行，每季至少两行"），让监控有明确的 "任务目标"。
流式获取并分析消息：通过 "async for message in team.run_stream (task=task_description)" 实时获取团队协作中的每一条消息，对每条消息进行多维度分析：

消息来源：检测消息是否有 "source" 属性，输出发送消息的智能体名称（如 "primary""critic"），明确各智能体的操作时机。
内容预览：让开发者快速了解消息核心。
Token 使用情况：检测消息是否有 "models_usage" 属性，输出输入 token（prompt_tokens）与输出 token（completion_tokens）数量，帮助开发者监控资源消耗。

任务完成统计：任务结束后，统计 "总消息数""各智能体发言次数"，让开发者了解协作的整体效率与各角色的参与度。
最后，通过 "asyncio.run (detailed_stream_monitoring ())" 启动监控函数，实现协作过程的实时跟踪。

python 复制代码

# 步骤6：运行团队协作任务
async def detailed_stream_monitoring():
    """
    实时监控团队协作过程，深入了解每个智能体的思考和工作流程
    功能特点：
    - 实时显示对话流
    - 统计消息数量和来源
    - 分析Token使用情况
    - 提供任务完成摘要
    """
    print("开始实时监控团队协作...")
    # 定义具体的创作任务描述
    task_description = """
    创作任务要求：
    1. 主题：四季变换与人生哲理
    2. 形式：现代诗歌
    3. 长度：8-12行
    4. 要求：每季至少两行，体现季节特色和人生启示
    """
    print(f"任务内容: {task_description}")
    print("-" * 60)  # 分隔线，提高输出可读性

    message_count = 0  # 消息计数器
    # 使用异步流式处理实时获取团队对话消息
    async for message in team.run_stream(task=task_description):
        message_count += 1
        print(f"\n#{message_count} ", end="")  # 显示消息序号

        # 分析消息类型和内容
        if hasattr(message, 'source'):  # 检查是否为普通对话消息
            print(f"【{message.source}】", end="")  # 显示消息来源（哪个智能体）

            if hasattr(message, 'content'):  # 检查消息是否有内容
                content_preview = str(message.content)  # 获取消息内容
                print(f": {content_preview}")  # 显示消息内容预览

            # 显示token使用情况（如果可用）
            if hasattr(message, 'models_usage') and message.models_usage:
                usage = message.models_usage  # 获取使用量统计
                print(f"Token使用: 输入{usage.prompt_tokens}, 输出{usage.completion_tokens}")  # 显示输入输出token数量
        else:
            # 任务结果分析（当收到最终结果消息时）
            print(f"任务完成!")
            print(f"停止原因: {message.stop_reason}")  # 显示会话停止的具体原因
            print(f"总消息数: {len(message.messages)}")  # 显示总对话轮数

            # 统计各智能体的发言次数
            source_count = {}
            for msg in message.messages:
                if hasattr(msg, 'source'):
                    source_count[msg.source] = source_count.get(msg.source, 0) + 1

            print("各角色发言统计:")
            for source, count in source_count.items():
                print(f"{source}: {count}次")  # 显示每个智能体的发言次数统计

# 主程序入口：运行详细监控函数
asyncio.run(detailed_stream_monitoring())  # 执行异步监控函数

3.2 控制台美化输出

控制台美化输出的核心是 "提升可视化体验"，通过 AutoGen 的 "Console" 类对协作过程的输出进行格式化处理，让信息展示更清晰，示例中通过异步函数 "enhanced_console_demo" 实现，关键步骤包括：

启动美化控制台：调用 "Console" 类，传入 "team.run_stream (task = 任务描述)"（任务示例为 "创作关于城市夜晚的诗歌，体现繁华与孤独"），并设置 "output_stats=True"（显示详细统计信息）。
输出效果：Console 类会自动对消息来源、内容、token 消耗等信息进行格式化排版（如用不同标识区分智能体、清晰展示统计数据），避免原始输出的杂乱，让开发者更易读取协作信息。
任务完成后，打印提示确认协作过程分析完成，通过美化输出降低监控信息的读取成本。

python 复制代码

async def enhanced_console_demo():
    """
    使用增强的控制台输出，提供更好的可视化体验
    """
    print("启动增强型控制台界面...")
    # 使用Console类提供格式化的输出
    print("开始团队协作创作...")
    await Console(
        team.run_stream(task="写一首关于城市夜晚的诗歌，要求体现现代都市的繁华与孤独"),
        output_stats=True  # 显示详细统计信息
    )
    print("\n协作过程分析完成")

# 运行美化输出示例
asyncio.run(enhanced_console_demo())

四、高级团队控制：精准管理

4.1 智能状态管理

智能状态管理的核心是 "灵活控制团队的历史上下文"，根据任务需求选择 "清空历史" 或 "保留历史"，实现不同场景下的高效协作，示例中通过异步函数 "advanced_state_management" 演示三种核心场景：

场景 1：完全重置（全新任务）

当需要启动与历史任务无关的全新任务时，通过 "await team.reset ()" 清空团队的对话历史，让智能体以 "无历史干扰" 的状态开始工作。示例中先重置团队，再执行 "创作关于春天的诗歌" 任务，任务完成后统计消息数，确保全新任务的独立性。

场景 2：保持状态继续（相关任务）

当需要基于上一任务的成果进行后续优化时，不重置团队状态，直接提交新任务（示例中为 "保留之前的诗歌，在之前诗歌的下方，再写一首关于冬天的诗歌"）。此时智能体可参考历史对话中的诗歌内容，避免重复创作，提升协作效率，任务完成后统计总消息数，体现 "历史上下文复用" 的价值。

最后，通过 "asyncio.run (advanced_state_management ())" 启动函数，演示不同状态管理场景的实际效果。

python 复制代码

async def advanced_state_management():
    """
    演示状态管理技巧，包括重置和状态保持
    """

    # 场景1：完全重置 - 开始全新任务
    print("场景1: 完全重置团队")
    await team.reset()
    print("团队历史已清空，准备新任务")

    # 执行第一个任务
    result1 = await team.run(task="写一首关于春天的诗歌")
    print(f"任务1完成，消息数: {len(result1.messages)}")

    # 场景2：保持状态继续 - 相关任务延续
    print("\n场景2: 保持状态继续任务")
    print("基于之前的诗歌，进行新的版本创作")
    result2 = await team.run(task="保留之前的诗歌，在之前诗歌的下方，再写一首关于冬天的诗歌")
    print(f"任务2完成，消息数: {len(result2.messages)}")
    print(f"总消息数: {len(result2.messages)}")

asyncio.run(advanced_state_management())

4.2 外部控制机制

外部控制机制的核心是 "突破关键词终止的单一限制"，允许从团队外部主动触发停止信号，适用于 "需要人工干预" 或 "定时停止" 的场景，示例中通过 "ExternalTermination"（外部终止）机制实现，关键步骤包括：

创建外部终止控制器：实例化 "ExternalTermination" 类，作为外部控制的 "信号发生器"。
组建支持外部控制的团队：创建新的 RoundRobinGroupChat 团队，将 "外部终止控制器" 与 "原有关键词终止条件" 通过 "|"（或逻辑）结合，意味着团队停止的条件有两个 ------ 要么检测到 "APPROVE" 关键词，要么收到外部停止信号。
模拟外部干预：定义异步函数 "simulate_user_interruption"，模拟用户在协作过程中主动中断 ------ 通过 "await asyncio.sleep (5)" 让程序等待 5 秒，随后调用 "external_controller.set ()" 发送停止信号，触发团队停止。
并行运行任务与干预：通过 "asyncio.create_task" 分别创建 "团队协作任务"（执行 "创作机器学习长文" 任务，用 Console 美化输出）和 "外部干预任务"，再通过 "asyncio.gather" 让两个任务并行运行，模拟 "协作过程中突然外部中断" 的场景。
任务完成反馈：外部干预触发团队停止后，打印提示确认演示完成，展示外部控制的实际效果。
最后，通过 "asyncio.run (external_control_demonstration ())" 启动函数，实现外部控制机制的演示。

python 复制代码

async def external_control_demonstration():
    """
    演示如何从外部控制团队的运行和停止
    """
    # 创建外部终止控制器
    external_controller = ExternalTermination()
    # 创建支持外部控制的团队
    controllable_team = RoundRobinGroupChat(
        [primary_agent, critic_agent],
        termination_condition=external_controller | termination_condition)
    print("开始外部控制演示...")
    print("团队将在5秒后被外部停止")

    async def simulate_user_interruption():
        """
        模拟用户中断操作
        """
        await asyncio.sleep(5)
        print("用户触发停止指令...")
        external_controller.set()
        print("停止信号已发送")
        return

    # 同时运行团队任务和中断模拟
    team_task = asyncio.create_task(controllable_team.run(task="写一篇关于机器学习的长文，包含历史、现状和未来展望"))
    interruption_task = asyncio.create_task(simulate_user_interruption())
    # 等待任务完成
    await asyncio.gather(team_task, interruption_task)
    print("外部控制演示完成")


asyncio.run(external_control_demonstration())

五、智能体团队实际应用案例

该案例聚焦 "代码开发" 场景，创建包含 "开发、测试、文档" 三个角色的完整团队，实现 "从代码编写到测试、文档的全流程协作"，核心步骤包括：

5.1 代码开发团队

定义 "create_development_team" 函数，在函数内创建三个专业智能体，并组建团队：

（1）开发工程师智能体（developer）

核心定位是 "代码编写者"，通过 "system_message" 明确其专业能力与编码原则：

专业能力：擅长编写高效可读的 Python 代码、遵循 PEP8 规范、实现算法与数据结构、代码优化与性能调优，确保代码质量与规范性。
编码原则：强调 "优先可读性""添加必要注释""处理边界情况""编写单元测试"，避免代码仅能运行但难以维护或存在隐藏问题。

（2）测试工程师智能体（tester）

核心定位是 "代码质量审核者"，通过 "system_message" 明确其测试职责、禁止批准的问题与批准条件：

测试职责：涵盖代码审查、测试用例设计、边界测试、异常测试、性能测试建议、安全漏洞检查，全面排查代码问题。
禁止批准的问题：明确 "明显逻辑错误""未处理异常""性能问题""安全风险" 这四类问题必须解决，否则不批准，确保代码稳定性与安全性。
批准条件：仅当代码质量达标时，回复 "APPROVED"（注意与前文 "APPROVE" 区分，需严格匹配关键词）。

（3）技术文档工程师智能体（technical_writer）

核心定位是 "文档生产者"，通过 "system_message" 明确其文档职责与质量要求：

文档职责：负责 API 文档编写、使用示例创建、代码注释审查、用户指南制作，确保代码有完整的配套文档。
质量要求：强调文档需 "准确反映代码功能""包含使用示例""格式规范清晰"，让用户能通过文档快速理解并使用代码。

（4）组建代码开发团队

创建 RoundRobinGroupChat 团队，将上述三个智能体作为成员，设置终止条件为 "检测到 APPROVED"（与测试工程师的批准关键词匹配），并限制 "max_turns=8"（最大 8 轮协作，避免无限循环），确保团队高效且有序地完成代码开发全流程。

python 复制代码

import asyncio
from autogen_agentchat.agents import AssistantAgent
from autogen_agentchat.conditions import TextMentionTermination
from autogen_agentchat.teams import RoundRobinGroupChat
from autogen_agentchat.ui import Console
from autogen_core.models import ModelFamily
from autogen_ext.models.openai import OpenAIChatCompletionClient


# 配置DeepSeek模型的API连接参数，用于后续智能体的对话生成
model_client = OpenAIChatCompletionClient(
    model="qwen-plus",  # 指定使用的模型名称
    base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",  # DeepSeek API的基础URL
    api_key="sk-xxxxxxxxxx",  # API密钥（注意：在实际应用中应使用环境变量保护密钥）
    model_info={  # 模型能力配置信息
        "vision": False,  # 不支持视觉功能
        "function_calling": True,  # 支持函数调用
        "json_output": True,  # 支持JSON格式输出
        "family": ModelFamily.UNKNOWN,  # 模型家族分类
        "structured_output": True,  # 支持结构化输出
        "multiple_system_messages": True  # 支持多条系统消息
    },
)
print("模型客户端配置完成")


# 开发工程师
developer = AssistantAgent(
    "developer",
    description="一位资深Python开发工程师",
    model_client=model_client,
    system_message="""
    你是资深Python开发工程师，擅长：
    - 编写高效、可读的代码
    - 遵循PEP8规范
    - 实现算法和数据结构
    - 代码优化和性能调优

    编码原则：
    1. 优先考虑代码可读性
    2. 添加必要的注释
    3. 处理边界情况
    4. 编写单元测试
    """
)

# 测试工程师
tester = AssistantAgent(
    "tester",
    description="一位专业的QA测试工程师",
    model_client=model_client,
    system_message="""
    你是专业的QA测试工程师，负责：
    - 代码审查和测试用例设计
    - 边界测试和异常测试
    - 性能测试建议
    - 安全漏洞检查

    发现以下问题时阻止批准：
    - 明显的逻辑错误
    - 未处理的异常
    - 性能问题
    - 安全风险

    当代码质量达标时回复：APPROVED
    """
)

# 技术文档工程师
technical_writer = AssistantAgent(
    "documentation",
    description="一位专业的技术文档工程师",
    model_client=model_client,
    system_message="""
    你是技术文档专家，负责：
    - API文档编写
    - 使用示例创建
    - 代码注释审查
    - 用户指南制作

    确保文档：
    - 准确反映代码功能
    - 包含使用示例
    - 格式规范清晰
    """
)
dev_team = RoundRobinGroupChat([developer, tester, technical_writer],termination_condition=TextMentionTermination("APPROVED"), max_turns=10)

5.2 运行代码开发示例

定义异步函数 "development_example"，启动代码开发团队的协作，关键步骤包括：

调用 "create_development_team ()" 获取组建好的代码开发团队。
明确任务需求：开发一个 Python 函数，功能包括 "接收字符串列表→统计每个字符串出现频率→按频率降序返回字典结果"，同时需处理空列表与异常情况；输出要求包括 "完整文档字符串""使用示例""单元测试用例"，确保任务需求清晰具体。
启动协作并美化输出：通过 "Console (dev_team.run_stream (task = 任务描述))" 启动团队协作，同时用美化控制台展示过程，让开发者清晰看到 "开发→测试→文档" 的协作流程 ------ 开发工程师写代码，测试工程师审核并提出问题，开发工程师修改，直至测试工程师批准，最后文档工程师编写配套文档。
最后，通过 "asyncio.run (development_example ())" 启动函数，实现代码开发团队的全流程协作演示。

python 复制代码

# 运行代码开发示例
async def development_example():
    print("开始代码开发协作...")
    await Console(dev_team.run_stream(task="""
        开发一个Python函数，实现：
        功能要求：
        1. 接收一个字符串列表
        2. 统计每个字符串的出现频率
        3. 返回按频率降序排列的结果
        4. 处理空列表和异常情况
        输出要求：
        - 返回字典：{字符串: 频率}
        - 包含完整的文档字符串
        - 提供使用示例
        - 包含单元测试用例
        """
    ))

asyncio.run(development_example())

六、人机交互

AutoGen 提供了灵活的人机交互机制，允许在智能体团队运行过程中或运行结束后与用户进行交互。这对于需要人工监督、反馈或决策的应用场景至关重要。

6.1 人机交互的两种主要方式

6.1.1 运行中交互（使用 UserProxyAgent）

在团队执行过程中通过 UserProxyAgent 提供实时反馈。

UserProxyAgent 的工作原理：

代理机制 ：UserProxyAgent 作为用户在智能体团队中的代表
阻塞等待：当团队执行到该智能体时，暂停并等待用户输入
输入函数 ：可以通过 input_func 参数自定义输入方式（控制台、WebSocket、GUI等）

特点：

阻塞式交互 ：当团队调用 UserProxyAgent 时，执行会暂停等待用户输入
即时反馈：适合需要立即确认或决策的场景
会话连续性：交互后团队继续执行

适用场景：

需要人工批准的敏感操作
实时决策点
紧急情况处理

6.1.2 运行后交互

在团队运行结束后提供反馈，然后重新运行团队。

特点：

非阻塞式：团队完整运行后才请求反馈
持久化友好：适合保存和恢复团队状态
批处理友好：可以批量处理多个任务

实现方法：

设置最大轮次 (max_turns)
使用终止条件 (Termination Conditions)

6.2 演示示例

6.2.1 运行中交互

python 复制代码

import asyncio
from autogen_agentchat.agents import AssistantAgent, UserProxyAgent
from autogen_agentchat.conditions import TextMentionTermination
from autogen_agentchat.teams import RoundRobinGroupChat
from autogen_agentchat.ui import Console
from autogen_core.models import ModelFamily
from autogen_ext.models.openai import OpenAIChatCompletionClient

# 创建模型客户端
model_client = OpenAIChatCompletionClient(
    model="deepseek-chat",  # 指定使用的模型名称
    base_url="https://api.deepseek.com/v1",  # DeepSeek API的基础URL
    api_key="sk-xxxxxxxxxx",  # API密钥（注意：在实际应用中应使用环境变量保护密钥）
    model_info={  # 模型能力配置信息
        "vision": False,  # 不支持视觉功能
        "function_calling": True,  # 支持函数调用
        "json_output": True,  # 支持JSON格式输出
        "family": ModelFamily.UNKNOWN,  # 模型家族分类
        "structured_output": True,  # 支持结构化输出
        "multiple_system_messages": True  # 支持多条系统消息
    }
)

async def main():
    """
    运行中交互示例：诗歌创作需要人工审批
    """
    # 创建智能体
    assistant = AssistantAgent("assistant", model_client=model_client, system_message="你是一个诗人，创作优美的诗歌。完成创作后请说'请审批'等待用户批准。")
    # 创建用户代理智能体，使用控制台输入
    user_proxy = UserProxyAgent("user_proxy", input_func=lambda prompt: input(prompt))
    # 设置终止条件：当用户说"批准"时结束
    termination = TextMentionTermination("批准")
    # 创建轮询团队
    team = RoundRobinGroupChat([assistant, user_proxy],termination_condition=termination)
    # 运行团队并流式输出到控制台
    print("=== 诗歌创作审批系统 ===")
    stream = team.run_stream(task="创作一首关于春天的四行诗")
    await Console(stream)


# 运行示例
if __name__ == "__main__":
    asyncio.run(main())

6.2.2 运行后交互

python 复制代码

import asyncio
from autogen_agentchat.agents import AssistantAgent
from autogen_agentchat.teams import RoundRobinGroupChat
from autogen_agentchat.ui import Console
from autogen_core.models import ModelFamily
from autogen_ext.models.openai import OpenAIChatCompletionClient


# 创建模型客户端
model_client = OpenAIChatCompletionClient(
    model="deepseek-chat",  # 指定使用的模型名称
    base_url="https://api.deepseek.com/v1",  # DeepSeek API的基础URL
    api_key="sk-xxxxxxxxxx",  # API密钥（注意：在实际应用中应使用环境变量保护密钥）
    model_info={  # 模型能力配置信息
        "vision": False,  # 不支持视觉功能
        "function_calling": True,  # 支持函数调用
        "json_output": True,  # 支持JSON格式输出
        "family": ModelFamily.UNKNOWN,  # 模型家族分类
        "structured_output": True,  # 支持结构化输出
        "multiple_system_messages": True  # 支持多条系统消息
    }
)

async def main():
    """
    运行后交互示例：多轮对话修改诗歌
    """
    # 创建助理智能体
    assistant = AssistantAgent("assistant", model_client=model_client, system_message="你是一个专业的诗人，根据用户反馈修改诗歌。每次完成修改后说'修改完成'。")
    # 创建团队，设置每轮最大对话次数为1
    team = RoundRobinGroupChat([assistant], max_turns=1)
    # 初始任务
    task = "创作一首关于月亮的四行诗"
    print("=== 诗歌修改对话系统 ===")
    print("输入'退出'结束对话")
    while True:
        # 运行团队
        print(f"\n当前任务: {task}")
        stream = team.run_stream(task=task)
        await Console(stream)
        # 获取用户反馈
        feedback = input("\n请输入修改意见（输入'退出'结束）: ")
        if feedback.lower().strip() in ['退出', 'exit']:
            break
        # 设置下一轮任务为用户的反馈
        task = feedback

# 运行示例
if __name__ == "__main__":
    asyncio.run(main())

七、终止条件（Termination）

在 AutoGen 多智能体协作系统中，终止条件是保障团队高效、可控运行的核心机制。它不仅能避免智能体陷入无限对话循环、过度消耗资源，还能确保任务在达到预期目标时及时收尾，平衡 "质量达标" 与 "资源成本" 的关系。本部分将结合代码示例，从核心概念、工作机制、内置类型、组合策略到自定义开发，全面补充终止条件的细节说明，帮助开发者深入理解并灵活应用。

7.1 终止条件的核心概念与工作机制

7.1.1 终止条件的重要性与设计哲学

为什么必须设置终止条件？

多智能体协作的本质是 "动态交互"------ 智能体之间会基于任务需求持续传递消息、优化结果。若缺乏终止条件，可能出现两种风险：

资源浪费：智能体反复迭代却无法确定 "何时停止"，导致 Token 消耗激增、运行时间过长（例如创作智能体不断修改内容，评审智能体持续提建议，陷入无限循环）；
结果失控：任务可能在未达质量标准时 "意外停止"，或在已达标后 "过度优化"（例如代码已通过测试，仍反复调整格式）。
因此，终止条件相当于多智能体团队的 "交通警察"，既规范协作流程，又守护资源边界。

终止条件的核心价值拆解

设计哲学：三层防护理念

终止条件的设计需遵循 "主次结合、多重保障" 原则，通常分为三层防护，确保极端场景下系统仍可控：

主要条件（业务驱动）：基于核心业务逻辑的正常终止，是任务的 "预期结束方式"。例如 "评审通过（APPROVE）""经理确认"，确保任务在达到业务目标时停止；
保护条件（资源驱动）：基于资源消耗的强制终止，是 "成本防护网"。例如 "最大消息数 10 轮""Token 上限 2000"，防止主要条件未触发时资源过度消耗；
紧急条件（时间驱动）：基于时间的绝对终止，是 "最后防线"。例如 "超时 60 秒"，即使前两层条件失效，也能强制停止任务，避免进程僵死。

7.1.2 终止条件的工python作机制详解

核心逻辑："监控 - 判断 - 触发" 循环

终止条件的运行遵循固定流程，以代码示例中的 MaxMessageTermination（消息数量限制）为例：

初始化配置 ：创建终止条件实例时，定义触发阈值（如 max_messages=3，即总消息数达到 3 条时停止）；
实时监控：团队运行过程中，终止条件会监听每一条智能体消息、用户消息，实时统计消息总数；
条件判断：每新增一条消息，都会与阈值对比（如当前消息数是否 ≥ 3）；
触发停止 ：当条件满足时，立即生成 StopMessage，通知团队停止协作，并返回 "停止原因"（如 "消息数达到 3 条"）；
自动重置：每次任务运行结束后，终止条件会自动重置状态（如消息计数清零），避免影响下一次任务。
以下代码演示了 "消息数量限制" 的完整工作流程，关键细节已标注：

python 复制代码

import asyncio

from autogen_agentchat.agents import AssistantAgent
from autogen_agentchat.conditions import MaxMessageTermination, TextMentionTermination
from autogen_agentchat.teams import RoundRobinGroupChat
from autogen_core.models import ModelFamily
from autogen_ext.models.openai import OpenAIChatCompletionClient

model_client = OpenAIChatCompletionClient(
    model="deepseek-chat",  # 指定使用的模型名称
    base_url="https://api.deepseek.com/v1",  # DeepSeek API的基础URL
    api_key="sk-xxxxxxxxxx",  # API密钥（注意：在实际应用中应使用环境变量保护密钥）
    model_info={  # 模型能力配置信息
        "vision": False,  # 不支持视觉功能
        "function_calling": True,  # 支持函数调用
        "json_output": True,  # 支持JSON格式输出
        "family": ModelFamily.UNKNOWN,  # 模型家族分类
        "structured_output": True,  # 支持结构化输出
        "multiple_system_messages": True  # 支持多条系统消息
    },
)

async def termination_mechanism_deep_dive():
    """
    解析终止条件的工作机制和调用流程
    """
    # 创建主要智能体 - 负责内容生成
    primary_agent = AssistantAgent(
        "primary",
        description="一位专业的创意作家，擅长诗歌和创意内容创作",
        model_client=model_client,
        system_message="""
        你是一位专业的创意作家，擅长诗歌和创意内容创作。

        创作流程：
        1. 接收创作任务
        2. 生成初稿内容
        3. 根据反馈进行改进
        4. 持续优化直到满意

        请在内容达到高质量时提示"最终完成"。
        """
    )

    # 创建评审智能体 - 负责质量把关
    critic_agent = AssistantAgent(
        "critic",
        description="一位严格且专业的质量检查员",
        model_client=model_client,
        system_message="""
        你是严格的质量评审专家。

        评审标准：
        - 内容质量：主题明确、表达清晰
        - 创意价值：新颖独特、有启发性  
        - 技术规范：符合格式要求
        - 用户体验：易于理解、有吸引力

        评审流程：
        1. 对每个版本进行详细评审
        2. 提供具体的改进建议
        3. 当内容达到优秀标准时回复"APPROVE"
        4. 发现严重问题时要求重写
        """
    )

    print("智能体配置完成")
    print("主要智能体职责: 内容创作和迭代优化")
    print("评审智能体职责: 质量评审和最终批准")

    # 创建消息数量限制终止条件
    max_msg_termination = MaxMessageTermination(max_messages=3)

    print(f"\n终止条件配置: MaxMessageTermination(max_messages=3)")
    print("工作机制:")
    print("  • 监控所有消息的数量")
    print("  • 当总消息数达到3条时触发停止")
    print("  • 包括用户任务消息和智能体响应消息")
    print("  • 自动重置机制: 每次运行后自动重置计数")

    # 创建团队并配置终止条件
    round_robin_team = RoundRobinGroupChat([primary_agent, critic_agent], termination_condition=max_msg_termination)

    print("\n开始终止条件演示...")
    print("任务: 创作一首关于春天的诗句")
    print("-" * 50)

    # 运行第一轮对话
    result1 = await round_robin_team.run(task="创作一首关于春天的诗句")

    print(f"第一轮完成 - 停止原因: {result1.stop_reason}")
    print(f"消息数量: {len(result1.messages)}")

    # 显示终止条件状态
    print(f"\n终止条件状态分析:")
    print(f"MaxMessageTermination.terminated: {max_msg_termination.terminated}")
    print(f"自动重置: 是 (在每次run()完成后自动重置)")

    # 继续对话 - 终止条件已自动重置
    print("\n继续对话 (终止条件已自动重置)...")
    result2 = await round_robin_team.run(task="创作一首关于冬天的诗句")

    print(f"第二轮完成 - 停止原因: {result2.stop_reason}")
    print(f"消息数量: {len(result2.messages)}")
    print(f"累计总消息: {len(result1.messages) + len(result2.messages)}")
    await model_client.close()

asyncio.run(termination_mechanism_deep_dive())

关键细节说明

消息计数范围 ：MaxMessageTermination 会统计 "所有消息"，包括用户提交的任务描述、智能体的响应消息（如创作智能体的初稿、评审智能体的反馈）；
自动重置的必要性：若不自动重置，第二轮任务会继承第一轮的消息计数（如第一轮已 3 条，第二轮刚启动就触发停止），导致任务无法正常运行；
停止原因透明度 ：result.stop_reason 会明确返回终止触发的具体原因（如 "max_messages reached"），便于开发者排查问题（例如判断是正常达标还是资源超限）。

7.2 内置终止条件全面解析

AutoGen 提供了两类核心内置终止条件：资源控制型 （保障成本与效率）和业务逻辑型 （匹配业务目标），覆盖绝大多数常见场景。

7.2.1 资源控制型终止条件

1. MaxMessageTermination（消息数量限制）

核心作用：限制团队协作的总消息数，防止无限对话循环；
配置参数 ：max_messages（最大消息数，整数）；
适用场景：所有对话场景的 "基础防护"，尤其适合任务流程较固定的场景（如 "创作→评审→修改"3 轮即可完成）；
优势：逻辑简单、判断高效，无需依赖复杂计算（如 Token 统计）；
注意事项：计数包含 "用户任务消息 + 智能体响应消息"，需根据任务复杂度合理设置（例如简单诗歌创作设 5 条，复杂代码开发设 10 条）。

2. TokenUsageTermination（Token 使用限制）

核心作用：精确控制 API 调用的 Token 消耗（输入 Token + 输出 Token），直接关联成本控制；
配置参数 ：
- max_prompt_token：输入 Token 上限（智能体接收的提示词、历史对话等）；
- max_completion_token：输出 Token 上限（智能体生成的响应内容）；
适用场景：成本敏感的生产环境（如批量处理任务、API 费用有限额）；
优势：精准控制成本，避免单任务 Token 消耗过高（例如 GPT-4 按 Token 计费，可通过此条件限制单任务费用）；
要求：智能体必须支持 Token 统计（需模型客户端返回 models_usage 信息，如 OpenAI、DeepSeek 等主流模型均支持）。

3. TimeoutTermination（超时控制）

核心作用：限制任务的总运行时间，保障实时性，避免长时间无响应；
配置参数 ：timeout_seconds（超时时间，单位：秒）；
适用场景：实时性要求高的应用（如客服机器人、实时数据分析）；
优势：防止任务 "僵死"（例如智能体因网络问题长时间未响应），保障用户体验；
机制：从 team.run() 调用开始计时，无论任务是否在迭代，超时后立即强制停止。
以下代码演示了三种资源控制型终止条件的配置与组合使用：

python 复制代码

import asyncio
from autogen_agentchat.agents import AssistantAgent
from autogen_agentchat.teams import RoundRobinGroupChat
from autogen_agentchat.ui import Console
from autogen_core.models import ModelFamily
from autogen_ext.models.openai import OpenAIChatCompletionClient
from autogen_agentchat.conditions import MaxMessageTermination, TokenUsageTermination, TimeoutTermination

model_client = OpenAIChatCompletionClient(
    model="deepseek-chat",  # 指定使用的模型名称
    base_url="https://api.deepseek.com/v1",  # DeepSeek API的基础URL
    api_key="sk-xxxxxxxxxx",  # API密钥（注意：在实际应用中应使用环境变量保护密钥）
    model_info={  # 模型能力配置信息
        "vision": False,  # 不支持视觉功能
        "function_calling": True,  # 支持函数调用
        "json_output": True,  # 支持JSON格式输出
        "family": ModelFamily.UNKNOWN,  # 模型家族分类
        "structured_output": True,  # 支持结构化输出
        "multiple_system_messages": True  # 支持多条系统消息
    },
)

async def resource_control_terminations():
    """
    资源控制型终止条件详解 - 防止资源过度消耗
    """
    # 创建基础智能体
    primary_agent = AssistantAgent("primary", model_client=model_client)
    critic_agent = AssistantAgent("critic", model_client=model_client)

    # 1. 消息数量限制 - 最基本的保护机制
    message_limit = MaxMessageTermination(max_messages=5)
    print("1.MaxMessageTermination - 消息数量限制")
    print(f"配置: max_messages=5")
    print("适用场景: 所有对话场景的基础保护")
    print("优势: 简单可靠，防止无限对话循环")
    print("注意: 计数包括所有消息类型")

    # 2. Token使用限制 - 成本控制核心
    token_limit = TokenUsageTermination(
        max_prompt_token=1000,  # 输入token限制
        max_completion_token=500  # 输出token限制
    )
    print("\n2.TokenUsageTermination - Token使用限制")
    print(f"配置: max_prompt_tokens=1000, max_completion_tokens=500")
    print("适用场景: 成本敏感的生产环境")
    print("优势: 精确控制API调用成本")
    print("要求: 智能体必须报告token使用情况")

    # 3. 超时控制 - 响应时间保障
    timeout_limit = TimeoutTermination(timeout_seconds=30)
    print("\n3.TimeoutTermination - 超时控制")
    print(f"配置: timeout_seconds=30")
    print("适用场景: 实时性要求高的应用")
    print("优势: 防止长时间无响应")
    print("机制: 从任务开始计算总时间")

    # 演示资源控制组合
    print("\n资源控制组合演示")
    resource_guard = message_limit | token_limit | timeout_limit
    protected_team = RoundRobinGroupChat([primary_agent, critic_agent], termination_condition=resource_guard)
    print("保护策略: 消息数超5 或 Token超限 或 超时30秒")
    print("确保系统在任何情况下都不会失控")
    # 运行受保护的对话
    result = await Console(protected_team.run_stream(task="讨论人工智能的未来发展趋势"))
    print(result)

asyncio.run(resource_control_terminations())python

组合使用的优势

互补性：单一条件可能存在漏洞（例如 "消息数未超但 Token 超支"），组合后可覆盖所有资源风险；
灵活性 ：通过 "或逻辑"（|）实现 "任一触发"，既保障资源安全，又不影响任务正常完成（例如任务提前达标，无需等待超时或消息数上限）。

7.2.2 业务逻辑型终止条件

业务逻辑型终止条件以 "匹配业务目标" 为核心，根据任务的具体需求触发停止，适用于需要 "质量达标""角色决策" 的场景。以下结合代码示例解析两种常用类型：

1. TextMentionTermination（文本提及终止）

核心作用：监控智能体 / 用户消息中是否包含指定关键词，包含则触发停止；
配置参数 ：text（关键词，字符串，支持多个关键词用列表传入）；
工作机制：逐句扫描消息内容，不区分大小写（例如 "APPROVE""approve" 均会触发）；
适用场景：审批流程、质量确认、任务完成通知（如评审通过、用户确认）；
优势：直接匹配业务目标，逻辑直观（例如 "APPROVE" 代表质量达标，"REJECT" 代表任务终止）。

2. SourceMatchTermination（来源匹配终止）

核心作用：指定某一智能体发言后触发停止，即 "特定角色拥有终止决策权"；
配置参数 ：sources（智能体名称列表，如 ["critic", "manager"]）；
工作机制：只要指定名称的智能体发送消息，无论内容如何，立即触发停止；
适用场景：需要 "权威角色最终决策" 的场景（如经理确认后任务停止、测试工程师反馈后结束）；
优势：明确决策链，避免其他角色越权终止（例如只有评审智能体可停止任务，创作智能体无法终止）。
以下代码演示了两种业务逻辑型终止条件的配置与组合：

python 复制代码

import asyncio
from autogen_agentchat.conditions import TextMentionTermination, SourceMatchTermination

async def business_logic_terminations():
    """
    业务逻辑型终止条件 - 基于对话内容的智能停止
    """
    # 1. 文本提及终止 - 最常用的业务终止条件
    text_termination = TextMentionTermination("APPROVE")
    print("1.TextMentionTermination - 文本提及终止")
    print(f"配置: 关键词='APPROVE'")
    print("工作机制: 监控所有消息内容，检测关键词")
    print("适用场景: 审批流程、质量确认、任务完成")

    # 2. 来源匹配终止 - 基于发言者身份
    source_termination = SourceMatchTermination(sources=["critic"])
    print("2.SourceMatchTermination - 来源匹配终止")
    print(f"配置: source='critic'")
    print("工作机制: 当指定智能体发言后停止")
    print("适用场景: 最终决策权赋予特定角色")

    # 业务逻辑组合示例
    print("业务逻辑组合策略")
    business_termination = TextMentionTermination("APPROVE") | TextMentionTermination("REJECT") | SourceMatchTermination(["manager"])

    print("业务终止条件: 审批通过 或 审批拒绝 或 经理决定")

# asyncio.run(business_logic_terminations())

关键注意事项

关键词精准性 ：TextMentionTermination 的关键词需避免歧义（例如用 "APPROVED" 而非 "通过"，防止消息中正常提及 "通过测试" 时误触发）；
角色名称一致性 ：SourceMatchTermination 的 sources 需与智能体的 name 参数完全一致（例如智能体创建时 name="critic"，则 sources 必须是 ["critic"]，不能是 ["评审"]）。

7.3 终止条件组合策略

实际业务场景中，单一终止条件往往无法覆盖所有需求（例如仅用 "APPROVE" 可能导致无限等待，仅用 "消息数限制" 可能导致未达标就停止）。因此，需要通过逻辑运算符 组合多个终止条件，实现复杂业务逻辑。

7.3.1 逻辑运算符深度应用

AutoGen 支持两种核心逻辑运算符：

或运算符（ | ）：任一条件满足即停止（"宽松策略"，优先保障效率与资源）；
与运算符（ & ）：所有条件满足才停止（"严格策略"，优先保障质量与安全性）。
以下结合代码示例，解析四种常用组合策略：

策略 1：OR 组合（资源敏感型应用）

核心逻辑：业务达标、资源超限、时间超时，任一条件满足即停止；
适用场景：批量任务处理、成本敏感型应用（如每天处理 1000 个创作任务，需控制总 Token 消耗）；
优势：快速响应，避免不必要的资源消耗（例如任务提前达标则停止，无需等待资源上限）。

策略 2：AND 组合（高安全性审批）

核心逻辑：必须同时满足 "业务达标" 和 "权威决策"，才停止任务；
适用场景：高安全性要求的场景（如金融领域的合同生成，需 "法务审核通过（APPROVE）" 且 "经理确认（manager 发言）"）；
优势：双重保障，避免单一角色决策失误（例如法务通过但经理未确认，任务不停止）。

策略 3：混合组合（企业级复杂工作流）

核心逻辑：将多个 OR 组合与 AND 组合嵌套，覆盖复杂业务场景；
适用场景：企业级工作流（如代码开发："开发完成 + 测试通过"OR "资源超限" OR "超时"）；
优势：平衡效率与安全性，既保障正常流程，又防止异常场景。

策略 4：分层防护（生产环境系统）

核心逻辑：按 "优先级" 分层，优先触发业务正常终止，其次触发资源保护，最后触发紧急超时；
适用场景：生产环境的核心业务（如电商平台的智能客服，需保障用户体验与系统稳定）；
优势：主次分明，正常场景下按业务目标停止，极端场景下有资源 / 时间防护兜底。
以下代码演示了四种组合策略的配置：

python 复制代码

from autogen_agentchat.conditions import MaxMessageTermination, TokenUsageTermination, TimeoutTermination, TextMentionTermination, SourceMatchTermination


async def termination_combination_strategies():
    """
    终止条件组合策略 - 使用AND和OR运算符创建复杂逻辑
    """
    # 创建基础终止条件
    conditions = {
        'quality_approve': TextMentionTermination("APPROVE"),
        'manager_decide': SourceMatchTermination(["manager"]),
        'message_limit': MaxMessageTermination(max_messages=8),
        'token_budget': TokenUsageTermination(max_prompt_token=1500, max_completion_token=500),
        'timeout': TimeoutTermination(timeout_seconds=60)
    }

    print("可用终止条件:")
    for name, condition in conditions.items():
        print(f"{name}: {condition}")

    # 策略1: OR组合 - 任一条件满足即停止
    print("策略1: OR组合 (任一条件满足)")
    flexible_strategy = (
            conditions['quality_approve'] |  # 质量批准
            conditions['manager_decide'] |  # 经理决定
            conditions['message_limit'] |  # 消息限制
            conditions['token_budget'] |  # Token限制
            conditions['timeout']  # 超时保护
    )
    print("适用场景: 资源敏感型应用")
    print("优势: 快速响应，避免不必要消耗")
    print("配置: condition1 | condition2 | condition3")

    # 策略2: AND组合 - 所有条件满足才停止
    print("\n策略2: AND组合 (所有条件满足)")
    strict_strategy = (
            conditions['quality_approve'] &  # 必须质量批准
            conditions['manager_decide']  # 必须经理决定
    )
    print("适用场景: 高安全性要求的审批流程")
    print("优势: 双重保障，决策更可靠")
    print("配置: condition1 & condition2")

    # 策略3: 混合组合 - 复杂业务逻辑
    print("\n策略3: 混合组合 (复杂业务逻辑)")
    hybrid_strategy = (
            (conditions['quality_approve'] & conditions['manager_decide']) |  # 双审批
            (conditions['message_limit'] & conditions['token_budget']) |  # 资源耗尽
            conditions['timeout']  # 超时
    )
    print("适用场景: 企业级复杂工作流")
    print("优势: 平衡效率与安全性")
    print("配置: (A&B) | (C&D) | E")

    # 策略4: 分层防护体系
    print("\n策略4: 分层防护体系")
    layered_strategy = (
            conditions['quality_approve'] |  # 第一层: 业务正常完成
            (
                    conditions['message_limit'] |  # 第二层: 资源保护
                    conditions['token_budget'] |
                    conditions['timeout']
            )
    )
    print("适用场景: 生产环境系统")
    print("优势: 主次分明，保障系统稳定性")

组合策略的设计建议

优先 OR 组合：绝大多数场景下，OR 组合更灵活（既保障业务目标，又防止资源浪费），AND 组合仅用于高安全性场景；
明确优先级 ：分层防护策略中，业务正常终止（如 quality_approve）应放在最前面，确保优先触发；
避免过度复杂：组合条件不宜超过 5 个，否则会增加调试难度（例如判断停止原因时，需排查多个条件）。

7.4 自定义终止条件开发

当内置终止条件无法满足特殊业务需求时（例如 "基于质量评分终止""基于用户满意度终止"），AutoGen 支持通过继承 TerminationCondition 类开发自定义终止条件。

7.4.1 自定义终止条件框架

核心开发步骤

自定义终止条件需遵循固定框架，核心是实现以下四个部分：

配置类（Config） ：定义自定义条件的参数（如目标质量分、最大消息数），基于 pydantic.BaseModel 实现，确保参数合法性校验；
核心类（CustomTermination） ：继承 TerminationCondition 和 Component[Config]，实现以下关键方法：

init：初始化参数（如目标评分、计数变量）；
call：核心逻辑，接收消息列表，判断是否触发终止；
reset：任务结束后重置状态（如清空评分列表、计数清零）；
_to_config/_from_config：实现配置的序列化 / 反序列化，支持保存 / 加载配置；

辅助方法 ：根据业务需求编写辅助逻辑（如从消息中提取质量评分的 _extract_quality_score）；
测试验证：创建智能体和团队，绑定自定义条件，验证触发逻辑是否符合预期。
以下代码实现了 "基于质量评分的自定义终止条件"（当平均质量分≥8 且消息数≥3 时停止）：

python 复制代码

import asyncio
from typing import Sequence
from autogen_agentchat.agents import AssistantAgent
from autogen_agentchat.base import TerminatedException, TerminationCondition
from autogen_agentchat.messages import BaseAgentEvent, BaseChatMessage, StopMessage, ToolCallExecutionEvent
from autogen_agentchat.teams import RoundRobinGroupChat
from autogen_agentchat.ui import Console
from autogen_core import Component
from autogen_core.models import ModelFamily
from autogen_ext.models.openai import OpenAIChatCompletionClient
from pydantic import BaseModel
from typing_extensions import Self


class QualityScoreTerminationConfig(BaseModel):
    """
    质量评分终止条件配置
    """
    target_score: float
    max_messages: int


class QualityScoreTermination(TerminationCondition, Component[QualityScoreTerminationConfig]):
    """
    基于质量评分的自定义终止条件
    当平均质量评分达到目标值且消息数合理时停止
    """

    component_config_schema = QualityScoreTerminationConfig
    component_provider_override = "custom.conditions.QualityScoreTermination"

    def __init__(self, target_score: float, max_messages: int) -> None:
        self._terminated = False
        self.target_score = target_score
        self.max_messages = max_messages
        self.quality_scores = []
        self.message_count = 0

    @property
    def terminated(self) -> bool:
        return self._terminated

    async def __call__(self, messages: Sequence[BaseAgentEvent | BaseChatMessage]) -> StopMessage | None:
        if self._terminated:
            raise TerminatedException("终止条件已触发")
        # 更新消息计数
        self.message_count += len(messages)
        # 分析消息内容，提取质量评分
        for message in messages:
            if hasattr(message, 'content'):
                content = str(message.content)
                score = self._extract_quality_score(content)
                if score is not None:
                    self.quality_scores.append(score)
                    print(f"检测到质量评分: {score}")
        # 检查终止条件
        if self.quality_scores:
            avg_score = sum(self.quality_scores) / len(self.quality_scores)
            print(f"当前平均质量分: {avg_score:.2f}, 目标: {self.target_score}")
            if avg_score >= self.target_score and self.message_count >= 3:
                self._terminated = True
                return StopMessage(content=f"质量达标: 平均分{avg_score:.2f} ≥ 目标{self.target_score}", source="QualityScoreTermination")
        # 消息数量保护
        if self.message_count >= self.max_messages:
            self._terminated = True
            return StopMessage(content=f"达到最大消息数: {self.message_count}", source="QualityScoreTermination")
        return None

    def _extract_quality_score(self, content: str) -> float | None:
        """
        从消息内容中提取质量评分
        """
        import re

        # 匹配评分模式: "评分: 8.5" 或 "质量分: 7/10"
        score_patterns = [r'评分[:：]\s*(\d+(?:\.\d+)?)', r'质量分[:：]\s*(\d+(?:\.\d+)?)\s*[/]?\s*10', r'score[:：]\s*(\d+(?:\.\d+)?)']
        for pattern in score_patterns:
            match = re.search(pattern, content, re.IGNORECASE)
            if match:
                score = float(match.group(1))
                # 标准化到0-10分
                if score > 10:
                    score = 10.0
                return score
        return None

    async def reset(self) -> None:
        self._terminated = False
        self.quality_scores = []
        self.message_count = 0

    def _to_config(self) -> QualityScoreTerminationConfig:
        return QualityScoreTerminationConfig(target_score=self.target_score, max_messages=self.max_messages)

    @classmethod
    def _from_config(cls, config: QualityScoreTerminationConfig) -> Self:
        return cls(target_score=config.target_score, max_messages=config.max_messages)


model_client = OpenAIChatCompletionClient(
    model="deepseek-chat",  # 指定使用的模型名称
    base_url="https://api.deepseek.com/v1",  # DeepSeek API的基础URL
    api_key="sk-xxxxxxxxxx",  # API密钥（注意：在实际应用中应使用环境变量保护密钥）
    model_info={  # 模型能力配置信息
        "vision": False,  # 不支持视觉功能
        "function_calling": True,  # 支持函数调用
        "json_output": True,  # 支持JSON格式输出
        "family": ModelFamily.UNKNOWN,  # 模型家族分类
        "structured_output": True,  # 支持结构化输出
        "multiple_system_messages": True  # 支持多条系统消息
    },
)


async def custom_termination_demo():
    """
    自定义终止条件的应用
    """
    # 创建支持质量评分的智能体
    quality_agent = AssistantAgent(
        "quality_agent",
        description="一位质量评估专家",
        model_client=model_client,
        system_message="""
        你是质量评估专家，对每个内容版本进行评分。
        评分标准（0-10分）：
        - 内容质量: 主题明确、逻辑清晰 (0-4分)
        - 语言表达: 流畅自然、用词准确 (0-3分)  
        - 创意价值: 新颖独特、有启发性 (0-3分)
        请在评审结束时提供格式化的评分：
        "评分: 8.5" 或 "质量分: 7/10"
        当平均评分达到8分时可以考虑停止。
        """
    )

    # 创建自定义终止条件
    quality_termination = QualityScoreTermination(
        target_score=8.0,  # 目标质量分数
        max_messages=10  # 最大消息数保护
    )

    print("自定义终止条件配置:")
    print(f"目标质量分: {quality_termination.target_score}")
    print(f"最大消息数: {quality_termination.max_messages}")
    print("工作机制: 监控质量评分，计算平均值")

    quality_team = RoundRobinGroupChat([quality_agent], termination_condition=quality_termination)
    print("开始质量评分监控...")
    await Console(quality_team.run_stream(task="""评审下面这首诗歌的质量：床前明月光，疑是地上霜。举头望明月，低头思故乡。"""))

asyncio.run(custom_termination_demo())

自定义终止条件的开发建议

参数化设计 ：通过配置类（如 QualityScoreTerminationConfig）定义参数，避免硬编码（例如目标分、最大消息数可灵活调整）；
状态可重置 ：必须实现 reset 方法，否则多轮任务会相互干扰；
错误处理 ：在 call 方法中加入异常捕获（如 try-except），避免因消息格式异常导致终止条件崩溃；
日志输出：适当打印关键信息（如提取的评分、平均分），便于调试（例如判断为何未触发终止）；
兼容性 ：确保自定义条件与 AutoGen 版本兼容（继承 TerminationCondition 时，关注方法签名是否匹配最新版本）。