エージェントをトレースする

CoreWeave Forge SDK を使用してマルチターンのエージェント型アプリケーションをインストルメントし、エージェントの動作を確認、デバッグ、評価する方法について説明します。このガイドは、エージェントを構築または統合する開発者のうち、会話、ターン、LLM Call、ツール実行を構造的に可視化したい方を対象としています。 Agent Lens SDK は、マルチターンのエージェントの会話におけるライフサイクル全体をモデル化します。対象となるのは、複数の会話を持つエージェント、ターンをまとめる会話、ユーザーとエージェント間の個々のやり取り (ターン)、ターン内の LLM Call、そして LLM によってトリガーされるツール実行です。トレースは、CoreWeave Agent Lens の project の Conversations タブに表示されます。各会話には、ネストされたツール呼び出し、トークン使用量、フィードバックを含むマルチターンのタイムラインが表示されます。 Agent Lens は、分散トレースのオープン標準である OpenTelemetry (OTel) を基盤としています。ターン、LLM Call、ツール呼び出しはそれぞれ OTel の スパン (1 つの操作を表す構造化レコード) を出力します。各スパンには、gen_ai.agent.name や gen_ai.conversation.id などの GenAI セマンティック規約に基づく属性がタグ付けされます。

始める前に

まず、Agent Lens SDK をインストールし、project を初期化します。このステップで entity と project が Agent Lens に登録され、SDK がスパンを UI 上の正しい場所に送信できるようになります。SDK は WANDB_API_KEY 環境変数から APIキーを読み取ります。

Python
TypeScript

pip install coreweave

[YOUR-TEAM] を Forge の entity 名に、[YOUR-PROJECT] をプロジェクト名に置き換えます。entity は必須です。

from coreweave.forge.agentlens import tracing

tracing.init("[YOUR-TEAM]/[YOUR-PROJECT]")

start_conversation()、start_turn()、start_llm()、start_tool()、start_subagent() のいずれかを呼び出す前に、tracing.init() を呼び出してください。init() の実行前や shutdown() の実行後は、トレース関数はエラーを出さずに no-op となります。そのため、インストルメンテーションを本番コードに残したまま、設定で有効・無効を制御できます。プロセスの終了時に tracing.shutdown() を呼び出して、バッファに残っているスパンをフラッシュしてください。この関数は atexit にも登録されています。

npm install @coreweave/forge-sdk

[YOUR-TEAM] を Forge の entity 名に、[YOUR-PROJECT] をプロジェクト名に置き換えます。entity は必須です。

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

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

startConversation()、startTurn()、startLLM()、startTool()、startSubagent() のいずれかを呼び出す前に、tracing.init() を一度だけ呼び出してください。また TypeScript では、各リクエストやエージェントの run を tracing.runIsolated() でラップする必要があります。これにより、その実行のトレース状態が await をまたいで保持され、並行するリクエスト同士で会話が共有されるのを防げます。tracing.runIsolated() の外でスパンを開始すると、エラーがスローされます。プロセスの終了時に tracing.shutdown() を呼び出して、バッファに残っているスパンをフラッシュしてください。

エージェントのデータモデル

Agent Lens は、エージェントの動作を一対多の関係による階層としてモデル化します。1 つのエージェントは複数の会話を持つことができ、1 つの会話は複数のターンを、1 つのターンは複数の LLM Call を持つことができます。さらに、1 つの LLM Call から複数のツール呼び出しをトリガーできます。

概念	Agent Lens SDK クラス	OTel スパンタイプ	説明	リファレンスページ
エージェント	(クラスなし)	(スパンなし。`agent_name` 属性でグループ化)	1 つ以上の会話を含むエージェント型アプリケーション。
会話	`Conversation`	(スパンなし。ターンは `conversation_id` 属性でグループ化)	1 つ以上のターンを含む会話または run。	Python TypeScript
ターン	`Turn`	`invoke_agent`	1 つのユーザーメッセージと、それに対するエージェントの応答全体。	Python TypeScript
LLM Call	`LLM`	`chat`	言語モデル API への 1 回の呼び出し。	Python TypeScript
ツール呼び出し	`Tool`	`execute_tool`	LLM の応答によってトリガーされる 1 回のツール呼び出し。	Python TypeScript
サブエージェントの呼び出し	`SubAgent`	`invoke_agent`	ネストされたエージェントの invocation。通常、あるエージェントが別のエージェントに処理を委譲する場合に発生します。	Python TypeScript

次の図は、1 つのエージェントが複数の会話を持ち、1 つの会話が複数のターンを持つ、といった階層関係を示しています。会話は、親スパンではなく共通の conversation_id 属性によってターンをグループ化します。そのため、各ターンはそれぞれ独自の OTel トレースを開始します。この設計により、分散トレースと並列実行がサポートされます。クライアントはサーバー側で集約することなく、スパンを OTel コレクターに直接送信します。

Claude Agent SDK や Codex などのエージェント SDK またはハーネスと Agent Lens を統合するには、エージェントインテグレーションを選択するを参照してください。これらのインテグレーションは SDK またはハーネスのセッションから conversation_id を設定するため、ターンをグループ化するために start_conversation() を使用する必要はありません。一方、LLM プロバイダ SDK のインテグレーション (OpenAI、Anthropic、Google Gen AI) は会話を作成しません。Agent Lens には会話内で実行された Call のみが表示されるため、このページの API を使用して、これらの Call を囲む会話とターンを開始してください。

エージェントトレース API

以下のセクションでは、各トップレベルのトレース関数と、その関数が受け入れる引数について説明します。これらの関数を使用して、前のセクションで説明したデータモデルの会話、ターン、LLM Call、ツール呼び出しの各レイヤーをインストルメントします。 Agent Lens は、以下のトップレベル関数を提供します。各関数が返すオブジェクトは、コンテキストマネージャーとして使用する (Python では with、TypeScript では try/finally を使用) か、.end() を呼び出して手動で終了することができます。

会話を開始する

start_conversation() (Python) または startConversation() (TypeScript) は、すべての子スパンに conversation_id 属性を付与し、ターンが Conversations タブでグループ化されるようにします。conversation_id / conversationId を指定する場合は、会話の有効期間を通じて同じ値を使用する必要があります。既存の会話に新しいターンを追加するには、同じ ID を再利用してください。省略した場合は、SDK が UUID を自動的に生成します。実行中の会話はコンテキスト (Python の ContextVar または Node.js の AsyncLocalStorage) に保存されます。そのため、同じ非同期コンテキスト内で実行されるコードであれば、会話オブジェクトを明示的に渡さなくても tracing.get_current_conversation() / tracing.getCurrentConversation() で取得できます。

Python
TypeScript

conversation = tracing.start_conversation(
    agent_name="my-agent",    # オプション: UI でエージェントを識別します。省略すると、会話は名前付きエージェントの下にグループ化されません。
    conversation_id="",       # オプション: ターンをグループ化するための固定の ID。空の場合は自動生成されます。
    model="",                 # オプション: この会話のターンで使用するデフォルトのモデル。
    conversation_name="",     # オプション: UI に表示される、わかりやすいラベル。
    include_content=True,     # オプション: False に設定すると、スパンからメッセージ本文を除外します。
    continue_parent_trace=False,  # オプション: 新しいトレースを開始せず、既存の OTel トレースに紐付けます。
)

const conversation = tracing.startConversation({
  agentName: 'my-agent',  // オプション: UI でエージェントを識別します。省略すると、会話は名前付きエージェントの下にグループ化されません。
  conversationId: '',     // オプション: ターンをグループ化するための固定の ID。空の場合は自動生成されます。
  model: '',              // オプション: この会話のターンで使用するデフォルトのモデル。
});

ターンを開始する

start_turn() (Python) および startTurn() (TypeScript) は、新しい OTel トレースのルートとなる invoke_agent スパンを作成します。Agent Lens は、タイムラインビューでユーザーとエージェント間の 1 回のやり取り全体をこのスパンで表します。

Python
TypeScript

turn = tracing.start_turn(
    user_message="What is the weather in Tokyo?",  # ユーザーの入力テキスト。
    agent_name="my-agent",   # オプション: 会話レベルのエージェント名を上書きします。
    model="gpt-4o",          # オプション: このターンで使用するモデル。
)

const turn = tracing.startTurn({
  userMessage: 'What is the weather in Tokyo?',  // ユーザーの入力テキスト。
  agentName: 'my-agent',  // オプション: 会話レベルのエージェント名を上書きします。
  model: 'gpt-4o',        // オプション: このターンで使用するモデル。
});

呼び出し方法は 2 通りあります。

トップレベル関数として呼び出す (tracing.start_turn(...) / tracing.startTurn(...)) : 以下のサンプルではこの形式を使用しています。コンテキストから実行中の会話を解決し、その会話 ID を引き継ぎます。実行中の会話がない場合、ターンは conversation_id なしで作成され、他のターンとはグループ化されません。
インスタンスメソッドとして呼び出す (conversation.start_turn(...) / conversation.startTurn(...) ) : 参照を保持している会話に対して呼び出します。コンテキストマネージャーのブロック内など、会話オブジェクトが明示的にスコープ内にある場合に便利です。このガイドの後半で紹介する「コンテキストマネージャーまたは try-finally パターン」のサンプルでは、この形式を使用しています。両 SDK の Conversation、Turn、LLM、Tool、SubAgent のリファレンスページへの直接リンクについては、前述のデータモデルの表を参照してください。

LLM Call を開始する

start_llm() / startLLM() は、現在のターンの下にネストされた chat スパンを作成します。Agent Lens はこのスパンを使用して、トークン使用量、モデル名、入力メッセージと出力メッセージ、推論を UI に表示します。

Python
TypeScript

llm = tracing.start_llm(
    model="gpt-4o",             # モデル識別子。
    provider_name="openai",     # オプション: プロバイダー名（例: "openai"、"anthropic"）。下記の注記を参照してください。
    system_instructions=["Be concise."],  # オプション: システムプロンプトの strings。
)

const llm = tracing.startLLM({
  model: 'gpt-4o',          // モデル識別子。
  providerName: 'openai',   // オプション: プロバイダー名（例: "openai"、"anthropic"）。下記の注記を参照してください。
});

LLM Call が完了したら、llm オブジェクトが閉じる前に応答データを割り当てます。

Python
TypeScript

with tracing.start_llm(model="gpt-4o", provider_name="openai") as llm:
    response = openai_client.chat.completions.create(...)
    llm.input_messages = [Message(role="user", content="...")]
    llm.output_messages = [Message(role="assistant", content=response.choices[0].message.content)]
    llm.usage = Usage(
        input_tokens=response.usage.prompt_tokens,
        output_tokens=response.usage.completion_tokens,
    )

const llm = tracing.startLLM({ model: 'gpt-4o', providerName: 'openai' });
try {
  const response = await openaiClient.chat.completions.create({ ... });
  llm.record({
    inputMessages: [{ role: 'user', content: '...' }],
    outputMessages: [{ role: 'assistant', content: response.choices[0].message.content ?? '' }],
    usage: {
      inputTokens: response.usage?.prompt_tokens,
      outputTokens: response.usage?.completion_tokens,
    },
  });
} finally {
  llm.end();
}

llm.record() は、inputMessages、outputMessages、usage、reasoning を 1 回の呼び出しでまとめて割り当てるためのショートカットです。必要に応じて、各プロパティを個別に設定することもできます。Python SDK にも同じメソッドが llm.record(...) として用意されており、snake_case のキーワード引数で指定します。

provider_name / providerName は明示的に指定してください。Agent Lens はモデル文字列からプロバイダーを推測しません。

ツール呼び出しを開始する

start_tool() / startTool() は execute_tool スパンを作成します。このスパンは、コンテキスト内でアクティブな OTel スパン (通常は、そのツール呼び出しを生成した LLM Call の chat スパン) の子になります。

Python
TypeScript

tool = tracing.start_tool(
    name="get_weather",                  # LLM に宣言したツール名。
    arguments='{"city": "Tokyo"}',       # ツール引数の JSON 文字列。
    tool_call_id="call_abc123",          # オプション: LLM の応答に含まれるツール呼び出し ID。
)

const tool = tracing.startTool({
  name: 'get_weather',            // LLM に宣言したツール名。
  args: '{"city": "Tokyo"}',      // オプション: ツール引数の JSON 文字列。
  toolCallId: 'call_abc123',      // オプション: LLM の応答に含まれるツール呼び出し ID。
});

スパンを閉じる前にツール結果を設定します。

Python
TypeScript

with tracing.start_tool(name="get_weather", arguments='{"city": "Tokyo"}') as tool:
    result = get_weather_api("Tokyo")
    tool.result = result  # dict、list、または string を受け入れます。自動的に JSON エンコードされます。

const tool = tracing.startTool({ name: 'get_weather', args: '{"city": "Tokyo"}' });
try {
  tool.result = await getWeatherApi('Tokyo');
} finally {
  tool.end();
}

エージェントトレースの使用パターン

以下のセクションでは、エージェントのコード構成に応じてこれらの関数を組み合わせる方法について説明します。以下のサンプルでは、Agent Lens SDK の 2 つのタイプを使用します。

Message (Python · TypeScript) は、会話内の 1 つのエントリ (ユーザー入力、アシスタントの応答、システムプロンプト、ツール結果のいずれか) を表します。メッセージのリストを llm.input_messages / llm.inputMessages に割り当てるとモデルが受け取った内容が記録され、llm.output_messages / llm.outputMessages に割り当てるとモデルが生成した内容が記録されます。
Usage (Python · TypeScript) は、LLM の応答からトークン数を取得するもので、llm.usage に割り当てます。

Agent Lens はこの 2 つを使用して、各 LLM Call の入力、出力、トークン使用量を UI に表示します。

コンテキストマネージャーまたは try-finally パターン

ほとんどのエージェントでは、Python ではコンテキストマネージャーパターンを、TypeScript では try-finally パターンを使用してください。例外が発生した場合でも、スパンはブロックの終了時に閉じられ、送信されます。 Agent Lens は実行中の会話、ターン、LLM Call をコンテキストに保持します。そのため、ブロック内で呼び出される関数は、親への参照を明示的に保持していなくても start_llm() / startLLM() や start_tool() / startTool() を呼び出せます。コードが同じ非同期コンテキスト内で実行される限り、モジュールの境界をまたいでも機能します。コールスタックの任意の場所から実行中のオブジェクトを取得するには、tracing.get_current_conversation() / tracing.getCurrentConversation()、tracing.get_current_turn() / tracing.getCurrentTurn()、tracing.get_current_llm() / tracing.getCurrentLLM() を使用します。

Python
TypeScript

from coreweave.forge.agentlens import tracing
from coreweave.forge.agentlens.tracing import Message, Usage

# プレースホルダー関数: 独自の実装に置き換えてください。
def call_openai(*args, **kwargs):
    pass  # 使用する LLM クライアントの呼び出しに置き換えてください。

def get_weather_api(city: str) -> str:
    return "24°C, sunny"  # 使用する天気 API の呼び出しに置き換えてください。

tracing.init("[YOUR-TEAM]/[YOUR-PROJECT]")

with tracing.start_conversation(agent_name="weather-bot") as conversation:
    with conversation.start_turn(user_message="What is the weather in Tokyo?") as turn:

        # 1 回目の LLM Call: ツール呼び出しを返します。
        with tracing.start_llm(model="gpt-4o", provider_name="openai") as llm:
            response = call_openai(...)
            llm.input_messages = [Message(role="user", content="What is the weather?")]
            llm.think("User wants weather data, I should call get_weather.")
            llm.output("Let me check the weather for you.")
            llm.usage = Usage(input_tokens=100, output_tokens=20)

            # ツール呼び出し: 呼び出し元の LLM Call の子になります。
            with tracing.start_tool(name="get_weather", arguments='{"city":"Tokyo"}') as tool:
                tool.result = get_weather_api("Tokyo")  # "24°C, sunny" を返します。

        # 2 回目の LLM Call: 最終的な回答を生成します。
        with tracing.start_llm(model="gpt-4o", provider_name="openai") as llm:
            llm.input_messages = [Message(role="user", content="What is the weather?")]
            llm.output("It is 24°C and sunny in Tokyo today.")
            llm.usage = Usage(input_tokens=150, output_tokens=30)

tracing.shutdown()

エージェントの run を tracing.runIsolated() でラップします。これにより、会話、ターン、LLM のコンテキストが await をまたいでも維持され、同時実行中の他の run からも分離されます。

import { tracing } from '@coreweave/forge-sdk/agentlens';
import type { Message, Usage } from '@coreweave/forge-sdk/agentlens/tracing';

// プレースホルダー関数: 独自の実装に置き換えてください。
async function getWeatherApi(city: string): Promise<string> {
  return '24°C, sunny';  // 使用する天気 API の呼び出しに置き換えてください。
}

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

await tracing.runIsolated(async () => {
  const conversation = tracing.startConversation({ agentName: 'weather-bot' });
  try {
    const turn = conversation.startTurn({ userMessage: 'What is the weather in Tokyo?' });
    try {
      // 1 回目の LLM Call: ツール呼び出しを返します。
      const llm = tracing.startLLM({ model: 'gpt-4o', providerName: 'openai' });
      try {
        llm.inputMessages = [{ role: 'user', content: 'What is the weather?' }];
        llm.think('User wants weather data, I should call get_weather.');
        llm.output('Let me check the weather for you.');
        llm.usage = { inputTokens: 100, outputTokens: 20 };

        // ツール呼び出し: 呼び出し元の LLM Call の子になります。
        const tool = tracing.startTool({ name: 'get_weather', args: '{"city":"Tokyo"}' });
        try {
          tool.result = await getWeatherApi('Tokyo');  // "24°C, sunny" を返します。
        } finally {
          tool.end();
        }
      } finally {
        llm.end();
      }

      // 2 回目の LLM Call: 最終的な回答を生成します。
      const llm2 = tracing.startLLM({ model: 'gpt-4o', providerName: 'openai' });
      try {
        llm2.inputMessages = [{ role: 'user', content: 'What is the weather?' }];
        llm2.output('It is 24°C and sunny in Tokyo today.');
        llm2.usage = { inputTokens: 150, outputTokens: 30 };
      } finally {
        llm2.end();
      }
    } finally {
      turn.end();
    }
  } finally {
    conversation.end();
  }
});

await tracing.shutdown();

手動で開始と終了を行うパターン

with ブロックや try/finally を使用できない場合は、.end() を明示的に呼び出します。たとえば、スパンの開始と終了を別々の関数の Call で行う場合や、コルーチンの外部で非同期のライフサイクルを管理する場合が該当します。スパンを閉じてコレクターにフラッシュするために、作成したすべてのオブジェクトで必ず .end() を呼び出してください。TypeScript では、ターンまたは会話を終了すると、その配下でまだ開いている子孫もすべて閉じられます。

Python
TypeScript

conversation = tracing.start_conversation(agent_name="weather-bot")
turn = conversation.start_turn(user_message="What is the weather?")

llm = tracing.start_llm(model="gpt-4o", provider_name="openai")
llm.input_messages = [Message(role="user", content="What is the weather?")]
llm.output("Let me check.")
llm.usage = Usage(input_tokens=100, output_tokens=20)

tool = tracing.start_tool(name="get_weather", arguments='{"city": "Tokyo"}')
tool.result = "24°C, sunny"
tool.end()   # end() はべき等なので、複数回呼び出しても問題ありません。

llm.end()

llm2 = tracing.start_llm(model="gpt-4o", provider_name="openai")
llm2.output("It is 24°C and sunny in Tokyo.")
llm2.usage = Usage(input_tokens=150, output_tokens=30)
llm2.end()

turn.end()
conversation.end()

await tracing.runIsolated(async () => {
  const conversation = tracing.startConversation({ agentName: 'weather-bot' });
  const turn = conversation.startTurn({ userMessage: 'What is the weather?' });

  const llm = tracing.startLLM({ model: 'gpt-4o', providerName: 'openai' });
  llm.inputMessages = [{ role: 'user', content: 'What is the weather?' }];
  llm.output('Let me check.');
  llm.usage = { inputTokens: 100, outputTokens: 20 };

  const tool = tracing.startTool({ name: 'get_weather', args: '{"city": "Tokyo"}' });
  tool.result = '24°C, sunny';
  tool.end();  // end() はべき等なので、複数回呼び出しても問題ありません。

  llm.end();

  const llm2 = tracing.startLLM({ model: 'gpt-4o', providerName: 'openai' });
  llm2.output('It is 24°C and sunny in Tokyo.');
  llm2.usage = { inputTokens: 150, outputTokens: 30 };
  llm2.end();

  turn.end();
  conversation.end();
});

セマンティック規約

Agent Lens SDK は、GenAI セマンティック規約および GenAI エージェントスパン規約に準拠した OTel スパンを出力します。Agent Lens はあらゆる OTel スパンを受け入れ、すべての属性を保存してクエリできるようにします。任意の Agent Lens トレースオブジェクトで set_attributes() / setAttributes() を使用すると、スパンに任意の属性を追加できます。詳しくは、エージェントスパンに属性を設定するを参照してください。 SDK は専用のプライベートな OpenTelemetry トレーサープロバイダーを持っています。このプロバイダーは Agent Lens を通じて作成されたスパンのみをエクスポートします。アプリケーションのグローバルプロバイダーを置き換えることはなく、無関係なインストルメンテーションのスパンをエクスポートすることもありません。

Agent Lens UI でのデータの表示

前述のパターンでエージェントをインストルメントして実行すると、トレースが Agent Lens project の Conversations タブ (https://) に表示されます。

Conversations タブには、すべての会話が、ターンのアクティビティを示すミニマップとともに表示されます。
会話の詳細ビューは、会話をクリックすると開きます。このビューには、その会話のすべてのターン、LLM Call、ツール実行、トークン数、および関連付けられたフィードバックが表示されます。

Agent Lens で取得したデータの表示方法について詳しくは、エージェントのアクティビティを表示するを参照してください。

​始める前に

​エージェントのデータモデル

​エージェントトレース API

​会話を開始する

​ターンを開始する

​LLM Call を開始する

​ツール呼び出しを開始する

​エージェントトレースの使用パターン

​コンテキストマネージャーまたは try-finally パターン

​手動で開始と終了を行うパターン

​セマンティック規約

​Agent Lens UI でのデータの表示