# Agen Helai
<a name="supported-frameworks-strands"></a>

Halaman ini menjelaskan cara instrumen [agen Strands Agents](https://strandsagents.com/latest/), bagaimana rentang diidentifikasi, dan bagaimana bidang evaluasi diekstraksi.

 **Topik** 
+  [Instrumen agen Anda](#strands-instrument) 
+  [Bagaimana rentang diidentifikasi](#strands-span-identification) 
+  [Bagaimana bidang evaluasi diekstraksi](#strands-extraction) 
  +  [Dari catatan acara](#strands-extraction-event-records) 
  +  [Dari acara rentang sebaris](#strands-extraction-inline-events) 
+  [Contoh membentang dengan catatan acara](#strands-examples-with) 
+  [Contoh membentang tanpa catatan peristiwa](#strands-examples-without) 

## Instrumen agen Anda
<a name="strands-instrument"></a>

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](supported-frameworks.md#supported-frameworks-setup).

## Bagaimana rentang diidentifikasi
<a name="strands-span-identification"></a>

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
<a name="strands-extraction"></a>

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](supported-frameworks-telemetry.md). Atribut pengidentifikasi (`gen_ai.operation.name`) berada pada rentang dalam kedua kasus.

### Dari catatan acara
<a name="strands-extraction-event-records"></a>

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 (`input`dan`output`).

Sebagai contoh, lihat [Contoh bentang dengan catatan peristiwa](#strands-examples-with).

### Dari acara rentang sebaris
<a name="strands-extraction-inline-events"></a>

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](#strands-examples-without).

## Contoh membentang dengan catatan acara
<a name="strands-examples-with"></a>

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.

**Example**  
`gen_ai.operation.name`Atribut (`invoke_agent`) mengidentifikasi ini sebagai rentang agen pemanggilan. `gen_ai.agent.tools`Atribut 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 pengguna`input.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"
          }
        }
      ]
    }
  }
}
```
`gen_ai.operation.name`Atribut (`execute_tool`) mengidentifikasi ini sebagai rentang alat eksekusi. `gen_ai.tool.name`Atribut 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
<a name="strands-examples-without"></a>

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.

**Example**  
`gen_ai.user.message`Acara 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"
      }
    }
  ]
}
```
`gen_ai.tool.message`Acara 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"
      }
    }
  ]
}
```