instrument-existing-agent-with-prefactor-sdk

使用 Prefactor SDK 为现有 Agent 埋点

为一个使用 Prefactor 之外的方式构建且正常运行的 Agent 埋点。

核心原则：为边界埋点，而不是为业务逻辑埋点。

快速开始

1. 使用 skills/bootstrap-existing-agent-with-prefactor-cli/SKILL.md 引导配置 Prefactor 凭据（prefactor setup 或 prefactor setup --create）。
2. 检查项目，并使用项目现有的包管理器（bun、npm、pnpm 或 yarn）安装匹配的 Prefactor 适配器。
3. 确定运行时路径：内置适配器（@prefactor/langchain、@prefactor/ai、@prefactor/openclaw、@prefactor/claude）或自定义 @prefactor/core 适配器。
4. 添加一个顶层运行 span，并在 LLM／工具边界周围添加子 span。
5. 保留上下文传播和带包名前缀的 span 类型。
6. 记录错误元数据并重新抛出原始错误。
7. 在成功、错误、取消及流终止路径上结束 span。
8. 通过项目的构建／测试／类型检查流程进行验证，然后使用 prefactor agent_instances list --agent_id <agent_id> 和 prefactor agent_instances agent_context <instance_id> 确认 trace。

前置条件

埋点之前，请确保已根据 prefactor setup 的输出设置以下运行时凭据：

• PREFACTOR_API_URL
• PREFACTOR_API_TOKEN
• PREFACTOR_AGENT_ID
• PREFACTOR_AGENT_IDENTIFIER（来自 setup；通常为 1.0.0）

另请确保已通过项目的包管理器安装依赖：

• 以下包之一：@prefactor/langchain、@prefactor/ai、@prefactor/openclaw、@prefactor/claude
• 仅当没有可用的内置适配器时才使用 @prefactor/core

编码工具触发短语

如果用户提出以下任一需求，请应用此技能：

• “为这个现有 Agent 埋点”
• “这个 Agent 已经能正常工作了，添加 Prefactor trace”
• “用 Prefactor 包装这个现有的 LangChain／AI Agent”
• “为工具调用和运行添加 trace”
• “我的编码工具时间线中缺少工具调用”

与自定义 Provider 技能搭配使用

有时需要同时使用这两项技能。

• 如果 Prefactor 适配器已支持该框架／Provider，请直接使用此技能。
• 如果尚未支持该框架／Provider，请先使用 skills/create-provider-package-with-core/SKILL.md 构建自定义适配器，然后使用此技能通过该适配器为现有 Agent 埋点。

不受支持时的推荐顺序：

1. 使用 @prefactor/core 创建 Provider 适配器。
2. 将适配器集成到现有 Agent 入口。
3. 在实际运行中验证 run／llm／tool／error span。

实现规则

• 优先使用内置适配器，而不是低层级的 @prefactor/core：
  • LangChain -> @prefactor/langchain
  • AI SDK -> @prefactor/ai
  • OpenClaw -> @prefactor/openclaw
• 如果有适配器，请从同一个选定的适配器包（@prefactor/ai 或 @prefactor/langchain）导入 init、withSpan 和 shutdown。
• 除非向 withSpan 传入显式 tracer，否则不要将适配器的 init 与从 @prefactor/core 导入的 withSpan／shutdown 混用。
• 原因：混用辅助函数导入可能导致 No active tracer found（例如存在嵌套包实例时），从而丢失手动创建的自定义 span。
• 保持导入来源明确且限定在对应包中，例如：

import { init, withSpan, shutdown } from '@prefactor/ai';
// or
import { init, withSpan, shutdown } from '@prefactor/langchain';

• 这种混合导入导致的 tracer 风险适用于适配器式流程（@prefactor/ai、@prefactor/langchain），不适用于 @prefactor/openclaw 插件运行时模型。
• 如果没有内置适配器，请遵循 skills/create-provider-package-with-core/SKILL.md。
• 保持 Provider span 类型带有包名前缀（langchain:*、ai-sdk:*、openclaw:*）。
• 在活动上下文中运行嵌套工作，以保持父子 trace 树完整。
• 安全地捕获输入／输出（脱敏机密信息，并设置截断限制）。
• 埋点绝不能导致用户代码崩溃。

验证

运行等效的项目验证命令（例如构建、类型检查和测试）。

还要运行至少一次真实的 Agent 请求，并确认：

• 存在顶层运行 span
• 子级 llm/tool span 的嵌套关系正确
• 成功和失败时都会显示终止状态

参考资料

• 如需了解面向编码工具的关键词覆盖和触发措辞，请阅读 references/coding-tool-triggers.md。
• 如需查看执行检查清单和故障诊断，请阅读 references/instrumentation-checklist.md。

常见错误

• 为每个辅助函数埋点，而不是在边界处埋点。
• 使用通用 span 类型。
• 记录日志后吞掉异常。
• 遗漏流取消或错误完成路径。