什么是 回调处理器（Callback Handler）？
回调处理器（Callback Handler）是一种框架钩子，它在模型、工具、检索、流、工作流或 Agent 执行生命周期中接收类型化事件，用于观察或具有明确契约的拦截。
工作原理
事件身份与 Trace 结构
每个事件应携带 Run、Span 与 Parent ID，组件类型和版本，事件类型、时间、Attempt 和终态。即使存在嵌套 Agent 与异步 Tool，Start 和 End 也必须能够关联。应在一个 Adapter 边界把框架事件映射到 OpenTelemetry 等可观测 schema，而不是让供应商属性名散落在业务代码中。
Observer、Interceptor 与 Middleware
Observer 只记录事件而不改变执行；Interceptor 可以校验、脱敏、短路或替换输入输出；Middleware 通常包裹完整操作并同时控制前后流程。不同框架对名称的使用并不一致，因此必须说明 Handler 能否修改数据、取消工作、返回替代结果或触发外部副作用。正确性不能依赖未承诺的 Handler 顺序。
流式处理与可靠性
Stream 可能是单消费者资源；如果 Callback 直接读取，而框架没有正确 Tee 或复制，应用会拿不到结果。许多 Runtime 还会在主路径同步等待 Handler，因此要限制耗时、传播取消、隔离错误，并把昂贵导出放入队列。重试或恢复可能重复投递等价事件，所有外部写入都应具备幂等性。
隐私、成本与可测试性
Prompt、检索文档、工具参数、模型输出和凭证都可能包含敏感数据。遥测默认只记录 Metadata，字段采用白名单，导出前脱敏，控制保留期与访问权限，并避免把原始用户 ID 或完整 Prompt 作为高 Cardinality Label。先用合成 Event 单测 Handler，再集成测试嵌套、Stream 完成、取消、重复投递、Exporter 故障和拦截拒绝。
主要特点
- 接收包含 Run、Span、Parent、组件、Attempt 和状态的类型化事件
- 把观察或拦截与组件的主要业务逻辑分离
- 需要明确修改、取消、替换和调用顺序语义
- 必须保留 Stream 所有权并传播取消与终态错误
- 需要限制延迟、隔离故障、保证幂等并处理背压
- 默认采用仅 Metadata 遥测、字段白名单和保留策略
常见用途
- 为模型、工具、检索、工作流和 Agent 操作创建嵌套 Span
- 记录用量、延迟、结束状态、重试和供应商请求 ID
- 导出经过隐私过滤的轨迹事件用于调试与评估
- 在不消费应用结果 Stream 的前提下推送进度事件
- 在确定性授权前拦截敏感工具提议
示例
Loading code...常见问题
Callback Handler 与 Middleware 有什么区别？
只读 Callback 通常观察某个时点的事件，Middleware 则包裹完整操作并控制前后流程；部分框架允许 Callback 拦截或替换结果，使名称边界变得模糊。实现时应依据文档中的修改、顺序、取消与错误契约，而不是只看名称。
每个回调事件应该包含哪些身份字段？
至少包含 Run ID、Span ID、可选 Parent Span、组件名称与版本、事件类型、Attempt、时间和终态。模型与工具事件还需要稳定 Call ID 和结束原因，这些字段才能重建嵌套、重试、Handoff 与部分失败。
Callback Handler 能安全读取流式响应吗？
只有框架提供副本、Tee 或可重放 Event Stream 时才安全。很多 StreamReader 只能消费一次，Handler 读取后可能让调用方失去数据。必须明确 Close 与取消责任，保留 Chunk 顺序和 ID，并测试首个分片前后的错误。
Callback 失败应该中断 Agent 吗？
取决于用途。Best-effort 指标导出失败通常应隔离，授权拦截器失败则可能需要 Fail Closed。应按关键程度分类 Handler，设置超时和背压策略，并测试 Exporter 故障，避免可观测性问题悄然演变为应用故障。
Callback 应记录 Prompt 和工具参数吗？
默认不应记录。它们可能包含个人数据、凭证、私有文档或恶意载荷。优先记录 Metadata，明确白名单所需内容，导出前脱敏，限制访问与保留期，并避免将原始值作为 Metric Label。只有经过批准且目的明确时才采集正文。