メインコンテンツへスキップ
Weave for Agents はパブリック プレビューです。一般提供前に、機能、API、Agents view UI は変更される可能性があります。
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_session / startSession と start_turn / startTurn を使用して、セッションとターンを開始する。
  • start_llm / startLLM で LLM Call をラップし、使用状況を記録する。
  • start_tool / startTool でツール実行をラップし、結果を記録する。
  • 生成されたセッション、ターン、ツール呼び出し を Agents ビューで表示する。

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

Weave SDK には、エージェント向けの汎用的な OTel 取り込み機構が含まれています。つまり、Weave はエージェントのコード内の任意の OTel span から情報を取得できます。ただし、Weave UI の Agents ビューでエージェントのトレースを表示するには、Weave では次の span を特別に処理する必要があります。
概念PythonTypeScriptOTel span
1 つの会話weave.start_session(...)weave.startSession(...)(span なし、ターンをグループ化)
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:) 。終了時には、例外が発生した場合も含めて、span を終了し、属性をフラッシュします。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 が必要です)。

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

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

​
Weave を初期化する

weave.init() は W&B で認証し、agent スパンを Agents ビューに送信する OTel エクスポーターを設定します。チームにその project が存在しない場合、Weave は最初に書き込んだときに作成します。 
import getpass
import os

os.environ["WANDB_API_KEY"] = getpass.getpass("W&B APIキーを入力してください: ")
os.environ["OPENAI_API_KEY"] = getpass.getpass("OpenAI APIキーを入力してください: ")

TEAM = input("W&B チーム名を入力してください: ")
PROJECT = input("W&B の project 名を入力してください: ")

import weave
weave.init(f"{TEAM}/{PROJECT}")

​
ツールを定義する

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

def wikipedia_search(query: str) -> str:
    r = requests.get(
        "https://en.wikipedia.org/w/api.php",
        params={
            "action": "query", "generator": "search", "gsrsearch": query, "gsrlimit": 1,
            "prop": "extracts", "exintro": True, "explaintext": True, "format": "json",
        },
        headers={"User-Agent": "weave-demo"},
    ).json()
    return next(iter(r["query"]["pages"].values()))["extract"]

wikipedia_tool_schema = {
    "type": "function",
    "function": {
        "name": "wikipedia_search",
        "description": "Search Wikipedia for a topic and return its intro paragraph.",
        "parameters": {
            "type": "object",
            "properties": {"query": {"type": "string"}},
            "required": ["query"],
        },
    },
}

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

ツール と Weave の初期化が完了したら、次のステップではそれらを組み合わせて完全なエージェント ループを構成します。このループでは、セッション、ターン、LLM Call、ツール呼び出し がどのように入れ子になるかを示します。 次の例では、1 つのセッションで 3 つのターンを実行します。各ターンでは、次の処理を行います。
  1. chat span を開き、ツール を呼び出すかどうかを LLM に判断させます。
  2. LLM が ツール を要求した場合は、呼び出しを execute_tool span で囲み、その結果を LLM に返します。
  3. 2 つ目の chat span を開いて、最終的な回答を生成します。
from openai import OpenAI

openai_client = OpenAI()
MODEL = "gpt-4o-mini"

def run_turn(history, user_message):
    history.append({"role": "user", "content": user_message})

    with weave.start_turn(user_message=user_message, model=MODEL):
        # LLM 呼び出し 1: モデルがツールの使用を決定する場合があります。
        with weave.start_llm(model=MODEL, provider_name="openai") as llm:
            resp = openai_client.chat.completions.create(
                model=MODEL, messages=history, tools=[wikipedia_tool_schema],
            )
            msg = resp.choices[0].message
            llm.output(msg.content or "")
            llm.usage = weave.Usage(
                input_tokens=resp.usage.prompt_tokens,
                output_tokens=resp.usage.completion_tokens,
            )
            history.append(msg.model_dump(exclude_none=True))

        # If no tool was requested, the first LLM response is the answer.
        if not msg.tool_calls:
            return msg.content

        # Execute each requested tool call.
        for tc in msg.tool_calls:
            with weave.start_tool(
                name=tc.function.name,
                arguments=tc.function.arguments,
                tool_call_id=tc.id,
            ) as tool:
                tool.result = wikipedia_search(**json.loads(tc.function.arguments))
                history.append({
                    "role": "tool",
                    "tool_call_id": tc.id,
                    "content": tool.result,
                })

        # LLM 呼び出し 2 — 最終的な回答を合成します。
        with weave.start_llm(model=MODEL, provider_name="openai") as llm:
            resp = openai_client.chat.completions.create(model=MODEL, messages=history)
            msg = resp.choices[0].message
            llm.output(msg.content)
            llm.usage = weave.Usage(
                input_tokens=resp.usage.prompt_tokens,
                output_tokens=resp.usage.completion_tokens,
            )
            history.append({"role": "assistant", "content": msg.content})
            return msg.content

with weave.start_session(agent_name="research-bot") as session:
    history = []
    for question in [
        "Who founded Anthropic?",
        "What is Claude (the AI assistant)?",
        "Summarize what we discussed in one sentence.",
    ]:
        print(f"USER: {question}")
        print(f"AGENT: {run_turn(history, question)}\n")

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

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

​
次のステップ