agentlens-tracing-instrument

Forge AgentLens 計装

編集または初期化の前に、ログイン確認を完了してください。 有効なログインがない場合は、そのセクションの返信だけを送信して停止してください。

Forge は、プライベートな OTel プロバイダーを通じて明示的なエージェントスパンをエクスポートします。 フレームワークを自動計装したり、グローバルプロバイダーを置き換えたり、そのプロバイダーのスパンをエクスポートしたりすることはありません。

有効なログインを確認した後、編集する前に Python または TypeScript のリファレンスと トレースの忠実性を読んでください。 インストール済み SDK バージョンに照らして API を検証してください。

まずログインを確認する

コードを編集したりトレースを初期化したりする前に、設定済みの SDK またはコネクターを通じて、 非対話型かつ読み取り専用の ID リクエストを行い、対象デプロイメントに対する既存の W&B ログインを確認してください。 認証情報はそのまま使用してください。秘密の値を表示、コピー、または調べてはいけません。 ログイン確認のために login やトレースの init を呼び出してはいけません。

有効なログインがない場合は停止してください。このスキルで編集、初期化、続行をしてはいけません。 このセッションで wandb login を実行してはいけません。このセッションのシェルは通常の ターミナルではないため、wandb login --verify を実行するとプロンプトが表示されず、 代わりに No API key configured で終了します。このチャットでキーを尋ねたり、認証情報を作成したりしないでください。

これだけを送信し、それ以外は何も送信しないでください。判断、メモ、計画、 ドキュメントへのリンクは含めないでください。

W&B にまだログインしていないため、ここで停止します。新しいターミナルタブを開き、 wandb login --verify を実行してください。API キーは https://wandb.ai/authorize?ref=models で作成してください。ブラウザーで別のページが開いた場合は、 そのリンクをもう一度開いてください。キーはここではなく、そのターミナルに貼り付けてから、「続行」と入力してください。

セルフホスト型または専用のデプロイメントでは、wandb login --verify --host <base-url> と、そのコマンドで表示される認証ページを使用してください。それでも、これだけを送信してください。

• 接続または権限の問題で確認できない、または確認に失敗した場合は、 ログイン／アクセスを未確認と報告して停止してください。認証情報が無効だと決めつけてはいけません。
• ユーザーが続行した後、アプリケーションのランタイムが独自に設定された 認証情報を使用して entity/project にアクセスできることを確認してください。 ブラウザーでのログインだけでは SDK の認証は確立されません。.netrc によるフォールバックがない Node／Forge ランタイムでは、 ユーザーがランタイムのシークレット管理機構を通じて認証情報を設定する必要があります。

計装する

• entity/project を確認してください。プロジェクト名だけではエンティティを解決できません。プロセスごとに 1 回だけ、ランタイムの WANDB_API_KEY を使って初期化してください。認証情報を表示またはコミットしてはいけません。
• Conversation → Turn → LLM／Tool／SubAgent を実際の境界に対応付けます。ユーザーとのやり取りごとに 1 つの turn、ストリーム消費中に 1 つの LLM スパン、実行ごとに 1 つのツールとします。プロバイダーのツール呼び出し ID を保持し、委譲した作業には明示的な親を指定してください。
• 出力、例外、再試行、キャンセルを保持してください。失敗時もスパンを閉じ、既存の計装による重複記録を避けてください。
• 作業中はプロジェクトのルーティングを安定させてください。フラッシュ／シャットダウンはリクエストごとではなく、プロセス終了時に行ってください。Python はコンテンツの抑制をサポートしますが、この TypeScript リビジョンでは機密フィールドを明示的に省く必要があります。いずれも PII をマスキングしません。

段階的に実装する

トレースする経路を 1 つずつ追加してください。まずモデル呼び出し、次にそのツールループ、その後、該当する場合は委譲や並行処理を追加します。変更するたびに、その経路を実行し、 読み戻し検証に従ってください。計装を拡張する前に、出力されたスパンと保存済みスパンを実際の実行と比較してください。

不一致を修正し、続行する前に同じ確認を再実行してください。結果が空の場合、クエリが失敗した場合、確認できない場合は、合格ではなく未検証です。その時点で停止し、検証を進めるためにユーザーが行う必要のあることを報告してください。

検証

計測したパスに対して、成功、失敗、重複するリクエストを含めて適合性チェックを実行します。テストスイート全体の実行に CI、ブラウザー、または利用できないサービスが必要な場合は、実行可能なローカルチェックを行い、スキップしたカバレッジを報告します。 親子関係、ツール呼び出し ID、および gen_ai.operation.name の値である invoke_agent、chat、execute_tool を、Forge のプロバイダーまたはローカルの OTLP レシーバーを使って検証します。承認済みの認証情報が利用可能な場合は、バックエンドへの到達を確認します。利用できない場合は、未検証として報告します。初期化やフラッシュの成功だけでは、配信の証明になりません。