> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coreweave.com/llms.txt
> Use this file to discover all available pages before exploring further.

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

> エージェント スパン（Turn、LLM、Tool、SubAgent）にカスタム属性を付与してイベントを記録し、Weave でエージェントのアクティビティをフィルタリング・分析します。

export const AgentLensBanner = ({href}) => <Tip>
    <strong>This workflow is also available in CoreWeave Agent Lens.</strong> Agent Lens is the Forge experience built for tracing, monitoring, and analyzing AI agents, with automated insights into agent failures and user intents. It uses the same trace data as Weights & Biases Weave, so the traces you already send appear there with nothing to migrate.{' '}
    <a href={href || '/products/agent-lens'}>{href ? 'See how to do this in Agent Lens' : 'Learn about Agent Lens'}</a>.
  </Tip>;

<AgentLensBanner href="/ja/products/agent-lens/tracing/attributes-and-events" />

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

このメタデータには次の 2 つの形式があります。

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

これらのメソッドは [OpenTelemetry (OTel) スパン API](https://opentelemetry.io/docs/specs/semconv/gen-ai/gen-ai-spans/) に倣って設計されています。`set_attributes` は OTel の `Span.set_attributes` に、`add_event` は OTel の `Span.add_event` に対応します。Weave SDK は OTel スパンを出力し、すべての属性を保存するため、属性は Weave でクエリできます。

<h2 id="set-attributes-on-a-span">
  スパンに属性を設定する
</h2>

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

<Tabs>
  <Tab title="Python">
    ```python lines theme={"system"}
    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"})
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript lines twoslash theme={"system"}
    // @noErrors
    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();
    ```
  </Tab>
</Tabs>

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

<Tabs>
  <Tab title="Python">
    ```python lines theme={"system"}
    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"})
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript lines twoslash theme={"system"}
    // @noErrors
    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();
    ```
  </Tab>
</Tabs>

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

<h2 id="set-attributes-on-every-span-in-a-conversation">
  会話内のすべてのスパンに属性を設定する
</h2>

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

<Tabs>
  <Tab title="Python">
    ```python lines theme={"system"}
    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、ツール、サブエージェントのスパンに、これらの属性が付与されます。
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript lines twoslash theme={"system"}
    // @noErrors
    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、ツール、サブエージェントのスパンに、これらの属性が付与されます。
    ```
  </Tab>
</Tabs>

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

<h2 id="when-you-can-set-attributes">
  属性を設定できるタイミング
</h2>

属性は、スパンの記録中、つまりスパンが開始してから終了するまでの間に設定してください。Python では `with` ブロックの内側、TypeScript では `start*()` の後から `end()` の前までが該当します。

まだ開始していない、またはすでに終了したスパンに対して `set_attributes()` (または TypeScript での同等のメソッド) を呼び出した場合、その呼び出しは no-op となり、修正方法を示す警告がログされます。

警告なしで何も起こらないのは、OTel がインストールされていない場合、または Weave が無効になっている場合のみです。

<Tip>
  実行中ではなく、完了したエージェントのアクティビティを 1 つのバッチでまとめてログする際に属性を付与するには、スパンオブジェクトの宣言済みフィールドに直接値を設定し、そのオブジェクトを `log_turn` または `log_conversation` に渡します。詳しくは [エージェントのアクティビティをバッチでログする](/ja/products/wandb/weave/guides/tracking/trace-agents-batch) を参照してください。
</Tip>

<h2 id="view-and-filter-attributes-in-the-ui">
  UI で属性を表示してフィルターする
</h2>

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