AutoGen 进入维护模式之后：分阶段迁移到 Microsoft Agent Framework 的实操路线

# 盘点清单（每行一个智能体/工作流）：
#   A) 角色：单智能体工具助手 / 群聊 / 交接？
#   B) 工具契约：函数清单、签名、返回结构
#   C) 状态与记忆：有没有线程内状态、
#      外部存储、自定义记忆
#   D) 依赖精确行为的地方：
#      流式输出的分块形态、异常类型、
#      消息序列化格式
#   E) 测试覆盖：哪些路径有回归测试

官方迁移指引的顺序很明确：先盘点存量智能体，而不是上来就换依赖。盘点的产出直接决定迁移顺序——没有持久状态、工具少、行为可测的「支持分诊机器人」是理想的首批搬迁户；依赖精确流式行为、带大量线程状态的「审批类智能体」放到最后，并单独留观察期。给每个模块标上迁移批次，这成了你的迁移作战图。

# 在同一虚拟环境里并存安装：
pip install agent-framework
pip install autogen-agentchat   # 存量代码继续可用

# 验证新框架：
python -c "import agent_framework; print(agent_framework.__version__)"

# 版本注意：Python 线与 .NET 线独立发版，
#   具体版本号以 GitHub releases 页为准

两个库可以同时装在同一个环境里——这是分阶段迁移能成立的技术前提。存量 AutoGen 代码不动，新代码用 agent-framework 写，每搬完一个模块再把对应的 AutoGen 依赖摘掉。新版框架同样 MIT 开源，不绑定 Azure：模型端可以接 Azure OpenAI、OpenAI、Anthropic、Ollama 本地模型，开发与验证在哪个云都不受限制，只是深度运维（托管、遥测面板）在 Azure Foundry 上体验最完整。

# AutoGen 写法（旧）：
from autogen_agentchat.agents import AssistantAgent
agent = AssistantAgent(
    name="triage",
    model_client=model_client,
    system_prompt="你是工单分诊助手...",
    tools=[classify, lookup])

# Agent Framework 写法（新）：
from agent_framework import ChatAgent
from agent_framework.openai import OpenAIChatClient
agent = ChatAgent(
    name="triage",
    chat_client=OpenAIChatClient(),
    instructions="你是工单分诊助手...",
    tools=[classify, lookup])

# 运行与取结果：
response = await agent.run("这条工单怎么分？")
print(response.text)

单智能体迁移的模式很固定：模型客户端从构造参数变成 chat_client 注入，system_prompt 改名 instructions，工具函数原样搬——普通 Python 函数加类型标注与 docstring 就是新框架的工具契约，与 AutoGen 的函数工具几乎同构，这部分基本零成本。运行入口统一为 run()（返回结构化响应，不再直接吐字符串），异步是默认形态。迁移完立刻跑 Step 1 记的行为锚点做对照，一致才算过。

# AutoGen 写法（旧）：
# RoundRobinGroupChat([researcher, reviewer],
#                     termination_condition=...)

# Agent Framework 写法（新，示意）：
# 预置编排模式：Sequential / Concurrent /
#   Handoff / GroupChat / Magentic
from agent_framework.orchestrations import GroupChatOrchestration
orch = GroupChatOrchestration(
    members=[researcher, reviewer],
    manager=...,          # 群聊管理器，含轮转/选择策略
    termination_condition=...)

result = await orch.run("写一份技术选型报告")

群聊是 AutoGen 用户的重灾区，也是迁移中概念转换最大的一段：发言顺序不再隐式存在于聊天记录里，而是编排器与管理器的显式配置。轮转发言、按语义选择下一个发言人、发言后终止判断，这些策略在新框架的群聊编排里都有对应配置项。具体类名与参数随版本演进较快，动手时以你安装版本的官方编排文档为准——本篇写的是形态对照，不是 API 速查表。

# 工作流检查点（示意）：
#   工作流按超级步推进，每步结束可写检查点
#   内置存储：内存 / 本地文件 / Azure Cosmos DB
#   可从任意检查点恢复运行，
#   或把运行迁移到新实例（拓扑一致前提下）

# AutoGen 时代的欠账怎么补：
#   旧代码自己实现的会话持久化
#     → 评估改为框架检查点
#   旧代码的日志拼装
#     → 改为 OpenTelemetry 导出

迁移不只是平移，还是一次还债窗口。AutoGen 时代你得自己把会话状态写进数据库、自己拼日志格式；新框架里工作流引擎的检查点机制覆盖了「长任务崩了从哪续」「暂停审批后从哪恢复」「把运行搬到另一台机器」这些场景，遥测则是标准 OpenTelemetry 格式，接哪家后端都行。迁移每个模块时同步评估：旧的 DIY 持久化与日志代码，能删的删，别把旧债原样搬进新房子。

# 推荐节奏：
#   批次 1：无状态单智能体（低风险练手）
#   批次 2：带工具与简单记忆的智能体
#   批次 3：群聊/交接等多智能体编排
#   批次 4：重度依赖流式与线程状态的最后搬
#
# 每批的回滚预案：
#   双包并存期间，切回 = 改回旧的 import
#   与入口装配，存量 AutoGen 代码原样保留
#   直到该批次稳定运行一个观察期后再删

回滚能力来自并存安装：迁移期内存量代码路径完整保留，新代码出问题就切回去，不存在「迁移到一半回不了头」的窘境。观察期建议按「稳定跑过真实的业务流量」定义，而不是「测试全绿」——多智能体系统的很多问题只在真实负载下暴露。全部迁完后，从依赖里摘掉 autogen-agentchat，README 里写清新架构，这次迁移才算闭环。

最后提醒一个时间维度的判断：维护模式不等于立即停摆，存量代码短期内还能正常跑，所以迁移是「值得规划」而不是「今晚就得做」的事。真正的止损线是新特性——当你的业务需要 MCP 深度集成、检查点、或官方遥测这些只在 Agent Framework 里演进的能力时，就是启动对应批次迁移的信号。