View a markdown version of this page

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

Agen OpenAI

Halaman ini menjelaskan cara instrumen agen Agen OpenAI, bagaimana rentang diidentifikasi, dan bagaimana bidang evaluasi diekstraksi.

Topik

Instrumen agen Anda

Anda dapat menginstrumentasikan agen Agen OpenAI dengan salah satu dari dua pustaka instrumentasi: OpenTelemetry(opentelemetry-instrumentation-openai-agents) atau (). OpenInferenceopeninference-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.

contoh
OpenTelemetry

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",
]
OpenInference

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.

Bagaimana rentang diidentifikasi

Atribut yang digunakan untuk mengklasifikasikan bentang berbeda antara dua pustaka instrumentasi.

contoh
OpenTelemetry

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

catatan

Agen OpenAI juga memancarkan bentang batas giliran internal dengan =. gen_ai.operation.name unknown Layanan evaluasi melewatkan ini.

OpenInference

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

catatan

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.nameatauopeninference.span.kind) berada pada rentang dalam kedua kasus. Untuk informasi selengkapnya, lihat Rentang, catatan peristiwa, dan sinyal telemetri.

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 danbody.output.

    • Panggilan alat: nama alat darigen_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 danbody.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 danbody.output.

Sebagai contoh, lihat Contoh bentang dengan catatan peristiwa.

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 darigen_ai.tool.name, dan argumen dan hasil dari gen_ai.tool.call.arguments dangen_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. danllm.output_messages.), lalu diisi kembali ke rentang agen pemanggilan kosong.

    • Panggilan alat: nama alat daritool.name, dan argumen dan hasil dari input.value danoutput.value, pada rentang alat eksekusi.

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 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

contoh
Invoke agent span

gen_ai.operation.nameAtribut (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 ...\"}]}]"
        }
      ]
    }
  }
}
Execute tool span

gen_ai.operation.nameAtribut (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"
  }
}
Inference span

gen_ai.operation.nameAtribut (chat) mengidentifikasi ini sebagai rentang inferensi. Rentang ini membawa metadata model dan, dalamgen_ai.tool.definitions, daftar alat yang tersedia untuk agen. Pesan percakapan untuk panggilan model langsung dalam catatan peristiwa yang berkorelasi, di body.input danbody.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.

contoh
Invoke agent span

openinference.span.kindAtribut (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"
  }
}
Execute tool span

openinference.span.kindAtribut (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\": [ ... ]}" }
      ]
    }
  }
}
Inference span

openinference.span.kindAtribut (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 inputuser, 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

contoh
Invoke agent span

gen_ai.input.messagesAtribut 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"
  }
}
Execute tool span

gen_ai.tool.call.argumentsAtribut 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"
  }
}
Inference span

gen_ai.operation.nameAtribut (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

contoh
Execute tool span

input.valueAtribut 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"
  }
}
Inference span

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