# Agen OpenAI
Halaman ini menjelaskan cara instrumen [agen Agen OpenAI](https://openai.github.io/openai-agents-python/), bagaimana rentang diidentifikasi, dan bagaimana bidang evaluasi diekstraksi.
**Topik**
+ [Instrumen agen Anda](#openai-agents-instrument)
+ [Bagaimana rentang diidentifikasi](#openai-agents-span-identification)
+ [Bagaimana bidang evaluasi diekstraksi](#openai-agents-extraction)
+ [Dari catatan acara](#openai-agents-extraction-event-records)
+ [Dari atribut span](#openai-agents-extraction-attributes)
+ [Contoh membentang dengan catatan acara](#openai-agents-examples-with)
+ [Contoh membentang tanpa catatan peristiwa](#openai-agents-examples-without)
## Instrumen agen Anda
Anda dapat menginstrumentasikan agen Agen OpenAI dengan salah satu dari dua pustaka instrumentasi: **OpenTelemetry**(`opentelemetry-instrumentation-openai-agents`) atau (). **OpenInference**`openinference-instrumentation-openai-agents` Amazon Bedrock AgentCore Evaluations mendukung kedua pustaka. Pustaka memancarkan nama lingkup yang berbeda dan menggunakan atribut rentang yang berbeda. Layanan evaluasi mengekstrak nilai yang sama dari masing-masing.
Saat agen Anda berjalan dengan AWS Distro for OpenTelemetry (ADOT), seperti di Amazon Bedrock AgentCore Runtime, Anda tidak perlu menambahkan kode instrumentasi eksplisit. Menambahkan pustaka instrumentasi ke dependensi proyek Anda sudah cukup. ADOT menemukannya saat startup dan mengaktifkannya secara otomatis.
Tambahkan pustaka instrumentasi untuk jalur yang Anda inginkan ke dependensi Anda. Gunakan versi terbaru yang tersedia kecuali Anda memiliki alasan untuk menyematkan.
**Example**
CATATAN: Gunakan versi `0.61.0` atau yang lebih baru. Ini adalah versi paling awal yang diuji dengan layanan evaluasi.
Tambahkan `opentelemetry-instrumentation-openai-agents` ke dependensi Anda. Nama lingkup yang dipancarkan adalah. `opentelemetry.instrumentation.openai_agents`
`requirements.txt`:
```
opentelemetry-instrumentation-openai-agents>=0.61.0
```
`pyproject.toml`:
```
[project]
dependencies = [
"opentelemetry-instrumentation-openai-agents>=0.61.0",
]
```
CATATAN: Gunakan versi `1.5.0` atau yang lebih baru. Ini adalah versi paling awal yang diuji dengan layanan evaluasi.
Tambahkan `openinference-instrumentation-openai-agents` ke dependensi Anda. Nama lingkup yang dipancarkan adalah. `openinference.instrumentation.openai_agents`
`requirements.txt`:
```
openinference-instrumentation-openai-agents>=1.5.0
```
`pyproject.toml`:
```
[project]
dependencies = [
"openinference-instrumentation-openai-agents>=1.5.0",
]
```
**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
Atribut yang digunakan untuk mengklasifikasikan bentang berbeda antara dua pustaka instrumentasi.
**Example**
Pustaka OpenTelemetry instrumentasi mengklasifikasikan rentang menggunakan atribut. `gen_ai.operation.name`
| Jenis rentang | Mengidentifikasi atribut |
| --- | --- |
| Memohon agen | `gen_ai.operation.name` = `invoke_agent` |
| Jalankan alat | `gen_ai.operation.name` = `execute_tool` |
| Inferensi | `gen_ai.operation.name` = `chat` |
Agen OpenAI juga memancarkan bentang batas giliran internal dengan =. `gen_ai.operation.name` `unknown` Layanan evaluasi melewatkan ini.
Pustaka OpenInference instrumentasi mengklasifikasikan rentang menggunakan atribut. `openinference.span.kind`
| Jenis rentang | Mengidentifikasi atribut |
| --- | --- |
| Memohon agen | `openinference.span.kind`= `AGENT` atau `CHAIN` |
| Jalankan alat | `openinference.span.kind` = `TOOL` |
| Inferensi | `openinference.span.kind` = `LLM` |
Dengan OpenInference perpustakaan, `AGENT` dan `CHAIN` bentang adalah wadah struktural kosong: mereka tidak membawa konten percakapan. Prompt pengguna dan respons agen direkonstruksi dari rentang inferensi (`LLM`) dalam jejak yang sama.
## Bagaimana bidang evaluasi diekstraksi
Agen OpenAI membuat serial pesan dalam format berbasis bagian, di mana setiap pesan membawa `parts` array blok konten yang diketik (misalnya,). `[{"role": "user", "parts": [{"type": "text", "content": "…"}]}]` Dengan OpenTelemetry perpustakaan, AgentCore Evaluasi mem-parsing teks dari bagian-bagian ini. Dengan OpenInference pustaka, output model adalah objek Respons OpenAI lengkap, dan AgentCore Evaluations membaca teks respons dari. `output[].content[].text`
Lokasi konten ini tergantung pada bagaimana telemetri dikumpulkan. Atribut pengidentifikasi (`gen_ai.operation.name`atau`openinference.span.kind`) berada pada rentang dalam kedua kasus. Untuk informasi selengkapnya, lihat [Rentang, catatan peristiwa, dan sinyal telemetri](supported-frameworks-telemetry.md).
### Dari catatan acara
Ketika telemetri dibagi, AgentCore Evaluasi membaca konten percakapan dari catatan peristiwa yang berkorelasi dengan setiap rentang. Lokasi input dan output alat berbeda antara dua pustaka:
+ **OpenTelemetry**:
+ **Prompt pengguna** dan **respons agen**: dari catatan peristiwa rentang agen pemanggilan, di `body.input` dan`body.output`.
+ **Panggilan alat**: nama alat dari`gen_ai.tool.name`, dan argumen dan hasil dari `gen_ai.tool.call.arguments` dan `gen_ai.tool.call.result` pada rentang alat eksekusi. Dengan OpenTelemetry perpustakaan, argumen alat dan hasil tetap pada atribut rentang bahkan ketika telemetri dibagi.
+ **OpenInference**:
+ **Prompt pengguna** dan **respons agen**: direkonstruksi dari catatan peristiwa rentang inferensi. AgentCore Evaluasi membaca pesan dari `body.input` dan`body.output`, kemudian mengisi kembali rentang agen pemanggilan kosong dengan prompt pengguna dan respons agen.
+ **Panggilan alat**: nama alat dari `tool.name` rentang alat eksekusi. Argumen dan hasil alat berasal dari catatan peristiwa rentang itu, di `body.input` dan`body.output`.
Sebagai contoh, lihat [Contoh bentang dengan catatan peristiwa](#openai-agents-examples-with).
### Dari atribut span
Ketika telemetri tidak dibagi, konten yang sama tetap pada rentang sebagai atribut. Atribut tergantung pada pustaka instrumentasi:
+ **OpenTelemetry**:
+ **Prompt pengguna** dan **respons agen**: dari `gen_ai.input.messages` dan `gen_ai.output.messages` pada rentang agen pemanggilan.
+ **Panggilan alat**: nama alat dari`gen_ai.tool.name`, dan argumen dan hasil dari `gen_ai.tool.call.arguments` dan`gen_ai.tool.call.result`, pada rentang alat eksekusi.
+ **OpenInference**:
+ **Prompt pengguna** dan **respons agen**: dari atribut pesan yang diindeks pada rentang inferensi (`llm.input_messages. `dan`llm.output_messages.`), lalu diisi kembali ke rentang agen pemanggilan kosong.
+ **Panggilan alat**: nama alat dari`tool.name`, dan argumen dan hasil dari `input.value` dan`output.value`, pada rentang alat eksekusi.
Sebagai contoh, lihat [Contoh rentang tanpa catatan peristiwa](#openai-agents-examples-without).
## 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 Agen OpenAI yang digunakan di Amazon Bedrock Runtime. AgentCore Agen yang sama ditampilkan di bawah setiap pustaka instrumentasi.
**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.
### OpenTelemetry
**Example**
`gen_ai.operation.name`Atribut (`invoke_agent`) mengidentifikasi ini sebagai rentang agen pemanggilan.
```
{
"traceId": "6a01eef11066751d68f90def0da1f80a",
"spanId": "3a300b0b3fe650e4",
"name": "invoke_agent openaiOtelTravel",
"kind": "INTERNAL",
"scope": {
"name": "opentelemetry.instrumentation.openai_agents",
"version": "0.62.1"
},
"attributes": {
"gen_ai.operation.name": "invoke_agent",
"gen_ai.agent.name": "openaiOtelTravel",
"gen_ai.system": "openai",
"gen_ai.provider.name": "openai",
"gen_ai.request.model": "gpt-4o-mini-2024-07-18",
"session.id": "sea-nyc-trip-2-turns-openai-otel"
},
"status": {
"code": "OK"
}
}
```
Catatan peristiwa yang berkorelasi membawa percakapan. Setiap pesan `content` adalah array format bagian OpenAI; prompt pengguna adalah teks pesan pengguna dan respons agen adalah teks dari pesan asisten.
```
{
"spanId": "3a300b0b3fe650e4",
"traceId": "6a01eef11066751d68f90def0da1f80a",
"scope": {
"name": "opentelemetry.instrumentation.openai_agents"
},
"body": {
"input": {
"messages": [
{
"role": "user",
"content": "[{\"role\": \"user\", \"parts\": [{\"type\": \"text\", \"content\": \"Hey, how can you help me\"}]}]"
}
]
},
"output": {
"messages": [
{
"role": "assistant",
"content": "[{\"role\": \"assistant\", \"parts\": [{\"type\": \"text\", \"content\": \"I can assist you with planning your trips ...\"}]}]"
}
]
}
}
}
```
`gen_ai.operation.name`Atribut (`execute_tool`) mengidentifikasi ini sebagai rentang alat eksekusi; `gen_ai.tool.name` memegang nama alat. Dengan OpenTelemetry perpustakaan, argumen alat dan hasil tetap pada atribut span bahkan ketika telemetri dibagi.
```
{
"traceId": "6a01eefa5c52f3d86a35038f35f5ba30",
"spanId": "3cbc4ea5f73fef81",
"name": "execute_tool search_flights",
"kind": "INTERNAL",
"scope": {
"name": "opentelemetry.instrumentation.openai_agents",
"version": "0.62.1"
},
"attributes": {
"gen_ai.operation.name": "execute_tool",
"gen_ai.tool.name": "search_flights",
"gen_ai.tool.type": "function",
"gen_ai.tool.call.arguments": "{\"origin\": \"SEA\", \"destination\": \"NYC\", \"date\": \"2025-03-15\"}",
"gen_ai.tool.call.result": "{\"origin\": \"SEA\", \"destination\": \"NYC\", \"flights\": [ ... ]}",
"session.id": "sea-nyc-trip-2-turns-openai-otel"
},
"status": {
"code": "OK"
}
}
```
`gen_ai.operation.name`Atribut (`chat`) mengidentifikasi ini sebagai rentang inferensi. Rentang ini membawa metadata model dan, dalam`gen_ai.tool.definitions`, daftar alat yang tersedia untuk agen. Pesan percakapan untuk panggilan model langsung dalam catatan peristiwa yang berkorelasi, di `body.input` dan`body.output`.
```
{
"traceId": "6a01eef11066751d68f90def0da1f80a",
"spanId": "7c1f9a2b4d6e8a03",
"name": "openai.response",
"kind": "INTERNAL",
"scope": {
"name": "opentelemetry.instrumentation.openai_agents",
"version": "0.62.1"
},
"attributes": {
"gen_ai.operation.name": "chat",
"gen_ai.provider.name": "openai",
"gen_ai.request.model": "gpt-4o-mini-2024-07-18",
"gen_ai.response.model": "gpt-4o-mini-2024-07-18",
"gen_ai.usage.input_tokens": 269,
"gen_ai.usage.output_tokens": 78,
"gen_ai.tool.definitions": "[{\"type\": \"function\", \"function\": {\"name\": \"search_flights\", \"description\": \"Search for available flights between cities.\", \"parameters\": { ... }}}]",
"session.id": "sea-nyc-trip-2-turns-openai-otel"
},
"status": {
"code": "OK"
}
}
```
```
{
"spanId": "7c1f9a2b4d6e8a03",
"traceId": "6a01eef11066751d68f90def0da1f80a",
"scope": {
"name": "opentelemetry.instrumentation.openai_agents"
},
"body": {
"input": {
"messages": [
{
"role": "user",
"content": "[{\"role\": \"user\", \"parts\": [{\"type\": \"text\", \"content\": \"Hey, how can you help me\"}]}]"
}
]
},
"output": {
"messages": [
{
"role": "assistant",
"content": "[{\"role\": \"assistant\", \"parts\": [{\"type\": \"text\", \"content\": \"I can assist you with planning your trips ...\"}]}]"
}
]
}
}
}
```
### OpenInference
Dengan OpenInference perpustakaan, rentang invoke agent (`AGENT`) adalah wadah kosong. AgentCore Evaluasi merekonstruksi prompt pengguna dan respons agen dari rentang inferensi (`LLM`), yang isinya hidup dalam catatan peristiwa yang berkorelasi.
**Example**
`openinference.span.kind`Atribut (`AGENT`) mengidentifikasi ini sebagai rentang agen pemanggilan. Rentang tidak membawa konten percakapan.
```
{
"traceId": "6a387ee61078243c1cc455ed45c6c313",
"spanId": "9a1c7dce81b692cd",
"name": "openaiOInfTravel",
"kind": "INTERNAL",
"scope": {
"name": "openinference.instrumentation.openai_agents",
"version": "1.5.0"
},
"attributes": {
"openinference.span.kind": "AGENT",
"graph.node.id": "openaiOInfTravel",
"llm.system": "openai",
"session.id": "sea-nyc-trip-2-turns-openai-oi"
},
"status": {
"code": "OK"
}
}
```
`openinference.span.kind`Atribut (`TOOL`) mengidentifikasi ini sebagai rentang alat eksekusi; `tool.name` memegang nama alat. Argumen dan hasil alat hidup dalam catatan peristiwa yang berkorelasi.
```
{
"traceId": "6a387ef07b8f4f3732fab45d3c0b51ff",
"spanId": "b4e78cb0a06a6fe2",
"name": "search_flights",
"kind": "INTERNAL",
"scope": {
"name": "openinference.instrumentation.openai_agents",
"version": "1.5.0"
},
"attributes": {
"openinference.span.kind": "TOOL",
"tool.name": "search_flights",
"input.mime_type": "application/json",
"output.mime_type": "application/json",
"session.id": "sea-nyc-trip-2-turns-openai-oi"
},
"status": {
"code": "OK"
}
}
```
```
{
"spanId": "b4e78cb0a06a6fe2",
"traceId": "6a387ef07b8f4f3732fab45d3c0b51ff",
"scope": {
"name": "openinference.instrumentation.openai_agents"
},
"body": {
"input": {
"messages": [
{ "role": "user", "content": "{\"origin\": \"SEA\", \"destination\": \"NYC\", \"date\": \"2025-03-15\"}" }
]
},
"output": {
"messages": [
{ "role": "assistant", "content": "{\"origin\": \"SEA\", \"destination\": \"NYC\", \"flights\": [ ... ]}" }
]
}
}
}
```
`openinference.span.kind`Atribut (`LLM`) mengidentifikasi ini sebagai rentang inferensi. Peran pesan dan definisi alat ada pada atribut rentang; konten pesan berada dalam catatan peristiwa yang berkorelasi. ADOT meratakan peran input`user`, sehingga AgentCore Evaluations menggunakan pesan input teks biasa terakhir sebagai prompt pengguna. Pesan output adalah objek OpenAI Response, dari mana AgentCore Evaluations membaca teks respons.
```
{
"traceId": "6a387ee61078243c1cc455ed45c6c313",
"spanId": "1221a062c7f90a8e",
"name": "response",
"kind": "INTERNAL",
"scope": {
"name": "openinference.instrumentation.openai_agents",
"version": "1.5.0"
},
"attributes": {
"openinference.span.kind": "LLM",
"llm.model_name": "gpt-4o-mini-2024-07-18",
"llm.input_messages.0.message.role": "system",
"llm.input_messages.1.message.role": "user",
"llm.output_messages.0.message.role": "assistant",
"llm.tools.0.tool.json_schema": "{\"type\": \"function\", \"function\": {\"name\": \"search_flights\", ...}}",
"session.id": "sea-nyc-trip-2-turns-openai-oi"
},
"status": {
"code": "OK"
}
}
```
```
{
"spanId": "1221a062c7f90a8e",
"traceId": "6a387ee61078243c1cc455ed45c6c313",
"scope": {
"name": "openinference.instrumentation.openai_agents"
},
"body": {
"input": {
"messages": [
{ "role": "user", "content": "[{\"content\": \"Hey, how can you help me\", \"role\": \"user\"}]" },
{ "role": "user", "content": "You are a travel planning assistant. Help users plan trips ..." },
{ "role": "user", "content": "Hey, how can you help me" }
]
},
"output": {
"messages": [
{
"role": "assistant",
"content": "{\"id\": \"resp_abc123...\", \"output\": [{\"type\": \"message\", \"content\": [{\"type\": \"output_text\", \"text\": \"I can assist you with planning your trips ...\"}]}]}"
}
]
}
}
}
```
## Contoh membentang tanpa catatan peristiwa
Ketika telemetri tidak dibagi, konten yang sama tetap pada atribut rentang dan tidak ada catatan peristiwa terpisah yang dihasilkan. Contoh berikut berasal dari agen perencanaan perjalanan Agen OpenAI. Agen yang sama ditampilkan di bawah setiap pustaka instrumentasi.
**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.
### OpenTelemetry
**Example**
`gen_ai.input.messages`Atribut menahan prompt pengguna, dan `gen_ai.output.messages` atribut menahan respons agen. Keduanya adalah array format bagian OpenAI.
```
{
"traceId": "6a4de7b85e61747e6b568a1f4768e89d",
"spanId": "50656fd77904d125",
"name": "invoke_agent openaiOtelTravel",
"kind": "INTERNAL",
"scope": {
"name": "opentelemetry.instrumentation.openai_agents",
"version": "0.62.1"
},
"attributes": {
"gen_ai.operation.name": "invoke_agent",
"gen_ai.agent.name": "openaiOtelTravel",
"gen_ai.system": "openai",
"gen_ai.input.messages": "[{\"role\": \"user\", \"parts\": [{\"type\": \"text\", \"content\": \"Hey, how can you help me\"}]}]",
"gen_ai.output.messages": "[{\"role\": \"assistant\", \"parts\": [{\"type\": \"text\", \"content\": \"I can assist you with planning your trips ...\"}]}]",
"session.id": "sea-nyc-trip-2-turns-unified"
},
"status": {
"code": "OK"
}
}
```
`gen_ai.tool.call.arguments`Atribut memegang argumen alat, dan `gen_ai.tool.call.result` atribut memegang hasil alat.
```
{
"traceId": "6a4de7c376913db82e6f0f336a16731d",
"spanId": "8840e8e23724ebd7",
"name": "execute_tool search_flights",
"kind": "INTERNAL",
"scope": {
"name": "opentelemetry.instrumentation.openai_agents",
"version": "0.62.1"
},
"attributes": {
"gen_ai.operation.name": "execute_tool",
"gen_ai.tool.name": "search_flights",
"gen_ai.tool.call.arguments": "{\"origin\": \"SEA\", \"destination\": \"NYC\", \"date\": \"2025-03-15\"}",
"gen_ai.tool.call.result": "{\"origin\": \"SEA\", \"destination\": \"NYC\", \"flights\": [ ... ]}",
"session.id": "sea-nyc-trip-2-turns-unified"
},
"status": {
"code": "OK"
}
}
```
`gen_ai.operation.name`Atribut (`chat`) mengidentifikasi ini sebagai rentang inferensi. Metadata model dan `gen_ai.tool.definitions` atribut (daftar alat yang tersedia untuk agen) tetap sebaris pada rentang.
```
{
"traceId": "6a4de7b85e61747e6b568a1f4768e89d",
"spanId": "9b2c1e5f7a3d0846",
"name": "openai.response",
"kind": "INTERNAL",
"scope": {
"name": "opentelemetry.instrumentation.openai_agents",
"version": "0.62.1"
},
"attributes": {
"gen_ai.operation.name": "chat",
"gen_ai.provider.name": "openai",
"gen_ai.request.model": "gpt-4o-mini-2024-07-18",
"gen_ai.response.model": "gpt-4o-mini-2024-07-18",
"gen_ai.usage.input_tokens": 269,
"gen_ai.usage.output_tokens": 78,
"gen_ai.tool.definitions": "[{\"type\": \"function\", \"function\": {\"name\": \"search_flights\", \"description\": \"Search for available flights between cities.\", \"parameters\": { ... }}}]",
"session.id": "sea-nyc-trip-2-turns-unified"
},
"status": {
"code": "OK"
}
}
```
### OpenInference
**Example**
`input.value`Atribut memegang argumen alat, dan `output.value` atribut memegang hasil alat.
```
{
"traceId": "6a387ef07b8f4f3732fab45d3c0b51ff",
"spanId": "d5a1c9e70b46f312",
"name": "search_flights",
"kind": "INTERNAL",
"scope": {
"name": "openinference.instrumentation.openai_agents",
"version": "1.5.1"
},
"attributes": {
"openinference.span.kind": "TOOL",
"tool.name": "search_flights",
"input.value": "{\"origin\": \"SEA\", \"destination\": \"NYC\", \"date\": \"2025-03-15\"}",
"output.value": "{\"origin\": \"SEA\", \"destination\": \"NYC\", \"flights\": [ ... ]}",
"session.id": "sea-nyc-trip-2-turns-oi"
},
"status": {
"code": "OK"
}
}
```
Konten pesan sebaris pada atribut yang diindeks. `llm.input_messages. `Atribut menahan prompt sistem dan prompt pengguna, dan `llm.output_messages.` atribut menahan respons agen. AgentCore Evaluasi merekonstruksi prompt pengguna dan respons agen dari rentang ini dan mengisi ulang rentang agen pemanggilan kosong (). `AGENT`
```
{
"traceId": "6a387ee61078243c1cc455ed45c6c313",
"spanId": "c9f0a2b41d773e88",
"name": "response",
"kind": "INTERNAL",
"scope": {
"name": "openinference.instrumentation.openai_agents",
"version": "1.5.1"
},
"attributes": {
"openinference.span.kind": "LLM",
"llm.model_name": "gpt-4o-mini-2024-07-18",
"llm.input_messages.0.message.role": "system",
"llm.input_messages.0.message.content": "You are a travel planning assistant ...",
"llm.input_messages.1.message.role": "user",
"llm.input_messages.1.message.content": "Hey, how can you help me",
"llm.output_messages.0.message.role": "assistant",
"llm.output_messages.0.message.contents.0.message_content.text": "I can assist you with planning your trips ...",
"session.id": "sea-nyc-trip-2-turns-oi"
},
"status": {
"code": "OK"
}
}
```