instrument-existing-agent-with-prefactor-sdk

Instrument Existing Agent With Prefactor SDK

Instrument a working agent that was built without Prefactor.

Core principle: instrument boundaries, not business logic.

Quick Start

1. Bootstrap Prefactor credentials with skills/bootstrap-existing-agent-with-prefactor-cli/SKILL.md (prefactor setup or prefactor setup --create).
2. Inspect the project and install the matching Prefactor adapter with the project's existing package manager (bun, npm, pnpm, or yarn).
3. Identify runtime path: built-in adapter (@prefactor/langchain, @prefactor/ai, @prefactor/openclaw, @prefactor/claude) or custom @prefactor/core adapter.
4. Add one top-level run span and child spans around LLM/tool boundaries.
5. Preserve context propagation and package-prefixed span types.
6. Record error metadata and rethrow original errors.
7. Finish spans on success, error, cancel, and stream terminal paths.
8. Verify in your project's build/test/typecheck flow, then confirm traces with prefactor agent_instances list --agent_id <agent_id> and prefactor agent_instances agent_context <instance_id>.

Prerequisite

Before instrumentation, ensure these runtime credentials are set from prefactor setup output:

• PREFACTOR_API_URL
• PREFACTOR_API_TOKEN
• PREFACTOR_AGENT_ID
• PREFACTOR_AGENT_IDENTIFIER (from setup; usually 1.0.0)

Also ensure dependencies are installed via the project's package manager:

• one of @prefactor/langchain, @prefactor/ai, @prefactor/openclaw, @prefactor/claude
• @prefactor/core only when no built-in adapter is available

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"

Use With Custom Provider Skill

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, 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:

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

Implementation Rules

• Prefer built-in adapters before low-level @prefactor/core:
  • LangChain -> @prefactor/langchain
  • AI SDK -> @prefactor/ai
  • OpenClaw -> @prefactor/openclaw
• Import init, withSpan, and shutdown from the same selected adapter package (@prefactor/ai or @prefactor/langchain) when an adapter exists.
• Do not mix adapter init with withSpan/shutdown imported from @prefactor/core unless you pass an explicit tracer to withSpan.
• Why: mixed helper imports can lead to No active tracer found (for example with nested package instances), which drops manual custom spans.
• Keep imports package-local and explicit, for example:

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

• This mixed-import tracer risk applies to adapter-style flows (@prefactor/ai, @prefactor/langchain) and not to the @prefactor/openclaw plugin runtime model.
• If a built-in adapter does not exist, follow skills/create-provider-package-with-core/SKILL.md.
• Keep provider span types package-prefixed (langchain:*, ai-sdk:*, openclaw:*).
• 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.

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

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.

Common Mistakes

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