Weave SDK で エージェント をインストルメントすると、各 スパン オブジェクト (Turn、LLM、Tool、SubAgent) でカスタム メタデータを追加するメソッドを使用できます。これらのメソッドを使用して、ユーザー ID、テナント、experiment 名、環境ラベルなどのコンテキスト情報を エージェント スパン に付与し、そのメタデータに基づいて Weave UI で エージェント のアクティビティをフィルタリングしたりグループ化したりできます。
このメタデータには 2 つの形式があります。
- 属性: スパン 全体に付くキーと値のプロパティです。
set_attributes() (Python) または setAttributes() (TypeScript) を使用して単一の スパン に属性を付与することも、セッション が出力するすべての スパン に適用される セッション 全体の属性を設定することもできます。
- イベント: スパン の存続期間中に発生する時点のマーカーです。たとえば、権限プロンプトやライフサイクル遷移などがあります。
add_event() (Python) または addEvent() (TypeScript) を使用します。
これらのメソッドは、OpenTelemetry (OTel) span API に対応しています。set_attributes は OTel の Span.set_attributes に対応し、add_event は OTel の Span.add_event に対応します。Weave SDK は OTel スパン を出力し、すべての属性を保存するため、それらは Weave で引き続きクエリ可能です。
単一の スパン に任意の属性を付与するには、set_attributes() (Python) または setAttributes() (TypeScript) を使用します。キーが 1 つでも複数でも、辞書またはオブジェクトを渡します。このメソッドは スパン を返すため、呼び出しをチェーンできます。
import weave
weave.init("[TEAM-NAME]/[PROJECT-NAME]")
with weave.start_session(agent_name="my-agent"):
with weave.start_turn(user_message="What is the weather in Tokyo?") as turn:
# この turn span に属性を付与します
turn.set_attributes({"user_id": "12345", "tenant": "acme", "env": "production"})
import * as weave from 'weave';
await weave.init('[TEAM-NAME]/[PROJECT-NAME]');
const session = weave.startSession({ agentName: 'my-agent' });
const turn = weave.startTurn({ agentName: 'my-agent' });
// この turn span に属性を付与します
turn.setAttributes({ user_id: '12345', tenant: 'acme', env: 'production' });
turn.end();
session.end();
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.* 配下のキーは Weave の組み込みフィールドにマップされ、gen_ai.* 配下のキーは OpenTelemetry GenAI のセマンティック規約フィールドにマップされます。前述の例では、weave.display_name は予約済みキーであり、Agents および Traces UI で スパン の表示名を設定します。フィルターやグループ化に使用したい任意のメタデータには、user_id や tenant などの独自キーを使用してください。Weave はそれらをフィルタリング可能なカスタム属性として保存します。
スパン ごとに 1 つずつ属性を付与する方法は、スパン 固有のメタデータには適していますが、メタデータの中にはセッション全体に適用されるものもあります。セッションから生成されるすべての スパン に同じ属性を適用するには、セッションの開始時に attributes を渡します。これは、インテグレーションのアイデンティティやデプロイ環境など、セッション全体にわたるメタデータを伝播する場合に便利です。
import weave
weave.init("[TEAM-NAME]/[PROJECT-NAME]")
session = weave.start_session(
agent_name="my-agent",
attributes={"weave.integration.name": "my-harness", "env": "production"},
)
# このセッション内のすべての turn、LLM、tool、sub-agent の span に、これらの属性が付与されます。
import * as weave from 'weave';
await weave.init('[TEAM-NAME]/[PROJECT-NAME]');
const session = weave.startSession({
agentName: 'my-agent',
attributes: { 'weave.integration.name': 'my-harness', env: 'production' },
});
// このセッション内のすべての turn、LLM、tool、sub-agent の span に、これらの属性が付与されます。
スパン ごとの属性と同様に、セッション属性には独自のカスタムキーを使用してください。agent 名、session 名、model などのセマンティック規約フィールドは、attributes ではなく、対応する型付きパラメーター (agent_name、session_name、model) で設定してください。予約済みの gen_ai.* および weave.* 接頭辞配下のキーは避けてください。Weave は取り込み時にそれらを型付きフィールドとして抽出するため、予約済みキー配下のカスタム値はサポートされません。
add_event() (Python) または addEvent() (TypeScript) を使用すると、スパンの存続期間中の特定の時点にマーカーを記録できます。スパン全体を表す attribute とは異なり、イベントは、権限 prompt、コンテキスト圧縮のステップ、spawned、streaming、finished などの lifecycle 遷移のように、スパンの途中のある時点で発生した出来事を記録します。
各イベントには、名前と省略可能な 属性 の dictionary または object を指定します。
with weave.start_turn(user_message="Delete the temp files") as turn:
# エージェントが権限を要求したときにマーカーを記録する
turn.add_event("weave.permission_request", {"tool": "shell", "command": "rm -rf ./tmp"})
# ... エージェントは処理を継続 ...
turn.add_event("finished")
const turn = weave.startTurn({ agentName: 'my-agent' });
// エージェントがコンテキストを圧縮したときにマーカーを記録する
turn.addEvent('context_compacted', { removedMessages: 12 });
turn.end();
events 配列を展開します。
属性とイベントは、スパン の記録中、つまり スパン の開始後から終了前までの間に設定してください。Python では with ブロック内、TypeScript では start*() の後から end() の前までです。
まだ開始していない、またはすでに終了した スパン に対して set_attributes()、add_event()、またはそれらに対応する TypeScript の関数を呼び出すと、その呼び出しは no-op となり、対処方法を示す警告がログされます。
呼び出しが何も出力しない (警告も出ない) のは、OTel がインストールされていない場合、または Weave が無効になっている場合だけです。
ライブ実行中ではなく、完了済みのエージェントアクティビティを 1 つのバッチとしてログする際に属性を付加するには、スパン オブジェクトで宣言されたフィールドに直接値を設定し、そのオブジェクトを log_turn または log_session に渡してください。詳しくは、Log agent activity in batchesを参照してください。 
