メインコンテンツへスキップ
Colab で試す · GitHub ソース Weave SDK を使用すると、一般的な SDK やカスタム ハーネスで構築されたエージェントをトレースできます。このクイックスタートでは、OpenTelemetry のスパンを送出して取得するために、独自に構築したマルチターン エージェントに Weave を手動で統合する方法を紹介します。エージェント向け Weave の概念を理解するには、エージェントをトレースする を参照してください。 Claude Agent SDK や Codex などの SDK やハーネスに Weave を統合したい場合は、エージェント インテグレーションをトレースする を参照してください。Weave は複数のエージェント構築用 SDK やエージェント ハーネスに自動でパッチを適用するため、すばやく統合できます。

学習内容

このクイックスタートを終える頃には、Weave 互換の OTel スパンを出力する、動作するマルチターンのエージェントを作成できます。また、Weave が会話、ターン、LLM Call、ツールコールをエージェントコードにどのように対応付けるのかを理解し、その同じパターンを独自のカスタム エージェントに適用できるようになります。 このガイドのコードでは、Wikipedia で情報を調べられる小規模なリサーチ エージェントを構築します。このエージェントは 3 つの質問 (3 ターン) を行い、回答のためにいつ Wikipedia を検索するかを LLM が判断します。Weave はすべてのステップ (会話、各質問、各 AI の応答、各 Wikipedia ルックアップ) を記録するため、Weave の Agents ビューで何が起きたのかを確認できます。 このガイドでは、次の方法を説明します。
  • weave.init() を使用して、agent tracing 用に Weave を初期化する。
  • start_conversation / startConversationstart_turn / startTurn を使用して、会話とターンを開始する。
  • start_llm / startLLM で LLM Call をラップし、Usage を記録する。
  • start_tool / startTool でツール実行をラップし、結果を記録する。
  • 生成された会話、ターン、ツールコールを Agents ビューで確認する。

Weave SDK とエージェントの連携の仕組み

Weave SDK には、エージェント向けの汎用的な OTel 取り込み機構が含まれており、Weave はエージェントのコード内にある任意の OTel スパンから情報を取得できます。ただし、Weave UI の Agents ビューでエージェントのトレースを表示するには、以下のスパンを Weave で特別に処理する必要があります。
概念PythonTypeScriptOTel スパン
1 つの会話weave.start_conversation(...)weave.startConversation(...)(スパンなし。ターンをグループ化)
1 回のユーザーまたはエージェントのやり取りweave.start_turn(...)weave.startTurn(...)invoke_agent
1 回の LLM API 呼び出しweave.start_llm(...)weave.startLLM(...)chat
1 回のツール実行weave.start_tool(...)weave.startTool(...)execute_tool
Python では、4 つの関数はすべてコンテキストマネージャーとして動作します (with weave.start_*(...) as obj:) 。コンテキストを抜けると、例外が発生した場合も含めて、スパンを終了し、属性を flush します。TypeScript では、返された各オブジェクトに対して .end() を呼び出します。例外が発生した場合でも確実にクリーンアップするには、try { ... } finally { obj.end(); } を使用してください。 gen_ai.usage.*gen_ai.agent.name などの他の GenAI semantic-convention attributes を指定すると、追加の表示も有効になりますが、これらは任意です。

前提条件

  • W&Bアカウントと APIキー
  • OpenAI APIキー
  • Python 3.10+ (Python の例を使用する場合)
  • Node.js 18+ (TypeScript の例では組み込みの fetch が必要です)

パッケージをインストール

次のパッケージを開発環境にインストールします。

Weave を初期化する

weave.init() は W&B で認証を行い、エージェントのスパンを Agents ビューに送信する OTel exporter を設定します。チームにそのプロジェクトが存在しない場合、Weave は最初に書き込むときにプロジェクトを作成します。

ツールを定義する

次のコードは、エージェント用の Wikipedia 検索ツールと、そのツールをいつどのように使用するかを指定する OpenAI のツールスキーマを定義しています。

トレースされたマルチターン エージェントを実行する

tool と Weave の初期化が完了したら、次のステップではそれらを組み合わせて、完全なエージェント ループを構成します。このループでは、会話、ターン、LLM Call、ツールコール がどのように入れ子になっているかを示します。 次の例では、1 つの会話で 3 つのターンを実行します。各ターンでは、次の処理を行います。
  1. chat スパン を開始し、ツールを呼び出すかどうかを LLM に選択させます。
  2. LLM がツールをリクエストした場合は、呼び出しを execute_tool スパン で囲み、その結果を LLM に戻します。
  3. 2 つ目の chat スパン を開始し、最終的な回答を生成します。

Agents ビューでエージェントのトレースを確認する

weave.init() を実行すると、以下を確認できる project へのリンクが出力されます。
  • Agents タブに research-bot の行が 1 つ表示されます。
  • 3 つのターンを含む 1 つの会話。
  • 各ターン (invoke_agent) には、2 つの chat スパンと、その内側にネストされた execute_tool スパンがあります。
  • chat のトークン数、レイテンシ、モデル、およびメッセージのやり取り全体。
いずれかのターンをクリックすると、入力、出力、ツールの引数、ツールの結果を確認できます。

次のステップ