View a markdown version of this page

Strands Agents - Amazon Bedrock AgentCore
エージェントを計測するスパンの識別方法評価フィールドの抽出方法イベントレコードを含むスパンの例イベントレコードのないスパンの例

Strands Agents

このページでは、ストランドエージェントエージェントの計測方法、スパンの識別方法、評価フィールドの抽出方法について説明します。

トピック

エージェントを計測する

Strands Agents SDK にはテレメトリが組み込まれており、追加の計測ライブラリは必要ありません。スコープ名 でスパンとイベントレコードを生成しますstrands.telemetry.tracer。Distro for OpenTelemetry (ADOT) AWS を使用して Amazon Bedrock AgentCore ランタイムにデプロイすると、ランタイムは session.id 属性を挿入し、スパンとイベントレコードを自動的にエクスポートします。

注記

計測は、オブザーバビリティを設定する 1 つのステップです。評価のためにテレメトリをエクスポートするには、「オブザーバビリティの設定」で完全なセットアップを完了します。

スパンの識別方法

ストランドは、各スパンに gen_ai.operation.name 属性を設定します。評価サービスは、この属性を使用してスパンを分類します。

スパンタイプ 属性の識別 スパン名の例

エージェントを呼び出す

gen_ai.operation.name = invoke_agent

invoke_agent TravelAgent

実行ツール

gen_ai.operation.name = execute_tool

execute_tool search_flights

推測

gen_ai.operation.name = chat

chat

評価フィールドの抽出方法

会話コンテンツの場所は、テレメトリの収集方法によって異なります。ADOT がテレメトリを分割すると、コンテンツは別のイベントレコードにあります。テレメトリが分割されていない場合、コンテンツはインラインイベントとしてスパンに残ります。詳細については、「スパン、イベントレコード、テレメトリシグナル」を参照してください。どちらの場合も、識別属性 (gen_ai.operation.name) はスパン上にあります。

イベントレコードから

テレメトリが分割されると、サービスは各スパンに相関するイベントレコードからコンテンツを読み取ります。

  • ユーザープロンプト: エージェント入力メッセージ (input.messages) から、ユーザーロールを持つメッセージの内容。

  • エージェントレスポンス: エージェント出力メッセージ (output.messages) から、アシスタントロールを持つメッセージの内容。

  • ツール呼び出し: 実行ツールスパンの gen_ai.tool.name 属性からのツール名。ツールの引数と結果は、そのスパンのイベントレコード (input と ) から取得されますoutput。

例については、「イベントレコードを含むスパンの例」を参照してください。

インラインスパンイベントから

テレメトリが分割されていない場合、同じコンテンツが個別のイベントレコードではなくインラインスパンイベントで伝送されます。

  • ユーザープロンプト: gen_ai.user.messageイベントから、 content 属性。

  • エージェントレスポンス: gen_ai.choiceイベントからの message 属性。

  • ツール呼び出し: スパンの gen_ai.tool.name 属性からのツール名。ツール引数は gen_ai.tool.messageイベントから取得され、結果は gen_ai.choiceイベントから取得されます。

例については、「イベントレコードのないスパンの例」を参照してください。

イベントレコードを含むスパンの例

テレメトリが分割されると、スパンは識別属性を保持し、コンテンツは相関イベントレコードに存在します。次の例は、Amazon Bedrock AgentCore ランタイムにデプロイされた Strands の旅行計画エージェントからのものです。

注記

これらの例は完全なスパンではありません。実際のエージェントインタラクションからの代表的なデータが表示され、読みやすいように一部のフィールドは省略され、長い値は切り捨てられます。

例
Invoke agent span

gen_ai.operation.name 属性 (invoke_agent) は、これを呼び出しエージェントのスパンとして識別します。gen_ai.agent.tools 属性には、エージェントが使用できるツールが一覧表示されます。

{
  "traceId": "69e9cc4771d7cabe0d8e8cea33b6b338",
  "spanId": "d24936b8989b6d42",
  "parentSpanId": "0ff3498548044e4b",
  "name": "invoke_agent TravelAgent",
  "kind": "INTERNAL",
  "scope": {
    "name": "strands.telemetry.tracer",
    "version": ""
  },
  "startTimeUnixNano": 1776929864011990383,
  "endTimeUnixNano": 1776929869634304466,
  "durationNano": 5622314083,
  "attributes": {
    "gen_ai.operation.name": "invoke_agent",
    "gen_ai.system": "strands-agents",
    "gen_ai.agent.name": "TravelAgent",
    "gen_ai.request.model": "us.anthropic.claude-sonnet-4-20250514-v1:0",
    "gen_ai.usage.input_tokens": 983,
    "gen_ai.usage.output_tokens": 232,
    "gen_ai.usage.total_tokens": 1215,
    "gen_ai.agent.tools": "[\"search_flights\", \"book_flight\", \"search_hotels\", \"book_hotel\", \"search_activities\", \"book_activity\"]",
    "session.id": "sea-nyc-trip-2-turns-adot_v17-20260423003743"
  },
  "status": {
    "code": "OK"
  }
}

相関イベントレコードには会話コンテンツが格納されます。ユーザープロンプトは のユーザーロールメッセージでinput.messages、エージェントのレスポンスは のアシスタントロールメッセージですoutput.messages。

{
  "spanId": "d24936b8989b6d42",
  "traceId": "69e9cc4771d7cabe0d8e8cea33b6b338",
  "scope": {
    "name": "strands.telemetry.tracer"
  },
  "body": {
    "input": {
      "messages": [
        {
          "role": "user",
          "content": "Hey, how can you help me"
        }
      ]
    },
    "output": {
      "messages": [
        {
          "role": "assistant",
          "content": {
            "message": "Hi there! I'm your travel planning assistant ...",
            "finish_reason": "end_turn"
          }
        }
      ]
    }
  }
}
Execute tool span

gen_ai.operation.name 属性 (execute_tool) は、これを実行ツールスパンとして識別します。gen_ai.tool.name 属性はツール名を保持します。

{
  "traceId": "69e9cc4d132b180909ba49f613f273dd",
  "spanId": "fff785ce12d6fda8",
  "parentSpanId": "96915bf5ecc78743",
  "name": "execute_tool search_flights",
  "kind": "INTERNAL",
  "scope": {
    "name": "strands.telemetry.tracer",
    "version": ""
  },
  "startTimeUnixNano": 1776929872258292842,
  "endTimeUnixNano": 1776929872259611427,
  "durationNano": 1318585,
  "attributes": {
    "gen_ai.operation.name": "execute_tool",
    "gen_ai.tool.name": "search_flights",
    "gen_ai.tool.call.id": "tooluse_hiWwdtThuD67G5cK8cp5mj",
    "gen_ai.tool.status": "success",
    "gen_ai.tool.description": "Search for available flights between cities.",
    "session.id": "sea-nyc-trip-2-turns-adot_v17-20260423003743"
  },
  "status": {
    "code": "OK"
  }
}

相関イベントレコードには、ツールの入力 (引数) と出力 (結果) が保持されます。

{
  "spanId": "fff785ce12d6fda8",
  "traceId": "69e9cc4d132b180909ba49f613f273dd",
  "scope": {
    "name": "strands.telemetry.tracer"
  },
  "body": {
    "input": {
      "messages": [
        {
          "role": "tool",
          "content": {
            "content": "{\"origin\": \"SEA\", \"destination\": \"NYC\", \"date\": \"2025-03-15\"}",
            "role": "tool",
            "id": "tooluse_hiWwdtThuD67G5cK8cp5mj"
          }
        }
      ]
    },
    "output": {
      "messages": [
        {
          "role": "assistant",
          "content": {
            "message": "[{\"text\": \"{\\\"origin\\\": \\\"SEA\\\", \\\"destination\\\": \\\"NYC\\\", \\\"flights\\\": [ ... ]}\"}]",
            "id": "tooluse_hiWwdtThuD67G5cK8cp5mj"
          }
        }
      ]
    }
  }
}

イベントレコードのないスパンの例

テレメトリが分割されていない場合、同じコンテンツがスパンのインラインスパンイベントで伝送されます。個別のイベントレコードはありません。次の例は、Strands の旅行計画エージェントからのものです。

注記

これらの例は完全なスパンではありません。実際のエージェントインタラクションからの代表的なデータが表示され、読みやすいように一部のフィールドは省略され、長い値は切り捨てられます。

例
Invoke agent span

gen_ai.user.message イベントはユーザープロンプトを保持し、gen_ai.choiceイベントはエージェントのレスポンスを保持します。

{
  "traceId": "69e9cc4771d7cabe0d8e8cea33b6b338",
  "spanId": "d2ee0e4765cc773e",
  "name": "invoke_agent TravelAgent",
  "kind": "INTERNAL",
  "scope": {
    "name": "strands.telemetry.tracer"
  },
  "attributes": {
    "gen_ai.operation.name": "invoke_agent",
    "gen_ai.agent.name": "TravelAgent",
    "session.id": "sea-nyc-trip-2-turns-unified"
  },
  "events": [
    {
      "name": "gen_ai.user.message",
      "attributes": {
        "content": "[{\"text\": \"Hey, how can you help me\"}]"
      }
    },
    {
      "name": "gen_ai.choice",
      "attributes": {
        "message": "Hi there! I'm your travel planning assistant ...",
        "finish_reason": "end_turn"
      }
    }
  ]
}
Execute tool span

gen_ai.tool.message イベントはツール引数を保持し、gen_ai.choiceイベントはツールの結果を保持します。

{
  "traceId": "69e9cc4d132b180909ba49f613f273dd",
  "spanId": "0a988e27758ebb53",
  "name": "execute_tool search_flights",
  "kind": "INTERNAL",
  "scope": {
    "name": "strands.telemetry.tracer"
  },
  "attributes": {
    "gen_ai.operation.name": "execute_tool",
    "gen_ai.tool.name": "search_flights",
    "gen_ai.tool.call.id": "tooluse_JuGterOaZfQV2c55Rp3S7C",
    "gen_ai.tool.status": "success",
    "session.id": "sea-nyc-trip-2-turns-unified"
  },
  "events": [
    {
      "name": "gen_ai.tool.message",
      "attributes": {
        "content": "{\"origin\": \"SEA\", \"destination\": \"NYC\", \"date\": \"2025-03-15\"}",
        "role": "tool",
        "id": "tooluse_JuGterOaZfQV2c55Rp3S7C"
      }
    },
    {
      "name": "gen_ai.choice",
      "attributes": {
        "message": "[{\"text\": \"{\\\"origin\\\": \\\"SEA\\\", \\\"destination\\\": \\\"NYC\\\", \\\"flights\\\": [ ... ]}\"}]",
        "id": "tooluse_JuGterOaZfQV2c55Rp3S7C"
      }
    }
  ]
}