クイックスタート: カスタムエージェントの可観測性を設定する

CoreWeave Forge SDK を使用すると、一般的な SDK やカスタムハーネスで構築したエージェントをトレースできます。このクイックスタートでは、独自に構築したマルチターンエージェントに CoreWeave Agent Lens を手動で統合し、OpenTelemetry スパンを出力して取得する方法を説明します。エージェント向け Agent Lens の概要については、エージェントをトレースするを参照してください。 Claude Agent SDK や Codex などの SDK やハーネスに Agent Lens を統合する場合は、エージェントインテグレーションを選択するを参照してください。Agent Lens は、エージェント構築用の各種 SDK やエージェントハーネスに自動でパッチを適用するため、すばやく統合できます。

学習内容

このクイックスタートを終えると、Agent Lens 互換の OTel スパンを出力するマルチターンエージェントが動作する状態になります。また、Agent Lens が会話、ターン、LLM Call、ツール呼び出しをエージェントコードにどのように対応付けるかを理解できるため、同じパターンを独自のカスタムエージェントにも適用できるようになります。このガイドのコードでは、Wikipedia で情報を調べられる小規模な Python または TypeScript のリサーチエージェントをセットアップします。このエージェントは 3 つの質問 (3 ターン) を行い、Wikipedia を検索して回答を探すタイミングを LLM に判断させます。Agent Lens はすべてのステップ (会話、各質問、各 AI の応答、各 Wikipedia ルックアップ) を記録するため、Agent Lens の Conversations タブで処理の流れを確認できます。このガイドでは、次の方法を説明します。

tracing.init() を使用して、エージェントトレース用に Agent Lens を初期化する。
start_conversation / startConversation と start_turn / startTurn を使用して、会話とターンを開始する。
start_llm / startLLM で LLM Call をラップし、使用量を記録する。
start_tool / startTool でツール実行をラップし、結果を記録する。
トークン数とコストがレンダリングされるように、完全なトークン使用量と料金を算出可能なモデルを記録する。
生成された会話、ターン、ツール呼び出しを Conversations タブで表示する。

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

Agent Lens SDK には、エージェント向けの汎用的な OTel 取り込みシステムが含まれています。そのため、Agent Lens はエージェントのコード内にある任意の OTel スパンから情報を取得できます。ただし、Agent Lens UI の Conversations タブでエージェントのトレースをレンダリングするには、以下のスパンを特別に処理する必要があります。

概念	Python	TypeScript	OTel スパン
1 つの会話	`tracing.start_conversation(...)`	`tracing.startConversation(...)`	(スパンなし、ターンをグループ化)
ユーザーまたはエージェントによる 1 回のやり取り	`tracing.start_turn(...)`	`tracing.startTurn(...)`	`invoke_agent`
1 回の LLM API 呼び出し	`tracing.start_llm(...)`	`tracing.startLLM(...)`	`chat`
1 回のツール実行	`tracing.start_tool(...)`	`tracing.startTool(...)`	`execute_tool`

Python では、4 つの関数はいずれもコンテキストマネージャーとして使用できます (with tracing.start_*(...) as obj:) 。ブロックを抜ける際には、例外が発生した場合も含め、スパンが終了し属性がフラッシュされます。TypeScript では、返された各オブジェクトに対して .end() を呼び出してください。例外発生時にも確実にクリーンアップされるよう try { ... } finally { obj.end(); } を使用し、同時に実行される run 同士が会話を共有しないよう、エージェントの各 run を tracing.runIsolated() でラップしてください。 gen_ai.usage.* や gen_ai.agent.name など、その他の GenAI セマンティック規約の属性を使用すると追加のレンダリングが可能になりますが、これらは必須ではありません。

前提条件

CoreWeave Forge アカウントと APIキー
OpenAI APIキー
Python 3.9 以降 (Python のサンプルを使用する場合)
Node.js 18 以降と、tsx などの TypeScript ランナー (TypeScript のサンプルは組み込みの fetch を必要とし、プレーンな JavaScript としては実行できません)

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

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

pip install coreweave openai requests

npm install @coreweave/forge-sdk openai
npm install --save-dev tsx

TypeScript のサンプルは .mts ファイルとして保存し、npx tsx [FILENAME].mts で実行します。

Agent Lens を初期化する

tracing.init() は APIキーで認証を行い、エージェントスパンを Agent Lens に送信する OTel エクスポーターを設定します。プロジェクト名にはチーム名を含める必要があります。SDK は WANDB_API_KEY 環境変数から APIキーを読み取りますが、api_key / apiKey 引数で渡すこともできます。

import getpass
import os

os.environ["WANDB_API_KEY"] = getpass.getpass("Enter your API key: ")
os.environ["OPENAI_API_KEY"] = getpass.getpass("Enter your OpenAI API key: ")

TEAM = input("Enter your team name: ")
PROJECT = input("Enter your project name: ")

from coreweave.forge.agentlens import tracing
tracing.init(f"{TEAM}/{PROJECT}", autopatch_integrations=False)

// このプロジェクトを実行する前に、環境に WANDB_API_KEY と OPENAI_API_KEY を設定してください
import { tracing } from '@coreweave/forge-sdk/agentlens';

await tracing.init('[YOUR-TEAM]/[YOUR-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": "agent-lens-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"],
        },
    },
}

async function wikipediaSearch(query: string): Promise<string> {
  const url = new URL('https://en.wikipedia.org/w/api.php');
  url.search = new URLSearchParams({
    action: 'query',
    generator: 'search',
    gsrsearch: query,
    gsrlimit: '1',
    prop: 'extracts',
    exintro: 'true',
    explaintext: 'true',
    format: 'json',
  }).toString();
  const res = await fetch(url, { headers: { 'User-Agent': 'agent-lens-demo' } });
  const data = (await res.json()) as {
    query: { pages: Record<string, { extract: string }> };
  };
  return Object.values(data.query.pages)[0].extract;
}

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

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

ツールと Agent Lens の初期化が完了したら、次のステップではそれらを組み合わせて完全なエージェントループを構築します。このループを見ると、会話、ターン、LLM Call、ツール呼び出しがどのようにネストされるかがわかります。次の例では、1 つの会話の中で 3 つのターンを実行します。各ターンでは次の処理を行います。

chat スパンを開始し、ツールを呼び出すかどうかを LLM に判断させます。
LLM がツールの使用をリクエストした場合は、その呼び出しを囲む execute_tool スパンを開始し、結果を LLM に返します。
2 つ目の chat スパンを開始し、最終的な回答を生成します。

Agent Lens SDK は、OpenAI、Anthropic、Google Gen AI の各クライアントライブラリによる呼び出しを自動的にトレースします。このクイックスタートでは、スパン同士の関係を示すために start_llm() を使用して各 LLM Call を手動で記録するので、init() に autopatch_integrations=False を渡しています。これを指定しないと、各呼び出しが start_llm() スパンと自動インテグレーションの両方で記録され、二重に記録されます。この引数は最初の init() 呼び出しで渡してください。以前の呼び出しで適用されたパッチは、後から autopatch_integrations=False を指定して呼び出しても削除されません。独自のコードでは、自動パッチ適用で LLM Call を記録するか、自動パッチ適用を無効にして自分で記録するかのどちらかにしてください。

from coreweave.forge.agentlens import tracing
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 tracing.start_turn(user_message=user_message, model=MODEL):
        # LLM Call 1: モデルがツールを使用すると判断する場合があります。
        with tracing.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 "")
            # record() は、使用量、料金計算の対象となるモデル、応答 ID をまとめて設定します。
            llm.record(
                usage=tracing.Usage(
                    input_tokens=resp.usage.prompt_tokens,
                    output_tokens=resp.usage.completion_tokens,
                    cache_read_input_tokens=getattr(
                        resp.usage.prompt_tokens_details, "cached_tokens", 0
                    ),
                ),
                response_id=resp.id,
                response_model=resp.model,
            )
            history.append(msg.model_dump(exclude_none=True))

        # ツールがリクエストされなかった場合は、最初の LLM の応答をそのまま回答とします。
        if not msg.tool_calls:
            return msg.content

        # リクエストされたツール呼び出しを 1 つずつ実行します。
        for tc in msg.tool_calls:
            with tracing.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 Call 2: 最終的な回答を生成します。
        with tracing.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.record(
                usage=tracing.Usage(
                    input_tokens=resp.usage.prompt_tokens,
                    output_tokens=resp.usage.completion_tokens,
                    cache_read_input_tokens=getattr(
                        resp.usage.prompt_tokens_details, "cached_tokens", 0
                    ),
                ),
                response_id=resp.id,
                response_model=resp.model,
            )
            history.append({"role": "assistant", "content": msg.content})
            return msg.content

tracing.init(f"{TEAM}/{PROJECT}", autopatch_integrations=False)

with tracing.start_conversation(agent_name="research-bot") as conversation:
    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")

tracing.shutdown()

import { tracing } from '@coreweave/forge-sdk/agentlens';
import OpenAI from 'openai';

const openaiClient = new OpenAI();
const MODEL = 'gpt-4o-mini';

// history は OpenAI のチャットメッセージのリストです。簡潔にするため、型指定は緩くしています。
async function runTurn(history: any[], userMessage: string): Promise<string | null> {
  history.push({ role: 'user', content: userMessage });

  const turn = tracing.startTurn({ userMessage, model: MODEL });
  try {
    // LLM Call 1: モデルがツールを使用すると判断する場合があります。
    const llm1 = tracing.startLLM({ model: MODEL, providerName: 'openai' });
    let msg;
    try {
      const resp = await openaiClient.chat.completions.create({
        model: MODEL,
        messages: history,
        tools: [wikipediaToolSchema],
      });
      msg = resp.choices[0].message;
      llm1.output(msg.content ?? '');
      // record() は、使用量、料金計算の対象モデル、応答 ID を 1 回の呼び出しでまとめて設定します。
      llm1.record({
        usage: {
          inputTokens: resp.usage?.prompt_tokens,
          outputTokens: resp.usage?.completion_tokens,
          cacheReadInputTokens: resp.usage?.prompt_tokens_details?.cached_tokens,
        },
        responseId: resp.id,
        responseModel: resp.model,
      });
      history.push(msg);
    } finally {
      llm1.end();
    }

    // ツールがリクエストされなかった場合は、最初の LLM の応答がそのまま回答になります。
    if (!msg.tool_calls?.length) {
      return msg.content ?? null;
    }

    // リクエストされたツール呼び出しをそれぞれ実行します。
    for (const tc of msg.tool_calls) {
      if (tc.type !== 'function') continue;
      const tool = tracing.startTool({
        name: tc.function.name,
        args: tc.function.arguments,
        toolCallId: tc.id,
      });
      try {
        const { query } = JSON.parse(tc.function.arguments);
        tool.result = await wikipediaSearch(query);
        history.push({ role: 'tool', tool_call_id: tc.id, content: tool.result });
      } finally {
        tool.end();
      }
    }

    // LLM Call 2: 最終的な回答を生成します。
    const llm2 = tracing.startLLM({ model: MODEL, providerName: 'openai' });
    try {
      const resp = await openaiClient.chat.completions.create({
        model: MODEL,
        messages: history,
      });
      const msg2 = resp.choices[0].message;
      llm2.output(msg2.content ?? '');
      llm2.record({
        usage: {
          inputTokens: resp.usage?.prompt_tokens,
          outputTokens: resp.usage?.completion_tokens,
          cacheReadInputTokens: resp.usage?.prompt_tokens_details?.cached_tokens,
        },
        responseId: resp.id,
        responseModel: resp.model,
      });
      history.push({ role: 'assistant', content: msg2.content });
      return msg2.content ?? null;
    } finally {
      llm2.end();
    }
  } finally {
    turn.end();
  }
}

await tracing.init('[YOUR-TEAM]/[YOUR-PROJECT]');

await tracing.runIsolated(async () => {
  const conversation = tracing.startConversation({ agentName: 'research-bot' });
  try {
    const history: any[] = [];
    for (const question of [
      'Who founded Anthropic?',
      'What is Claude (the AI assistant)?',
      'Summarize what we discussed in one sentence.',
    ]) {
      console.log(`USER: ${question}`);
      console.log(`AGENT: ${await runTurn(history, question)}\n`);
    }
  } finally {
    conversation.end();
  }
});

await tracing.shutdown();

トークン使用量とコストを記録する

各 chat スパンには、トークン使用量とモデル ID が含まれます。Agent Lens は使用量からトークン数をレンダリングし、使用量とモデル ID からコストを算出します。そのため、値が不完全な場合や価格を算出できない場合は、トレースの他の部分が正しく見えていても、トークンが 0 in / 0 out、またはコストが Cost - と表示されます。record(...) を使用すると、これらのフィールド (output_messages、response_id、reasoning など) を 1 回の呼び出しでまとめて設定できます。適用されるのは、渡したフィールドのみです。コストを表示するには、次の 2 点を正しく設定する必要があります。

完全な使用量。 input_tokens は、キャッシュされたトークンを含む入力の合計です。Agent Lens はキャッシュの読み取りと書き込みをそれぞれ個別の料金で計算し、入力の合計から差し引きます。そのため、cache_read_input_tokens と cache_creation_input_tokens は、これらを含めた合計の input_tokens とあわせて報告する必要があります。プロンプトキャッシュを備えたプロバイダー (Anthropic など) では、キャッシュされたトークンが入力の大半を占めることが多いため、これらを省略すると使用量とコストがほぼゼロとしてレンダリングされます。
価格を算出できるモデル ID。 応答で返される具体的な ID (resp.model) を response_model として渡します。コストはモデルに基づくルックアップで算出されます。Agent Lens は response_model (プロバイダーが実際に使用したモデル) を優先し、これがない場合は start_llm に渡した model を使用します。opus や sonnet などのエイリアスでは価格を算出できず、Cost - と表示されます。

OpenAI はキャッシュされたトークンを prompt_tokens に含めてカウントするため、上記の例をそのまま適用できます。一方、Anthropic はキャッシュされたトークンを input_tokens とは別に報告するため、Agent Lens が価格計算に使用する合計にこれらを加算してください。

with tracing.start_llm(model=MODEL, provider_name="anthropic") as llm:
    resp = anthropic_client.messages.create(
        model=MODEL, max_tokens=1024, messages=history,
    )
    u = resp.usage
    llm.output(resp.content[0].text)
    llm.record(
        usage=tracing.Usage(
            input_tokens=u.input_tokens
            + u.cache_read_input_tokens
            + u.cache_creation_input_tokens,
            output_tokens=u.output_tokens,
            cache_read_input_tokens=u.cache_read_input_tokens,
            cache_creation_input_tokens=u.cache_creation_input_tokens,
        ),
        response_id=resp.id,
        response_model=resp.model,
    )

const u = resp.usage;
llm.record({
  usage: {
    inputTokens:
      u.input_tokens + u.cache_read_input_tokens + u.cache_creation_input_tokens,
    outputTokens: u.output_tokens,
    cacheReadInputTokens: u.cache_read_input_tokens,
    cacheCreationInputTokens: u.cache_creation_input_tokens,
  },
  responseId: resp.id,
  responseModel: resp.model,
});

Conversations タブでエージェントのトレースを確認する

Agent Lens で project を開き、Conversations を選択します。次の内容が表示されます。

research-bot の会話が 1 つあり、3 つのターンが含まれています。
各ターン (invoke_agent) の中に、2 つの chat スパンと 1 つの execute_tool スパンがネストされています。
各 chat には、トークン数、レイテンシー、モデル、メッセージのやり取り全体が表示されます。

会話を選択すると、Thread タブと Spans タブで入力、出力、ツールの引数、ツール結果を確認できます。

アプリから会話にリンクする

独自の UI から Agent Lens 内の会話にディープリンクするには、その会話の ID が必要です。start_conversation / startConversation はこの ID を conversation_id / conversationId として公開しています。この ID をログしたり、独自のリクエスト ID と一緒に保存したりしておけば、後で Conversations タブから該当の会話を開くことができます。

with tracing.start_conversation(agent_name="research-bot") as conversation:
    # ... ターンを実行 ...
    print(f"Agent Lens conversation ID: {conversation.conversation_id}")

await tracing.runIsolated(async () => {
  const conversation = tracing.startConversation({ agentName: 'research-bot' });
  try {
    // ... ターンを実行 ...
    console.log(`Agent Lens conversation ID: ${conversation.conversationId}`);
  } finally {
    conversation.end();
  }
});

次のステップ

Agent Lens でエージェントをトレースする方法と、Agent Lens SDK で利用できる機能やオプションについて確認してください。
Agent Lens をエージェントと統合するその他の方法については、エージェントインテグレーションを選択するを参照してください。

​学習内容

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

​前提条件

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

​Agent Lens を初期化する

​ツールを定義する

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

​トークン使用量とコストを記録する

​Conversations タブでエージェントのトレースを確認する

​アプリから会話にリンクする

​次のステップ