多 Agent 框架、观测与治理

• 理解统一 trace 的标识体系
• 理解跨进程与跨框架的上下文传播
• 理解 OpenTelemetry / OpenInference 等标准

统一追踪需建立贯穿所有层的追踪体系：1) 统一标识——用全局唯一 taskId 作为根，向下派生 spanId、messageId、toolId、artifact 版本，所有 Agent 共享同一 trace 命名空间；2) 上下文传播——在跨进程/跨框架调用时，通过 W3C Trace Context（traceparent/tracestate）或自定义头传递 traceId 与 spanId，让 A2A 边界、HTTP、gRPC 调用都能关联到同一 trace；3) 统一事件模型——把 Agent、消息、工具调用、artifact 都建模为带属性的 span/事件，用统一 schema 记录；4) 标准工具——用 OpenTelemetry（OTel）或 OpenInference 作为统一 trace 协议，各框架（LangGraph、AutoGen、CrewAI）接入同一导出器。这样无论任务经过多少框架、进程与 A2A 跳，都能在单一 trace 视图中还原完整链路。核心是"统一 id + 上下文传播 + 标准协议"。

跨框架追踪的难点是"标识不统一、上下文不传播"。统一 taskId 与 W3C trace context 让所有跳数关联，OTel/OpenInference 提供统一 schema 与导出，最终形成端到端可观测的完整链路。

• 理解逐跳权限收缩的原则
• 理解 delegated token / scope 衰减
• 理解身份与授权分离

逐跳权限收缩的核心是"权限随调用链只减不增，低信任 Agent 不能获得上游全部身份权限"。实现：1) 每跳重新委托受限 scope——用 OAuth Token Exchange（RFC 8693）把当前 token 换成 scope 更窄的 delegated token，subject 保持用户、audience 指向被调 Agent、scope 限制到本跳所需；2) 限制不可再委托——通过声明（如 delegation 限制、max_ttl、call_chain）阻止下游 Agent 继续无限授权；3) 身份与授权分离——下游 Agent 只获得"代表用户做有限操作"的授权，而非用户的完整身份；4) 能力边界——每跳声明允许的能力与数据范围，杜绝越权；5) 审计——记录每跳的授权依据与 scope 链，便于追溯。低信任 Agent 位于链路末端，其权限已被逐级收缩到最小，即使被攻破也无法借上游身份做越权操作。

委托的本质是"权限衰减"。逐跳收缩让信任链末端的 Agent 权限最小，从机制上防止"攻破末端 = 获得全部权限"。delegated token + 不可再委托声明是标准实现。

• 理解 checkpoint 与消息持久化
• 理解幂等与去重
• 理解恢复时的副作用控制

保证幂等与避免重复副作用：1) Checkpoint——在关键步骤持久化执行状态（已处理的消息、已产出的 artifact、token 计数），恢复时从 checkpoint 继续，而非重跑整个流程；2) 消息持久化——把消息与事件持久化到可靠存储，配合幂等键（messageId/eventId）去重，重复投递被识别并丢弃；3) 幂等处理——每个副作用（写库、调用工具、发通知）绑定幂等键或使用"先查后写"，重复执行时检测到已处理则跳过；4) 恢复——崩溃后从 checkpoint 加载状态，重放未完成的步骤，但用幂等键保证已完成的副作用不重复执行；5) 原子性——把"状态更新 + 副作用"做成原子，避免"副作用已发生但状态未记录"导致恢复时重复。核心是"状态持久化 + 幂等键 + 原子副作用"，让恢复安全且不产生重复副作用。

崩溃恢复的经典难题是"副作用可能已执行但状态未保存"。checkpoint + 幂等键 + 原子性解决：恢复时对已完成的副作用跳过，对未完成的补做，从而消除重复。

• 理解按任务类型评估而非预设偏好
• 理解评估维度（能力、生态、可控性、成本、锁定）
• 理解评估矩阵与方法

评估应基于任务需求与多维标准，而非预设某框架最佳。评估维度：1) 能力匹配——框架是否支持所需模式（reAct、多 Agent、工具调用、记忆、RAG）；2) 可控性与可观测性——是否支持细粒度控制、trace、调试、checkpoint；3) 生态与集成——可用的工具、模型、存储、社区；4) 开发与维护成本——学习曲线、语言生态、部署复杂度；5) 成本与锁定——token 成本、云厂商锁定、可移植性；6) 性能与可扩展性——延迟、并发、生产就绪度。方法：定义明确的评估矩阵，为每个候选（smolagents、DSPy、LlamaIndex、云托管服务）按任务类型打分，并用 POC 在真实任务上对比。结论应"按任务选型"，例如研究/检索用 LlamaIndex、可编程 Agent 用 smolagents、需要深入学习用 DSPy、快速托管用云服务。核心是"不预设，用矩阵 + POC 决策"。

没有"最佳框架"，只有"适合特定任务与约束的框架"。用评估矩阵把主观偏好转化为可量化对比，用 POC 验证真实表现，避免"锤子思维"。

• 理解云托管服务的优势与局限
• 理解状态管理、成本、锁定风险的差异
• 理解混合选型

云托管 Agent 服务：优势是开箱即用、托管状态管理（会话、工具、文件）、快速上线、内置模型与工具；局限是状态存储与编排在供应商侧、定制受限、成本随调用增长、有锁定风险（API 与数据绑定）。自建编排：优势是状态与编排完全可控、可定制、可审计、可移植、可用自有模型与工具；局限是开发与运维成本高、需自行管理状态、弹性与工具链自建。取舍：1) 状态管理——云托管省心但数据在供应商侧，自建可控但需自己实现；2) 成本——云托管按调用计费、便利但费，自建可控但需投入研发；3) 锁定——云托管锁定风险高，自建可移植。策略：快速原型/标准场景用云托管，核心/敏感/定制场景用自建，或"云托管做外层、自建做关键内部能力"的混合。核心是"按状态敏感度、成本预算与锁定容忍度权衡"。

云托管与自建是"省心 vs 可控"的权衡。状态管理、成本、锁定是三个决策轴：越敏感/越核心越该自建，越通用/越快速越可用云托管。混合模式可兼顾。

• 理解策略即代码的价值
• 理解 OPA/Cedar 等策略引擎
• 理解约束外置与集中治理

策略即代码把权限、配额、行为约束从"提示词/代码内散落"提升为"集中声明的策略"，用 OPA（Rego）或 Cedar 等策略引擎执行。价值：1) 集中治理——策略独立成文件，统一管理、版本化、可审查，不散落在各 Agent 提示词中；2) 一致执行——所有 Agent 调用策略引擎进行授权判断，行为一致，避免"提示词遗漏导致越权"；3) 可测试——策略是代码，可做单元测试与 CI 门禁；4) 动态更新——策略热更新，无需改 Agent；5) 审计——策略评估结果可记录，支持"为什么允许/拒绝"。落地：把"Agent 能否调用某工具、某配额、某操作"建模为策略决策请求，Agent 在执行前调用 OPA/Cedar 查询（如 allow 输入 subject/action/资源），根据结果放行或拒绝。提示词只负责"如何做"，策略负责"能否做"。核心是"把安全与边界从软约束（提示词）变成硬约束（策略引擎）"。

提示词约束是"软的、可能被忽略的"，策略引擎是"硬的、强制执行的"。策略即代码把治理从 LLM 提示中剥离，交给确定性引擎，既提升安全一致性，又让策略可审查、可测试、可动态更新。

• 理解能力目录的字段与作用
• 理解发现、路由与治理
• 理解目录与信任

Agent 能力目录是统一注册表，记录每个 Agent 的能力（skills）、版本、SLA（可用性/延迟/成功率）、负责人、依赖与安全等级。它支撑：1) 发现——调用方按能力查询目录，找到匹配的 Agent，而非硬编码地址；2) 路由——基于能力、SLA、负载、成本把请求路由到合适 Agent，支持灰度与降级；3) 治理——负责人明确、版本可追踪、SLA 可监控，违规可下架，支持准入与审计；4) 信任——目录是可信清单，配合签名与健康检查，作为发现路径的信任锚。目录要与实际运行数据联动：SLA 由监控回填，能力由注册更新，失效条目被剔除。核心是"目录 = 能力的单一事实源"，把发现、路由、治理统一到一处。

能力目录是"发现"与"治理"的枢纽。它把 Agent 的能力、版本、SLA、负责人元数据集中管理，让调用方可靠发现、路由方择优分配、治理方问责。目录与运行时数据联动才不腐化。

• 理解复盘所需的轨迹与上下文
• 理解隐私保护与脱敏
• 理解最小化记录

复盘应保存可定位错误的轨迹：taskId、各 Agent 的输入/输出（结构化）、工具调用、状态转移、错误信息、时间戳、模型与 prompt 版本、决策所依据的来源引用。避免记录隐私与内部思考：1) 不记录原始个人数据正文——对个人身份、敏感内容做脱敏/掩码，只保留角色或 hash；2) 不记录内部思考——只记录"做了什么、依据什么"，不记录模型原始推理链（chain-of-thought），如确需可保留脱敏摘要；3) 结构化最小化——只记录与任务执行相关的元数据与契约字段，不记录无关上下文；4) 访问控制——复盘日志按角色授权，审计人员只能读脱敏轨迹；5) 保留期限——按合规设定保留期与删除。原则是"可复盘但最小化、脱敏、不记录内部思考"。

复盘能力与隐私保护需要平衡。保存结构化、可定位的轨迹（含来源引用与版本）足以复盘，而脱敏与排除内部思考则满足隐私与安全。这是"审得清但看不全"的设计。

• 理解契约测试的内容
• 理解版本兼容性验证
• 理解测试方法（schema 校验、状态机测试、事件测试）

契约测试用于验证版本变化不破坏兼容性：1) Agent Card 测试——校验卡片 schema 合法、字段符合版本规范、新增字段向后兼容、旧字段仍可解析；2) 状态机测试——验证所有合法状态转移仍被允许、非法转移被拒绝、终态不可再转移，用状态机测试覆盖全部路径；3) 流事件测试——验证事件 schema、顺序、字段（messageId、kind、artifact part）符合契约，客户端能正确解析增量事件。方法：1) schema 校验（JSON Schema）——对卡片与事件做结构校验；2) 双向兼容测试——新版本能读旧数据、旧版本能容忍新字段（只增不删）；3) 金丝雀/回放——用真实历史事件集回放，验证新版本解析结果一致；4) 契约仓库——把契约固化为测试套件，CI 门禁，patch 升级前跑通。核心是"版本升级必须通过契约测试，否则不允许发布"。

版本升级的回归风险在于"契约被悄悄破坏"。契约测试把 schema、状态机、事件的行为固化为可自动执行的测试，任何版本变化都必须通过，从机制上保证兼容性。

• 理解框架优势与任务类型相关
• 理解评估矩阵的设计
• 理解按任务类型差异化选型

没有"最佳框架"是因为不同任务对框架的要求不同：编码任务需要强工具调用与代码执行能力；研究任务需要多轮检索、RAG 与长上下文；客服任务需要对话管理、记忆、人格一致与延迟。衡量一个框架"最佳"必须相对任务而言。评估矩阵应按任务类型 × 评估维度设计：维度包括能力支持（工具、RAG、多 Agent、记忆）、可控性、可观测性、生态、延迟、成本、部署、锁定。列：候选框架（LangGraph、AutoGen、CrewAI、DSPy、smolagents、云服务等）；行：任务类型（编码/研究/客服）。对每个单元格打分，结合 POC 验证。例如：编码任务可能偏好工具调用强的框架，研究任务偏好 RAG 与检索框架，客服任务偏好对话与记忆框架。结论是"按任务与约束选型，而非迷信单一框架"。

"最佳"是相对任务与约束的。评估矩阵把不同任务的要求与框架的特性结构化对照，避免主观偏好与"锤子思维"。POC 验证能把矩阵打分落到真实表现。

• 理解可观测性指标
• 理解多 Agent 与单 Agent 的量化对比
• 理解数据驱动的决策

用可观测性数据判断多 Agent 必要性，需采集并对比量化指标：1) 采集——为多 Agent 与单 Agent 方案分别记录任务成功率、质量评分、token 成本、延迟、通信轮数、错误传播率、人工接管率；2) 对比——同一任务集上做 A/B 对比，看多 Agent 是否在质量/成功率上有显著提升，以及成本/延迟增加是否可接受；3) 归因——用 trace 分析"是哪个 Agent 提升了质量"或"哪个环节多余"，若某些 Agent 从未改善结果或只增加轮数，则证明冗余；4) 边际收益——逐步增加 Agent，看质量收益是否边际递减，若额外 Agent 无收益则说明单 Agent 已够。核心是"用数据回答：多 Agent 带来的质量提升是否覆盖成本与复杂度增加"，而非"听起来更先进"。

直觉容易高估多 Agent 的收益。可观测性数据把"是否必要"变成可量化问题：质量提升、成本、延迟、轮数、错误传播共同决定性价比。数据说话，避免过度设计。

• 理解每跳验证的维度
• 理解声明、能力、上下文验证
• 理解逐跳审计

每跳的权限收缩应验证三个维度：1) 声明验证——校验调用方带来的身份声明/token（subject、audience、scope、issuer）是否有效、是否过期、是否被篡改，确认"谁在调用"；2) 能力验证——校验被调 Agent 的能力边界，该操作是否在被调 Agent 允许的能力范围内，且调用方的 scope 是否覆盖该操作；3) 上下文验证——校验请求携带的上下文（数据范围、任务内容）是否在授权范围内，防止用合法 scope 请求越权数据。每跳都执行"验证声明 → 校验能力 → 校验上下文 → 收缩 scope 再传递"的流程，并记录审计。这样即使某跳被攻破，下一跳的验证也能拦截越权。核心是"每跳独立验证，而非依赖上游信任"。

逐跳收缩不是"一次性收缩后直接信任"，而是"每跳重新验证"。声明、能力、上下文三个维度分别回答"谁、能做什么、对什么数据做"，三者齐备才放行，缺一不可。

• 理解三个框架的编排模型
• 理解状态图、角色流程、Actor 运行时
• 理解适用场景

三个框架的核心差异在编排模型：1) LangGraph——以状态图（StateGraph）为核心，把 Agent 流程建模为有向图（节点 + 边 + 共享状态），强调可编程、可检查、可循环的状态机，适合复杂、需精确控制与持久化的流程；2) CrewAI——以角色（Role）为核心，通过 Crew 组织多个角色（Agent）按"流程"（顺序/层级）协作，强调角色分工与任务委派，上手快、结构清晰，适合角色化团队协作；3) AutoGen——以对话（ConversableAgent）为核心，使用 Actor 运行时，多个 Agent 通过消息对话协作，支持群聊、多轮对话与人工介入，强调动态对话与灵活性。差异：状态图（LangGraph）重精确控制，角色流程（CrewAI）重团队分工，Actor 对话（AutoGen）重动态交互。选型按"控制需求 vs 分工需求 vs 对话需求"。

三者是"图、角色、对话"三种编排范式。LangGraph 用显式状态图给出精确控制，CrewAI 用角色分工给出清晰结构，AutoGen 用 Actor 对话给出动态交互。理解差异才能按需选型。

• 理解框架与语言类型系统的结合
• 理解各语言生态的 Agent 组织方式
• 理解类型安全与结构化输出

三个框架都利用各自语言的类型系统：1) Pydantic AI（Python）——基于 Pydantic 模型定义结构化输出与工具契约，用 Python 类型系统保证 Agent 输入输出类型安全、可校验，适合 Python 生态与数据密集型任务；2) Mastra（TypeScript）——利用 TypeScript 类型系统与声明式结构组织 Agent 工作流，适合前端/JS 生态统一，强调类型安全与可组合的 workflow；3) Spring AI / LangChain4j（Java）——利用 Java 强类型与 Spring 生态，把 Agent 建模为 Spring 组件/Bean，配合依赖注入、事务与云原生基础设施，适合企业级 Java 后端。它们共同点是"用语言类型系统把 Agent 的输入、输出、工具契约固化，获得编译期校验与结构化输出"，差异在语言生态与集成方式。选型取决于团队语言与运行时生态。

语言类型系统把"Agent 的契约"从运行时校验提升到编译期，减少错误。各框架用原生类型与生态（Pydantic 类型、TS 类型、Spring Bean）组织 Agent，让 Agent 自然融入技术栈。

• 理解 token 归因维度
• 理解预算控制
• 理解异常消费告警

token 归因需按多个维度分摊：1) 按 Agent——通过 trace 记录每个 Agent 的 token 消耗；2) 按任务——以 taskId 聚合任务级成本；3) 按工具调用——记录每次工具调用的模型 token 与工具成本。预算控制：为 Agent/任务/租户设置 token 与费用预算，实时累计，接近阈值预警，超限熔断或降级。异常消费告警：1) 检测异常增长——某 Agent/任务 token 突增、循环重试、超时重跑导致的重复消耗；2) 检测异常模式——单次调用 token 异常大、无意义的重复调用；3) 告警与治理——触发告警后定位到具体 Agent/任务，压缩或熔断，并纳入审计。核心是"可观测 + 可分摊 + 可熔断"，让成本可归因到最小单元，异常可被及时发现。

多 Agent 成本会随规模失控，归因是控制的前提。按 Agent/任务/工具分摊 token 能定位成本热点，预算控制设上限，异常告警抓失控，三者构成成本治理闭环。

• 理解分层 SLO 与端到端 SLO
• 理解成功率、时延、重试率的定义
• 理解告警与故障定位

避免"只看单 Agent"，需分层定义 SLO：1) 端到端 SLO——以 taskId 聚合，定义整体成功率、端到端时延（p95/p99）、端到端重试率，作为用户体验基线；2) 单 Agent/单跳 SLO——定义每个 Agent 的成功率、时延、重试率，用于定位瓶颈；3) 分层关系——端到端指标是各层指标的复合，单 Agent 指标异常未必反映端到端，反之亦然。告警设计：1) 端到端 SLO 违反告警（对用户影响最大）；2) 单 Agent 指标异常告警（潜在瓶颈）；3) 用 trace 关联——端到端告警触发时下钻到具体 Agent/跳，定位是哪个环节拖累；4) 重试率——监控重试率异常（可能因超时、错误导致），与成功率、时延联动分析。核心是"既要端到端总账，也要单层明细，用 trace 打通两层"。

只看单 Agent 指标会漏掉"串联后的端到端问题"，只看端到端又难定位根因。分层 SLO + trace 关联，让"端到端感知 + 单层定位"同时成立，告警能快速收敛到故障源。

• 理解跨框架的状态传递问题
• 理解消息格式不一致
• 理解观测碎片化

跨框架集成会遇到三类工程问题：1) 状态传递——各框架有各自的 state 模型（LangGraph 的 StateGraph、CrewAI 的任务输出、AutoGen 的对话历史），跨框架传递状态需要统一契约（如把子任务输出序列化为标准结构再传给另一框架），否则状态丢失或不兼容；2) 消息格式——各框架消息 schema 不同（role/content 结构、工具调用格式、artifact 表示），需做格式转换与适配层，防止字段错位；3) 观测——各框架 trace 体系不同，若不统一，日志分散、无法关联端到端链路，故障定位困难。解决方案：定义统一的状态/消息契约（如标准 JSON 结构）、建立适配层转换格式、用统一 trace（OTel/OpenInference）贯通所有框架。核心是"用契约 + 适配层 + 统一观测把异构框架黏合起来"。

跨框架集成是异构系统的集成问题。状态、消息、观测三个层面都要统一：状态用契约、消息用适配、观测用统一 trace。没有统一层，集成会变成"格式地狱"与"观测黑洞"。

• 理解 OTel 与 OpenInference 的定位
• 理解 Agent trace 的 span 模型
• 理解跨框架统一观察

统一 Trace 协议落地：1) OpenTelemetry（OTel）——通用可观测性标准，提供 trace、metric、log 的统一采集与导出，用 W3C trace context 传播，覆盖基础设施与应用的通用链路；2) OpenInference——在 OTel 之上扩展 Agent/LLM 语义，定义 Agent、LLM、tool、prompt、retrieval 等 span 类型与属性，把 LLM 调用、工具调用、检索映射为可观测 span。落地方式：1) 各框架（LangGraph、AutoGen、CrewAI）接入 OpenInference 的 span 生成器，把 Agent 执行发为带语义的 span；2) 统一 exporter 导出到同一后端（Jaeger、Tempo、云 trace）；3) 用 traceId 关联跨框架调用，端到端还原链路。核心是"用 OTel 做传输底座，用 OpenInference 做 Agent 语义，统一导出与关联"。

OTel 是底座（通用、标准），OpenInference 是 Agent 语义（LLM/工具/检索）。二者叠加使多 Agent 系统既能在通用层面观测，又能看到 Agent 语义，跨框架统一。

• 理解调用拓扑建模
• 理解循环检测与 DAG 约束
• 理解死锁预防

Agent 间调用拓扑可建模为有向图（节点 = Agent，边 = 调用关系），用静态分析治理：1) 拓扑构建——从代码/配置/能力目录提取 Agent 调用关系，构建数据流图；2) 循环检测——用拓扑排序（Kahn 算法）或 DFS 检测环，若存在环（A 调 B、B 调 A）则告警并阻断，要求调用关系必须是 DAG；3) 死锁预防——检测同步等待互为依赖的路径（A 等 B、B 等 A），限制同步调用深度与等待，防止死锁；4) 治理——把"调用关系必须无环"固化为 CI 门禁，静态分析在新改动时拦截循环依赖；5) 运行时监控——结合 trace 检测实际调用中出现的环与死锁，与静态分析互补。核心是"静态图约束 + 运行时监控双保险"，从设计与运行两侧预防循环依赖与死锁。

循环依赖与死锁在运行时难以排查，最好在设计期阻止。静态数据流图 + 环检测 + DAG 门禁把问题前置，运行时 trace 作为兜底，两者结合预防循环与死锁。

• 理解声明式（Graph）与命令式（代码控制流）的差异
• 理解可维护性、可调试性、热更新
• 理解选型依据

声明式编排（Graph，如 LangGraph 的状态图）把流程建模为数据（节点/边/schema），优缺点：1) 可维护性——流程可视化、可审查、可版本化，适合复杂可变的流程；2) 可调试性——图结构清晰、可逐步回放，但需理解图抽象；3) 热更新——图是数据，可热替换/动态加载，无需重编译。命令式编排（代码控制流，如手写 if/loop/函数调用）用代码显式控制执行，优缺点：1) 可维护性——直观、符合传统编程习惯，但复杂流程的代码可能难以看清全局；2) 可调试性——用常规调试器即可，逐行可控；3) 热更新——需重新部署，不利于运行时变更。取舍：复杂/多变/需可视化的流程用声明式，简单/确定性/需深度调试的流程用命令式，或混合（声明式定骨架、命令式做细节）。核心是"可维护与热更新 vs 直观调试"的权衡。

声明式把"流程"外化为数据，换来可视化、可审查、可热更；命令式把"流程"留在代码里，换来直观与常规调试。选型取决于流程复杂度与变更频率。