instrument-existing-agent-with-prefactor-sdk

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Instrument Existing Agent With Prefactor SDK

使用Prefactor SDK为已有Agent添加埋点

Instrument a working agent that was built without Prefactor.

Core principle: instrument boundaries, not business logic.

为未使用Prefactor构建的可正常运行的Agent添加埋点。

核心原则：为边界而非业务逻辑添加埋点。

Quick Start

快速开始

Identify runtime path: built-in adapter (
```
@prefactor/langchain
```
or
```
@prefactor/ai
```
) or custom
```
@prefactor/core
```
adapter.
Add one top-level run span and child spans around LLM/tool boundaries.
Preserve context propagation and package-prefixed span types.
Record error metadata and rethrow original errors.
Finish spans on success, error, cancel, and stream terminal paths.
Verify in your project's build/test/typecheck flow.

确定运行时路径：使用内置适配器（
```
@prefactor/langchain
```
或
```
@prefactor/ai
```
）或自定义
```
@prefactor/core
```
适配器。
添加一个顶级运行跨度（run span），并在LLM/工具边界周围添加子跨度。
保留上下文传播和带包前缀的跨度类型。
记录错误元数据并重新抛出原始错误。
在成功、错误、取消和流终止路径上结束跨度。
在项目的构建/测试/类型检查流程中验证。

Coding Tool Trigger Phrases

编码工具触发短语

If the user asks for any of these, apply this skill:

"instrument this existing agent"
"this agent already works, add prefactor tracing"
"wrap this existing langchain/ai agent with prefactor"
"add tracing for tool calls and runs"
"tool calls are missing in my coding tool timeline"

如果用户询问以下任何内容，请应用此技能：

"为这个已有Agent添加埋点"
"这个Agent已可正常运行，添加Prefactor追踪"
"用Prefactor封装这个已有的langchain/ai agent"
"为工具调用和运行添加追踪"
"我的编码工具时间线中缺少工具调用记录"

Use With Custom Provider Skill

与自定义Provider技能配合使用

Sometimes you need both skills.

If the framework/provider is already supported by a Prefactor adapter, use this skill directly.
If the framework/provider is not supported yet (for example a custom Google SDK agent integration), first use
```
skills/create-provider-package-with-core/SKILL.md
```
to build a custom adapter, then use this skill to instrument the existing agent with that adapter.

Recommended sequence when unsupported:

Create provider adapter with
```
@prefactor/core
```
.
Integrate adapter into the existing agent entrypoint.
Validate run/llm/tool/error spans in real executions.

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

如果框架/Provider已受Prefactor适配器支持，直接使用此技能即可。
如果框架/Provider暂未受支持（例如自定义Google SDK Agent集成），请先使用
```
skills/create-provider-package-with-core/SKILL.md
```
构建自定义适配器，再使用此技能通过该适配器为已有Agent添加埋点。

不支持场景下的推荐步骤：

使用
```
@prefactor/core
```
创建Provider适配器。
将适配器集成到已有Agent的入口点。
在实际执行中验证运行/LLM/工具/错误跨度。

Implementation Rules

实施规则

Prefer

@prefactor/langchain

@prefactor/ai

before low-level

@prefactor/core

Keep provider span types package-prefixed (
```
langchain:*
```
,
```
ai-sdk:*
```
).
Run nested work inside active context so parent/child trace trees stay intact.
Capture input/output safely (redact secrets, enforce truncation limits).
Instrumentation must never crash user code.

优先使用

@prefactor/langchain

或

@prefactor/ai

，而非底层的

@prefactor/core

。

为Provider跨度类型添加包前缀（如
```
langchain:*
```
、
```
ai-sdk:*
```
）。
在活动上下文中运行嵌套任务，以保持父/子追踪树的完整性。
安全捕获输入/输出（脱敏敏感信息，强制执行截断限制）。
埋点代码绝不能导致用户程序崩溃。

Verification

验证

Run equivalent project verification commands (for example build, typecheck, and tests).

Also run at least one real agent request and confirm:

top-level run span exists
child llm/tool spans are correctly nested
terminal status appears for success and failure

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

同时至少发起一次真实的Agent请求，并确认：

存在顶级运行跨度
子LLM/工具跨度嵌套正确
成功和失败时均显示终止状态

References

参考资料

For coding-tool-oriented keyword coverage and trigger wording, read
```
references/coding-tool-triggers.md
```
.
For an execution checklist and failure diagnostics, read
```
references/instrumentation-checklist.md
```
.

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

Common Mistakes

常见错误

Instrumenting every helper instead of boundaries.
Using generic span types.
Swallowing exceptions after logging.
Missing stream cancel/error completion paths.

为每个辅助函数而非边界添加埋点。
使用通用跨度类型。
记录日志后吞掉异常。
遗漏流取消/错误完成路径。