# OpenAI エージェント
このページでは、[OpenAI エージェント](https://openai.github.io/openai-agents-python/)を計測する方法、スパンの特定方法、評価フィールドの抽出方法について説明します。
**トピック**
+ [エージェントを計測する](#openai-agents-instrument)
+ [スパンの識別方法](#openai-agents-span-identification)
+ [評価フィールドの抽出方法](#openai-agents-extraction)
+ [イベントレコードから](#openai-agents-extraction-event-records)
+ [スパン属性から](#openai-agents-extraction-attributes)
+ [イベントレコードを含むスパンの例](#openai-agents-examples-with)
+ [イベントレコードのないスパンの例](#openai-agents-examples-without)
## エージェントを計測する
OpenAI エージェントは、**OpenTelemetry** (`opentelemetry-instrumentation-openai-agents`) または **OpenInference** () の 2 つの計測ライブラリのいずれかを使用して計測できます`openinference-instrumentation-openai-agents`。Amazon Bedrock AgentCore Evaluations は両方のライブラリをサポートしています。ライブラリは異なるスコープ名を出力し、異なるスパン属性を使用します。評価サービスは、それぞれから同じ値を抽出します。
Amazon Bedrock AgentCore ランタイムなど、エージェントが AWS Distro for OpenTelemetry (ADOT) で実行されている場合、明示的な計測コードを追加する必要はありません。計測ライブラリをプロジェクトの依存関係に追加するだけで十分です。ADOT は起動時に検出し、自動的にアクティブ化します。
依存関係に必要なパスの計測ライブラリを追加します。ピン留めする理由がない限り、利用可能な最新バージョンを使用してください。
**Example**
注: バージョン `0.61.0` 以降を使用します。これは、評価サービスでテストされた最も古いバージョンです。
`opentelemetry-instrumentation-openai-agents` を依存関係に追加します。出力されるスコープ名は です`opentelemetry.instrumentation.openai_agents`。
`requirements.txt`:
```
opentelemetry-instrumentation-openai-agents>=0.61.0
```
`pyproject.toml`:
```
[project]
dependencies = [
"opentelemetry-instrumentation-openai-agents>=0.61.0",
]
```
注: バージョン `1.5.0` 以降を使用します。これは、評価サービスでテストされた最も古いバージョンです。
`openinference-instrumentation-openai-agents` を依存関係に追加します。出力されるスコープ名は です`openinference.instrumentation.openai_agents`。
`requirements.txt`:
```
openinference-instrumentation-openai-agents>=1.5.0
```
`pyproject.toml`:
```
[project]
dependencies = [
"openinference-instrumentation-openai-agents>=1.5.0",
]
```
**注記**
計測は、オブザーバビリティを設定する 1 つのステップです。評価のためにテレメトリをエクスポートするには、[「オブザーバビリティの設定](supported-frameworks.md#supported-frameworks-setup)」で完全なセットアップを完了します。
## スパンの識別方法
スパンの分類に使用される属性は、2 つの計測ライブラリ間で異なります。
**Example**
OpenTelemetry 計測ライブラリは、 `gen_ai.operation.name` 属性を使用してスパンを分類します。
| スパンタイプ | 属性の識別 |
| --- | --- |
| エージェントを呼び出す | `gen_ai.operation.name` = `invoke_agent` |
| 実行ツール | `gen_ai.operation.name` = `execute_tool` |
| 推測 | `gen_ai.operation.name` = `chat` |
OpenAI エージェントは、 `gen_ai.operation.name` = の内部ターン境界スパンも出力します`unknown`。評価サービスはこれらをスキップします。
OpenInference 計測ライブラリは、 `openinference.span.kind` 属性を使用してスパンを分類します。
| スパンタイプ | 属性の識別 |
| --- | --- |
| エージェントを呼び出す | `openinference.span.kind` = `AGENT`または `CHAIN` |
| 実行ツール | `openinference.span.kind` = `TOOL` |
| 推測 | `openinference.span.kind` = `LLM` |
OpenInference ライブラリでは、 `AGENT` と `CHAIN`スパンは空の構造コンテナであり、会話コンテンツを持ちません。ユーザープロンプトとエージェントのレスポンスは、同じトレース内の推論 (`LLM`) スパンから再構築されます。
## 評価フィールドの抽出方法
OpenAI エージェントは、メッセージをパートベースの形式でシリアル化します。各メッセージには、型付きコンテンツブロックの`parts`配列 (例: ) が格納されます`[{"role": "user", "parts": [{"type": "text", "content": "…"}]}]`。OpenTelemetry ライブラリを使用すると、AgentCore Evaluations はこれらの部分からテキストを解析します。OpenInference ライブラリでは、モデル出力は完全な OpenAI Response オブジェクトであり、AgentCore Evaluations は からレスポンステキストを読み取ります`output[].content[].text`。
このコンテンツの場所は、テレメトリの収集方法によって異なります。どちらの場合も、識別属性 (`gen_ai.operation.name` または `openinference.span.kind`) はスパン上にあります。詳細については、[「スパン、イベントレコード、テレメトリシグナル](supported-frameworks-telemetry.md)」を参照してください。
### イベントレコードから
テレメトリが分割されると、AgentCore Evaluations は各スパンに相関するイベントレコードから会話コンテンツを読み取ります。ツールの入力と出力の場所は、2 つのライブラリによって異なります。
+ **OpenTelemetry**:
+ **ユーザープロンプト**と**エージェントのレスポンス**: エージェントスパンのイベントレコードの呼び出しから、 `body.input`および 。 `body.output`
+ **ツール呼び出し**: のツール名`gen_ai.tool.name`、および`gen_ai.tool.call.result`実行ツールスパンの引数`gen_ai.tool.call.arguments`と結果。OpenTelemetry ライブラリでは、テレメトリが分割されていても、ツールの引数と結果はスパン属性に残ります。
+ **OpenInference**:
+ **ユーザープロンプト**と**エージェントのレスポンス**: 推論スパンのイベントレコードから再構築されました。AgentCore Evaluations は `body.input`と からメッセージを読み取り`body.output`、空の呼び出しエージェントスパンをユーザープロンプトとエージェントレスポンスでバックフィルします。
+ **ツール呼び出し**: 実行ツールスパン`tool.name`の からのツール名。ツールの引数と結果は、 `body.input`と のスパンのイベントレコードから取得されます`body.output`。
例については、[「イベントレコードを含むスパンの例](#openai-agents-examples-with)」を参照してください。
### スパン属性から
テレメトリが分割されていない場合、同じコンテンツは属性と同じスパンに残ります。属性は、計測ライブラリによって異なります。
+ **OpenTelemetry**:
+ **ユーザープロンプト**と**エージェントのレスポンス**: `gen_ai.input.messages` `gen_ai.output.messages` 呼び出しエージェントのスパンとの間で。
+ **ツール呼び出し**: 実行ツールスパン`gen_ai.tool.call.result`の からのツール名`gen_ai.tool.name`、および `gen_ai.tool.call.arguments`と からの引数と結果。
+ **OpenInference**:
+ **ユーザープロンプト**と**エージェントのレスポンス**: 推論スパン (`llm.input_messages. ` および `llm.output_messages.`) のインデックス付きメッセージ属性から、空の呼び出しエージェントスパンにバックフィルされます。
+ **ツール呼び出し**: 実行ツールスパン`output.value`の からのツール名`tool.name`、および `input.value`と からの引数と結果。
例については、[「イベントレコードのないスパンの例](#openai-agents-examples-without)」を参照してください。
## イベントレコードを含むスパンの例
テレメトリが分割されると、スパンは識別属性を保持し、コンテンツは相関イベントレコードに存在します。次の例は、Amazon Bedrock AgentCore ランタイムにデプロイされた OpenAI Agents の旅行計画エージェントからのものです。 AgentCore 各計測ライブラリの下に同じエージェントが表示されます。
**注記**
これらの例は完全なスパンではありません。実際のエージェントインタラクションからの代表的なデータが表示され、読みやすいように一部のフィールドは省略され、長い値は切り捨てられます。
### OpenTelemetry
**Example**
`gen_ai.operation.name` 属性 (`invoke_agent`) は、これを呼び出しエージェントのスパンとして識別します。
```
{
"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"
}
}
```
相関イベントレコードは会話を保持します。各メッセージの `content`は OpenAI parts-format 配列です。ユーザープロンプトはユーザーメッセージのテキスト、エージェントのレスポンスはアシスタントメッセージのテキストです。
```
{
"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` 属性 (`execute_tool`) は、これを実行ツールスパンとして識別します。 はツール名`gen_ai.tool.name`を保持します。OpenTelemetry ライブラリでは、テレメトリが分割されていても、ツールの引数と結果はスパン属性に残ります。
```
{
"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` 属性 (`chat`) は、これを推論スパンとして識別します。このスパンには、モデルメタデータと、 でエージェントが使用できるツール`gen_ai.tool.definitions`のリストが含まれます。モデル呼び出しの会話メッセージは、 `body.input`と の相関イベントレコードにライブ表示されます`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
OpenInference ライブラリでは、呼び出しエージェント (`AGENT`) スパンは空のコンテナです。AgentCore Evaluations は、コンテンツが相関イベントレコードに存在する推論 (`LLM`) スパンからユーザープロンプトとエージェントレスポンスを再構築します。
**Example**
`openinference.span.kind` 属性 (`AGENT`) は、これを呼び出しエージェントのスパンとして識別します。スパンには会話コンテンツはありません。
```
{
"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` 属性 (`TOOL`) は、これを実行ツールスパンとして識別します。 はツール名`tool.name`を保持します。ツールの引数と結果は、相関イベントレコードに残ります。
```
{
"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` 属性 (`LLM`) は、これを推論スパンとして識別します。メッセージロールとツール定義はスパン属性にあり、メッセージコンテンツは相関イベントレコードに存在します。ADOT は入力ロールを にフラット化するため`user`、AgentCore Evaluations はユーザープロンプトとして最後のプレーンテキストの入力メッセージを使用します。出力メッセージは OpenAI Response オブジェクトで、そこから AgentCore Evaluations がレスポンステキストを読み取ります。
```
{
"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 ...\"}]}]}"
}
]
}
}
}
```
## イベントレコードのないスパンの例
テレメトリが分割されていない場合、同じコンテンツはスパン属性に残り、個別のイベントレコードは生成されません。次の例は、OpenAI Agents の旅行計画エージェントからのものです。各計測ライブラリの下に同じエージェントが表示されます。
**注記**
これらの例は完全なスパンではありません。実際のエージェントインタラクションからの代表的なデータが表示され、読みやすいように一部のフィールドは省略され、長い値は切り捨てられます。
### OpenTelemetry
**Example**
`gen_ai.input.messages` 属性はユーザープロンプトを保持し、 `gen_ai.output.messages` 属性はエージェントのレスポンスを保持します。どちらも OpenAI parts-format 配列です。
```
{
"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` 属性はツール引数を保持し、 `gen_ai.tool.call.result` 属性はツールの結果を保持します。
```
{
"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` 属性 (`chat`) は、これを推論スパンとして識別します。モデルメタデータと `gen_ai.tool.definitions` 属性 (エージェントが使用できるツールのリスト) は、スパンでインラインに保持されます。
```
{
"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` 属性はツール引数を保持し、 `output.value` 属性はツールの結果を保持します。
```
{
"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"
}
}
```
メッセージの内容は、インデックス付き属性でインラインです。`llm.input_messages. ` 属性はシステムプロンプトとユーザープロンプトを保持し、`llm.output_messages.`属性はエージェントのレスポンスを保持します。AgentCore Evaluations は、このスパンからユーザープロンプトとエージェントレスポンスを再構築し、空の呼び出しエージェント (`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"
}
}
```