View a markdown version of this page

Agen Helai - Batuan Dasar Amazon AgentCore
Instrumen agen AndaBagaimana rentang diidentifikasiBagaimana bidang evaluasi diekstraksiContoh membentang dengan catatan acaraContoh membentang tanpa catatan peristiwa

Agen Helai

Halaman ini menjelaskan cara instrumen agen Strands Agents, bagaimana rentang diidentifikasi, dan bagaimana bidang evaluasi diekstraksi.

Topik

Instrumen agen Anda

Strands Agents SDK menyertakan telemetri bawaan dan tidak memerlukan pustaka instrumentasi tambahan. Ini menghasilkan rentang dan catatan peristiwa di bawah nama strands.telemetry.tracer lingkup. Saat digunakan di Amazon Bedrock AgentCore Runtime dengan AWS Distro for OpenTelemetry (ADOT), Runtime menyuntikkan session.id atribut dan mengekspor rentang serta catatan peristiwa secara otomatis.

catatan

Instrumentasi adalah salah satu langkah dalam mengatur observabilitas. Untuk mengekspor telemetri untuk evaluasi, selesaikan pengaturan lengkap di Siapkan observabilitas.

Bagaimana rentang diidentifikasi

Helai menetapkan gen_ai.operation.name atribut pada setiap rentang. Layanan evaluasi menggunakan atribut ini untuk mengklasifikasikan rentang:

Jenis rentang Mengidentifikasi atribut Contoh nama rentang

Memohon agen

gen_ai.operation.name = invoke_agent

invoke_agent TravelAgent

Jalankan alat

gen_ai.operation.name = execute_tool

execute_tool search_flights

Inferensi

gen_ai.operation.name = chat

chat

Bagaimana bidang evaluasi diekstraksi

Lokasi konten percakapan tergantung pada bagaimana telemetri dikumpulkan. Ketika ADOT membagi telemetri, konten berada dalam catatan peristiwa terpisah. Ketika telemetri tidak dibagi, konten tetap pada rentang sebagai peristiwa sebaris. Untuk informasi selengkapnya, lihat Rentang, catatan peristiwa, dan sinyal telemetri. Atribut pengidentifikasi (gen_ai.operation.name) berada pada rentang dalam kedua kasus.

Dari catatan acara

Saat telemetri dibagi, layanan membaca konten dari catatan peristiwa yang berkorelasi dengan setiap rentang:

  • Prompt pengguna: dari pesan masukan agen (input.messages), konten pesan dengan peran pengguna.

  • Respons agen: dari pesan keluaran agen (output.messages), isi pesan dengan peran asisten.

  • Panggilan alat: nama alat dari gen_ai.tool.name atribut pada rentang alat eksekusi. Argumen dan hasil alat berasal dari catatan peristiwa rentang itu (inputdanoutput).

Sebagai contoh, lihat Contoh bentang dengan catatan peristiwa.

Dari acara rentang sebaris

Ketika telemetri tidak dibagi, konten yang sama dibawa dalam peristiwa rentang sebaris alih-alih catatan peristiwa terpisah:

  • Prompt pengguna: dari gen_ai.user.message acara, content atribut.

  • Respon agen: dari gen_ai.choice acara, message atribut.

  • Panggilan alat: nama alat dari gen_ai.tool.name atribut pada rentang. Argumen alat berasal dari gen_ai.tool.message acara, dan hasilnya berasal dari gen_ai.choice acara tersebut.

Sebagai contoh, lihat Contoh rentang tanpa catatan peristiwa.

Contoh membentang dengan catatan acara

Ketika telemetri dibagi, rentang membawa atribut pengidentifikasi dan konten hidup dalam catatan peristiwa yang berkorelasi. Contoh berikut berasal dari agen perencanaan perjalanan Strands yang digunakan di Amazon Bedrock Runtime. AgentCore

catatan

Contoh-contoh ini bukan bentang lengkap. Mereka menunjukkan data representatif dari interaksi agen nyata, dengan beberapa bidang dihilangkan dan nilai panjang dipotong untuk keterbacaan.

contoh
Invoke agent span

gen_ai.operation.nameAtribut (invoke_agent) mengidentifikasi ini sebagai rentang agen pemanggilan. gen_ai.agent.toolsAtribut mencantumkan alat yang tersedia untuk agen.

{
  "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"
  }
}

Catatan peristiwa yang berkorelasi membawa konten percakapan. Prompt pengguna adalah pesan peran penggunainput.messages, dan respons agen adalah pesan peran asisten. 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.nameAtribut (execute_tool) mengidentifikasi ini sebagai rentang alat eksekusi. gen_ai.tool.nameAtribut memegang nama alat.

{
  "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"
  }
}

Catatan peristiwa yang berkorelasi membawa input alat (argumen) dan output (hasil).

{
  "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"
          }
        }
      ]
    }
  }
}

Contoh membentang tanpa catatan peristiwa

Ketika telemetri tidak dibagi, konten yang sama dibawa dalam peristiwa rentang sebaris pada rentang, tanpa catatan peristiwa terpisah. Contoh berikut berasal dari agen perencanaan perjalanan Strands.

catatan

Contoh-contoh ini bukan bentang lengkap. Mereka menunjukkan data representatif dari interaksi agen nyata, dengan beberapa bidang dihilangkan dan nilai panjang dipotong untuk keterbacaan.

contoh
Invoke agent span

gen_ai.user.messageAcara ini memegang prompt pengguna, dan gen_ai.choice acara tersebut memegang respons agen.

{
  "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.messageAcara memegang argumen alat, dan gen_ai.choice acara memegang hasil alat.

{
  "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"
      }
    }
  ]
}