エージェントスパンに属性とイベントを設定する

Weave SDK でエージェントをインストルメントすると、各スパンオブジェクト (Turn、LLM、Tool、SubAgent) でカスタムメタデータを付与するためのメソッドを使用できます。これらのメソッドを使用すると、ユーザー ID、テナント、実験名、環境ラベルなどのコンテキスト情報をエージェントスパンに記録し、Weights & Biases UI でそのメタデータを基にエージェントのアクティビティをフィルタリングおよびグループ化できます。このメタデータには次の 2 つの形式があります。

属性: スパン全体に関するキーと値のプロパティです。set_attributes() (Python) または setAttributes() (TypeScript) を使用して単一のスパンに属性を記録できます。また、会話が出力するすべてのスパンに適用される、会話全体の属性を設定することもできます。
イベント: スパンの有効期間中の特定の時点で発生する事象を示すマーカーです (許可プロンプトやライフサイクルの遷移など) 。add_event() (Python) または addEvent() (TypeScript) を使用します。

これらのメソッドは OpenTelemetry (OTel) スパン API に倣って設計されています。set_attributes は OTel の Span.set_attributes に、add_event は OTel の Span.add_event に対応します。Weave SDK は OTel スパンを出力し、すべての属性を保存するため、属性は Weave でクエリできます。

スパンに属性を設定する

set_attributes() (Python) または setAttributes() (TypeScript) を使用すると、単一のスパンに任意の属性を付与できます。キーが 1 つでも複数でも、辞書またはオブジェクトとして渡します。このメソッドはスパンを返すため、Call をチェーンできます。

Python
TypeScript

import weave

weave.init("[TEAM-NAME]/[PROJECT-NAME]")

with weave.start_conversation(agent_name="my-agent"):
    with weave.start_turn(user_message="What is the weather in Tokyo?") as turn:
        # このターンスパンに属性を付与する
        turn.set_attributes({"user_id": "12345", "tenant": "acme", "env": "production"})

import * as weave from 'weave';

await weave.init('[TEAM-NAME]/[PROJECT-NAME]');

const conversation = weave.startConversation({ agentName: 'my-agent' });
const turn = weave.startTurn({ agentName: 'my-agent' });

// このターンスパンに属性を付与する
turn.setAttributes({ user_id: '12345', tenant: 'acme', env: 'production' });

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

同じメソッドはすべてのスパンクラスで使用できます。たとえば、個々のツール呼び出しや LLM Call にタグを付けられます。

Python
TypeScript

with weave.start_turn(user_message="What is the weather in Tokyo?") as turn:
    with turn.tool(name="get_weather") as tool:
        tool.set_attributes({"weave.display_name": "Weather lookup"})

const turn = weave.startTurn({ agentName: 'my-agent' });
const tool = turn.startTool({ name: 'get_weather' });

tool.setAttributes({ 'weave.display_name': 'Weather lookup' });

tool.end();
turn.end();

ほとんどの属性キーは任意のカスタムメタデータとして扱われますが、Weave は 2 つの接頭辞を特別な処理用に予約しています。weave.* 配下のキーは Weave の組み込みフィールドに、gen_ai.* 配下のキーは OpenTelemetry GenAI セマンティック規約のフィールドにマッピングされます。上記の例の weave.display_name は予約済みキーで、Agents UI および Traces UI に表示されるスパンの表示名を設定します。フィルターやグループ化に使用する任意のメタデータには、user_id や tenant などの独自のキーを使用してください。これらのキーは、Weave によってフィルター可能なカスタム属性として保存されます。

会話内のすべてのスパンに属性を設定する

スパンごとに属性を付与する方法は、スパン固有のメタデータには適していますが、会話全体に適用されるメタデータもあります。会話が生成するすべてのスパンに同じ属性を適用するには、会話を開始するときに attributes を渡します。これは、インテグレーションのアイデンティティやデプロイメント環境など、会話全体のメタデータを伝播させる際に役立ちます。

Python
TypeScript

import weave

weave.init("[TEAM-NAME]/[PROJECT-NAME]")

conversation = weave.start_conversation(
    agent_name="my-agent",
    attributes={"weave.integration.name": "my-harness", "env": "production"},
)
# このセッション内のすべてのターン、LLM、ツール、サブエージェントのスパンに、これらの属性が付与されます。

import * as weave from 'weave';

await weave.init('[TEAM-NAME]/[PROJECT-NAME]');

const conversation = weave.startConversation({
  agentName: 'my-agent',
  attributes: { 'weave.integration.name': 'my-harness', env: 'production' },
});
// この会話内のすべてのターン、LLM、ツール、サブエージェントのスパンに、これらの属性が付与されます。

スパンごとの属性と同様に、会話の属性には独自のカスタムキーを使用してください。エージェント名、会話名、モデルなどのセマンティック規約のフィールドは、attributes ではなく、型付きパラメーター (agent_name、conversation_name、model) を通じて設定してください。予約済みの接頭辞 gen_ai.* と weave.* に属するキーは避けてください。Weave は取り込み時にこれらを型付きフィールドに抽出するため、予約済みキーにカスタム値を設定することはサポートされません。

属性を設定できるタイミング

属性は、スパンの記録中、つまりスパンが開始してから終了するまでの間に設定してください。Python では with ブロックの内側、TypeScript では start*() の後から end() の前までが該当します。まだ開始していない、またはすでに終了したスパンに対して set_attributes() (または TypeScript での同等のメソッド) を呼び出した場合、その呼び出しは no-op となり、修正方法を示す警告がログされます。警告なしで何も起こらないのは、OTel がインストールされていない場合、または Weave が無効になっている場合のみです。

実行中ではなく、完了したエージェントのアクティビティを 1 つのバッチでまとめてログする際に属性を付与するには、スパンオブジェクトの宣言済みフィールドに直接値を設定し、そのオブジェクトを log_turn または log_conversation に渡します。詳しくはエージェントのアクティビティをバッチでログするを参照してください。

UI で属性を表示してフィルターする

属性の追加は最初のステップにすぎません。属性は、エージェントのアクティビティの分析に活用してこそ価値を発揮します。エージェントスパンに属性を付与すると、Weave プロジェクトの Agents タブで、それらの属性を使ってエージェントの会話をフィルターしたりグループ化したりできます。詳細については、エージェントのアクティビティを表示するを参照してください。

​スパンに属性を設定する

​会話内のすべてのスパンに属性を設定する

​属性を設定できるタイミング

​UI で属性を表示してフィルターする

スパンに属性を設定する

会話内のすべてのスパンに属性を設定する

属性を設定できるタイミング

UI で属性を表示してフィルターする