AutoGen 与 Microsoft Agent Framework:消息运行时与迁移验证
区分AgentChat、事件运行时和工作流,建立消息语义、终止规则与框架迁移的回归边界。
两个Agent能对话,不代表它们构成可靠的业务流程。工程上要问:消息发给谁,谁拥有下一轮执行权,重复投递怎么办,什么时候结束,失败后从哪里恢复?AutoGen不同代际的API以及Microsoft Agent Framework不能靠改几个import互换,必须先固定这些语义。
AutoGen分层:AgentChat与Core
当前AutoGen文档区分AgentChat、Core和扩展。AgentChat提供会话型Agent与团队协作的较高层接口;Core关注事件驱动Agent、消息传递和运行时;扩展连接模型客户端或其他组件。旧版0.2教程里的对象与当前稳定文档不一定兼容,复制示例前先确认版本与包名。
AgentChat中的AssistantAgent使用模型客户端完成任务,团队调度决定谁发言。Core中的事件可能定向投递,也可能经主题路由;会话文本只是消息载荷之一,运行时还有生命周期、取消、错误和订阅处理。不要把“一个Agent输出一段文字”误认为它完成了另一个Agent需要的完整结构契约。
消息至少要能关联run、发送者、接收者或主题、类型和事件ID。事件ID可辅助去重,但去重记录与副作用不在同一事务时,仍可能出现处理一半或重复执行。多进程与分布式运行还涉及投递语义、顺序与持久化,不能从本机队列推导网络可靠性。
Microsoft Agent Framework关注哪些对象
当前官方概览将Agents、Harness Agent、Workflows及Integrations作为不同能力面。Agent使用模型客户端、会话和上下文;工作流显式组织多个步骤或参与者;middleware在调用过程中扩展行为,工具和MCP负责外部能力连接。高层harness中的规划与记忆也仍依赖这些执行责任。
不要将产品演进讲成“所有旧API自动等价”。迁移前盘点:消息内容块和工具结果如何表示,历史归谁保存,流式事件顺序、终止返回值、异常类型和取消传播有何差别;同一系统提示在新模板下的角色优先级也要检查。对模型客户端、工具注册、会话存储和trace接入分别建适配层,才能逐步迁移。
终止需要多个独立条件
业务完成条件应能由可信数据判定,例如审阅通过且产物存在;工程保护还包括最大轮数、消息数、时间、Token、成本和取消。文本结束词适合辅助协议,但被外部文档或普通参与者注入时可能提前停止。接受终止事件前核对发送者及状态机,不能只做字符串包含判断。
团队停止时还要处理在途任务:取消后是否等待清理、是否保存部分结果、已发出的工具操作是否可撤销。队列为空可能只是暂时没有工作,不等于目标完成;触发预算则应报告未完成原因,不能伪造最终成功。
跟做:重复事件与伪造结束词
保存为 event_runtime.py,用Python 3.11+执行 python event_runtime.py。这是标准库机制模型,不是AutoGen或Agent Framework运行时;没有外部Agent或模型调用。
"""标准库事件路由夹具:重复事件、消息预算、终止原因可检查。"""
from collections import deque
from dataclasses import dataclass
@dataclass(frozen=True)
class Event:
id: str
sender: str
recipient: str
type: str
text: str
def replay(events, limit=5):
queue, seen, trace = deque(events), set(), []
handled = 0
while queue:
event = queue.popleft()
if event.id in seen:
trace.append('duplicate:' + event.id)
continue
if handled >= limit:
return trace, 'message-budget'
seen.add(event.id)
handled += 1
if event.recipient != 'reviewer':
trace.append('unroutable:' + event.id)
continue
# 文本内的 DONE 不是可信停止信号。
trace.append(event.type + ':' + event.id)
if event.type == 'approved' and event.sender == 'trusted-reviewer':
return trace, 'approved'
return trace, 'queue-empty'
if __name__ == '__main__':
a = Event('e1', 'writer', 'reviewer', 'draft', 'DONE')
b = Event('e2', 'trusted-reviewer', 'reviewer', 'approved', 'ok')
print(replay([a, a, b]))
print(replay([a, b], limit=1))实际输出:
(['draft:e1', 'duplicate:e1', 'approved:e2'], 'approved')
(['draft:e1'], 'message-budget')writer的文本包含DONE,但运行时只把它当draft。相同e1再次到达会被跳过;来自trusted-reviewer的approved事件结束流程。消息预算为1时在第二个新事件前停止,原因是message-budget。注意示例中的sender是固定夹具,真实系统必须绑定认证身份,不能相信客户端自报发送者。
改动接收者会得到unroutable记录;这帮助区分“模型没有回答”和“消息根本没有送达”。生产实现需要持久化处理状态、并发安全去重、死信或错误策略,本例内存set不提供跨进程保障。
如何证明迁移没有改变协作语义
先冻结模型响应夹具,回放正常、重复、乱序、工具失败、取消和超预算事件;检查每条工具调用次数、消息归属、终止原因与最终产物。再用相同数据和模型版本做端到端比较,分开记录框架差异与模型随机性。不要只比较最终回答文字:两版答案相同,但新版可能重复发了两次业务请求。
上线保留旧实现回滚入口,按小流量逐步切换;若状态格式改变,需要明确历史会话是否可恢复,不能让新运行时静默读取旧checkpoint。依据见 AutoGen官方分层 与 Agent Framework概览。本文没有宣称实际部署过两套运行时或完成跨版本迁移。
一个可核对的旧新字段迁移
2026-10-31核对的官方最小示例固定于commit 4d1674b78951。下面是该示例接口责任的对照,不是把旧字典直接传给新构造器:
| 职责 | AutoGen AgentChat | Agent Framework |
|---|---|---|
| 对象与客户端字段 | AssistantAgent,model_client | Agent,client |
| 固定指令字段 | system_message | instructions |
| 提交一次任务 | run(task=文本) | run(文本) |
| 取最终可读文本 | result.messages[-1].to_text() | result.text |
迁移例如把“只答一句话”的system_message改放instructions,并显式调整客户端类型和结果提取。若仍读取新结果的messages[-1],可能误把内部消息协议当成旧接口;先用固定响应替身断言归一化结果,再做可选模型测试。更关键的是会话:官方示例的AutoGen对象维护内部历史,而Agent Framework默认运行不自动沿用会话;多轮应用应显式提供相同session并隔离租户。工具循环的multi-turn与跨请求会话历史是两个维度,不能互相替代。
迁移指南和上述commit可用于复核字段,本文未运行该远端模型示例。真实执行它需要对应依赖、凭据及模型费用;本页已运行的仍是无模型事件夹具。旧新API未来变化时应按固定版本更新这张对照与契约测试。
课后练习展开习题收起习题
先独立作答,再展开参考思路。检查自己的解释是否包含机制、条件和反例。
AgentChat与Core的责任如何区分?
参考思路与常见误区
AgentChat提供会话与团队的高层组织,Core侧重事件、Agent运行时和消息传递;扩展连接模型等能力。
常见误区:将不同代际AutoGen对象混用。
为什么不能用消息含DONE判断业务完成?
参考思路与常见误区
不可信输入也可包含该词;终止需绑定可信事件来源和业务状态,同时有轮次、时间与成本保护。
常见误区:字符串匹配等价于可信验收。
事件去重为什么不等于exactly-once?
参考思路与常见误区
去重记录与副作用不原子时,崩溃可能造成重复或漏处理;需要业务幂等和持久化状态设计。
常见误区:一个set解决分布式副作用。
迁移到Agent Framework应如何回归?
参考思路与常见误区
先冻结响应夹具比较消息、工具次数、终止、取消和恢复,再固定模型与数据做端到端对照,保留旧版回滚。
常见误区:只改import再比较最终答案。
队列为空为何不一定完成任务?
参考思路与常见误区
可能没有可执行工作、消息丢失或等待外部输入;需要独立业务完成条件和明确结束原因。
常见误区:运行时空闲就是业务成功。