instrument-existing-agent-with-prefactor-sdk

既存のエージェントに Prefactor SDK で計装を追加する

Prefactor を使わずに構築された、動作中のエージェントに計装を追加します。

基本原則：ビジネスロジックではなく、境界を計装します。

クイックスタート

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. トップレベルの実行スパンを1つ追加し、LLM／ツールの境界に子スパンを追加します。
5. コンテキストの伝播と、パッケージ名で始まるスパンタイプを維持します。
6. エラーメタデータを記録し、元のエラーを再スローします。
7. 成功、エラー、キャンセル、ストリームの終了経路でスパンを終了します。
8. プロジェクトのビルド／テスト／型チェックのフローで検証し、prefactor agent_instances list --agent_id <agent_id> と prefactor agent_instances agent_context <instance_id> でトレースを確認します。

前提条件

計装する前に、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

コーディングツールのトリガーフレーズ

ユーザーから次のいずれかを求められた場合は、このスキルを適用してください。

• 「この既存のエージェントに計装を追加して」
• 「このエージェントはすでに動作するので、prefactor のトレースを追加して」
• 「この既存の langchain／ai エージェントを prefactor でラップして」
• 「ツール呼び出しと実行のトレースを追加して」
• 「コーディングツールのタイムラインにツール呼び出しが表示されない」

カスタムプロバイダースキルとの併用

両方のスキルが必要になることがあります。

• フレームワーク／プロバイダーが Prefactor アダプターですでにサポートされている場合は、このスキルをそのまま使用してください。
• フレームワーク／プロバイダーがまだサポートされていない場合は、まず skills/create-provider-package-with-core/SKILL.md を使ってカスタムアダプターを作成し、その後このスキルを使って既存のエージェントにそのアダプターで計装を追加してください。

未対応の場合の推奨手順：

1. @prefactor/core でプロバイダーアダプターを作成します。
2. 既存のエージェントのエントリーポイントにアダプターを統合します。
3. 実際の実行で、実行／LLM／ツール／エラーのスパンを検証します。

実装ルール

• 低レベルの @prefactor/core よりも、組み込みアダプターを優先します。
  • LangChain → @prefactor/langchain
  • AI SDK → @prefactor/ai
  • OpenClaw → @prefactor/openclaw
• アダプターがある場合は、選択した同じアダプターパッケージ（@prefactor/ai または @prefactor/langchain）から init、withSpan、shutdown をインポートします。
• withSpan に明示的なトレーサーを渡さない限り、アダプターの init と、@prefactor/core からインポートした withSpan／shutdown を混在させないでください。
• 理由：ヘルパーのインポートを混在させると、No active tracer found が発生する可能性があります（たとえば、パッケージインスタンスがネストしている場合）。その結果、手動で追加したカスタムスパンが失われます。
• 次の例のように、インポート元のパッケージを明示します。

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

• この混在インポートによるトレーサーのリスクは、アダプタースタイルのフロー（@prefactor/ai、@prefactor/langchain）に該当しますが、@prefactor/openclaw のプラグインランタイムモデルには該当しません。
• 組み込みアダプターがない場合は、skills/create-provider-package-with-core/SKILL.md に従ってください。
• プロバイダーのスパンタイプは、パッケージ名で始まる形式（langchain:*、ai-sdk:*、openclaw:*）にします。
• 親子のトレースツリーを維持できるよう、アクティブなコンテキスト内でネストされた処理を実行します。
• 入出力を安全に記録します（シークレットのマスキング、切り詰め制限の適用）。
• 計装によってユーザーコードがクラッシュしてはなりません。

検証

プロジェクトに相当する検証コマンド（例：ビルド、型チェック、テスト）を実行します。

また、実際のエージェントリクエストを少なくとも 1 回実行し、次の点を確認します。

• トップレベルの実行スパンが存在する
• 子の LLM／ツールスパンが正しくネストされている
• 成功時と失敗時の両方で終端ステータスが表示される

参考資料

• コーディングツール向けのキーワードカバレッジとトリガーの文言については、references/coding-tool-triggers.md を参照してください。
• 実行チェックリストと失敗時の診断については、references/instrumentation-checklist.md を参照してください。

よくある間違い

• 境界ではなく、すべてのヘルパーを計装する。
• 汎用的なスパンタイプを使用する。
• ログ記録後に例外を握りつぶす。
• ストリームのキャンセル／エラー時の完了パスを見落とす。