# LlamaIndex
このページでは、[LlamaIndex](https://docs.llamaindex.ai/) エージェントを計測する方法、スパンの識別方法、評価フィールドの抽出方法について説明します。LlamaIndex エージェントを確実に評価できるように、LlamaIndex エージェントを構造化するための[ベストプラクティス](#llamaindex-best-practices)で終了します。
**トピック**
+ [エージェントを計測する](#llamaindex-instrument)
+ [スパンの識別方法](#llamaindex-span-identification)
+ [評価フィールドの抽出方法](#llamaindex-extraction)
+ [イベントレコードから](#llamaindex-extraction-event-records)
+ [スパン属性から](#llamaindex-extraction-attributes)
+ [イベントレコードを含むスパンの例](#llamaindex-examples-with)
+ [イベントレコードのないスパンの例](#llamaindex-examples-without)
+ [LlamaIndex エージェントのベストプラクティス](#llamaindex-best-practices)
## エージェントを計測する
**OpenTelemetry** (`opentelemetry-instrumentation-llamaindex`) または **OpenInference** () の 2 つの計測ライブラリのいずれかを使用して、LlamaIndex エージェントを計測できます`openinference-instrumentation-llama-index`。Amazon Bedrock AgentCore Evaluations は両方のライブラリをサポートしています。ライブラリは異なるスコープ名を出力し、異なるスパン属性を使用します。評価サービスは、それぞれから同じ値を抽出します。
Amazon Bedrock AgentCore ランタイムなど、エージェントが AWS Distro for OpenTelemetry (ADOT) で実行されている場合、明示的な計測コードを追加する必要はありません。計測ライブラリをプロジェクトの依存関係に追加するだけで十分です。ADOT は起動時に検出し、自動的にアクティブ化します。
依存関係に必要なパスの計測ライブラリを追加します。ピン留めする理由がない限り、利用可能な最新バージョンを使用してください。
**Example**
注: バージョン `0.61.0` 以降を使用します。これは、評価サービスでテストされた最も古いバージョンです。
`opentelemetry-instrumentation-llamaindex` を依存関係に追加します。出力されるスコープ名は です`opentelemetry.instrumentation.llamaindex`。
`requirements.txt`:
```
opentelemetry-instrumentation-llamaindex>=0.61.0
```
`pyproject.toml`:
```
[project]
dependencies = [
"opentelemetry-instrumentation-llamaindex>=0.61.0",
]
```
注: バージョン `4.4.1` 以降を使用します。これは、評価サービスでテストされた最も古いバージョンです。
`openinference-instrumentation-llama-index` を依存関係に追加します。出力されるスコープ名は です`openinference.instrumentation.llama_index`。
`requirements.txt`:
```
openinference-instrumentation-llama-index>=4.4.1
```
`pyproject.toml`:
```
[project]
dependencies = [
"openinference-instrumentation-llama-index>=4.4.1",
]
```
**注記**
計測は、オブザーバビリティを設定する 1 つのステップです。評価のためにテレメトリをエクスポートするには、[「オブザーバビリティの設定](supported-frameworks.md#supported-frameworks-setup)」で完全なセットアップを完了します。
## スパンの識別方法
スパンの分類に使用される属性は、2 つの計測ライブラリによって異なります。
**Example**
OpenTelemetry 計測ライブラリは、 `traceloop.span.kind` 属性を使用してスパンを分類します。LlamaIndex は推論オペレーションとツールオペレーションの両方を としてタグ付けするため`task`、AgentCore Evaluations は`traceloop.entity.name`それらを 属性で曖昧さを解消します。`task`エンティティ名が で終わる `Tool.task`は実行ツールスパンで、その他のものは推論スパン`task`です。
| スパンタイプ | 属性の識別 |
| --- | --- |
| エージェントを呼び出す | `traceloop.span.kind` = `workflow` |
| 実行ツール | `traceloop.span.kind` = `tool`、または `traceloop.span.kind` = `task` `traceloop.entity.name` で終わる `Tool.task` |
| 推測 | `traceloop.span.kind` = `task` (ツールタスクではない) |
OpenInference 計測ライブラリは、 `openinference.span.kind` 属性を使用してスパンを分類します。LlamaIndex は `CHAIN`、`LLM`、および `TOOL`スパンを出力します。`AGENT`スパンは出力しません。ルートワークフロースパン (`CHAIN`) は、呼び出しエージェントのスパンとして機能します。
| スパンタイプ | 属性の識別 |
| --- | --- |
| エージェントを呼び出す | `openinference.span.kind` = `CHAIN` (ルートワークフロースパン) |
| 実行ツール | `openinference.span.kind` = `TOOL` |
| 推測 | `openinference.span.kind` = `LLM` |
LlamaIndex は、複数の中間`CHAIN`スパン (出力解析やツールルーティングなど) を出力します。AgentCore Evaluations は、ルートワークフロースパンのみを呼び出しエージェントスパンとして扱い、トレースの推論 (`LLM`) スパンからユーザープロンプトとエージェントレスポンスを再構築します。
## 評価フィールドの抽出方法
LlamaIndex エージェントは**ワークフロー**であり、最上位のスパンは子スパンの前に出力されます。このワークフロースパンには独自の使用可能な会話コンテンツがないため、AgentCore Evaluations は子スパン (推論とツールスパン) からユーザープロンプトとエージェントレスポンスを再構築し、呼び出しエージェントスパンにアタッチします。
LlamaIndex は、ネストされた JSON としてコンテンツをシリアル化します。ツール引数は としてラップされ`{"kwargs": {…}}`、ツールの結果は としてラップされます`{"blocks": [{"text": "…"}], …}`。AgentCore Evaluations は、これらのフォームをラップ解除します。LlamaIndex ReAct エージェントが 形式で出力を生成すると`Thought: … Answer: `、AgentCore Evaluations はエージェントのレスポンス`Answer:`として の後にテキストを抽出します。
このコンテンツの場所は、テレメトリの収集方法によって異なります。どちらの場合も、識別属性 (`traceloop.span.kind` または `openinference.span.kind`) はスパン上にあります。詳細については、[「スパン、イベントレコード、テレメトリシグナル](supported-frameworks-telemetry.md)」を参照してください。
### イベントレコードから
テレメトリが分割されると、AgentCore Evaluations は各スパンに相関するイベントレコードからコンテンツを読み取ります。
+ **ユーザープロンプト**と**エージェントのレスポンス**: の推論スパンのイベントレコードから再構築されました`body.output`。OpenTelemetry ライブラリでは、ユーザープロンプトはチャット履歴コンテンツから、エージェントレスポンスはモデル結果コンテンツから取得されます。OpenInference ライブラリでは、ユーザープロンプトはプレーンテキストの入力メッセージで、エージェントのレスポンスはモデル出力 (ReAct エージェント`Answer:`に使用した後のテキストを含む) です。 ReAct
+ **ツール呼び出し**: 実行ツールスパンのツール名。ツールの引数と結果は、 ( からラップ解除) と `body.input` ( からラップ`body.output`解除`{"kwargs": {…}}`) で、そのスパンのイベントレコードから取得されます`{"blocks": […]}`。
例については、[「イベントレコードを含むスパンの例](#llamaindex-examples-with)」を参照してください。
### スパン属性から
テレメトリが分割されていない場合、同じコンテンツは属性と同じスパンに残ります。属性は、計測ライブラリによって異なります。
+ **OpenTelemetry**: コンテンツは各スパンの `traceloop.entity.input`および `traceloop.entity.output` 属性にあります。AgentCore Evaluations は、同じチャット履歴、結果、ツールのラップ解除をこれらの値に適用します。
+ **OpenInference**: 推論コンテンツは、インデックス付きメッセージ属性 (`llm.input_messages. ` および ) にあります`llm.output_messages.`。ツール引数は から取得され `input.value` ( からラップ解除`{"kwargs": {…}}`)、ツールの結果は から取得されます `output.value` ( からラップ解除)`{"blocks": […]}`。
例については、[「イベントレコードのないスパンの例](#llamaindex-examples-without)」を参照してください。
## イベントレコードを含むスパンの例
テレメトリが分割されると、スパンは識別属性を保持し、コンテンツは相関イベントレコードに存在します。次の例は、Amazon Bedrock AgentCore ランタイムにデプロイされた LlamaIndex ReAct の旅行計画エージェントからのものです。各計測ライブラリの下に同じエージェントが表示されます。
**注記**
これらの例は完全なスパンではありません。実際のエージェントインタラクションからの代表的なデータが表示され、読みやすいように一部のフィールドは省略され、長い値は切り捨てられます。
### OpenTelemetry
**Example**
`traceloop.span.kind` 属性 (`workflow`) は、これを呼び出しエージェントのスパンとして識別します。ワークフロースパンには会話コンテンツはありません。AgentCore Evaluations は、子スパンからユーザープロンプトとエージェントレスポンスを再構築します。
```
{
"traceId": "6a01eef11066751d68f90def0da1f80a",
"spanId": "ba1833fa7f097041",
"name": "ReActAgent.workflow",
"kind": "INTERNAL",
"scope": {
"name": "opentelemetry.instrumentation.llamaindex",
"version": "0.61.0"
},
"attributes": {
"traceloop.span.kind": "workflow",
"traceloop.entity.name": "ReActAgent.workflow",
"session.id": "sea-nyc-trip-2-turns-llamaindex-otel"
},
"status": {
"code": "OK"
}
}
```
末尾が の`traceloop.span.kind`属性 (`task`) `traceloop.entity.name` は、これを実行ツールスパンとして`Tool.task`識別します。相関イベントレコードには、ツールの引数 ( でラップ`kwargs`) とツールの結果 ( でラップ`blocks`) が、ツール名とともに保持されます。
```
{
"traceId": "6a01eefa5c52f3d86a35038f35f5ba30",
"spanId": "5b332f3cd15ace04",
"name": "FunctionTool.task",
"kind": "INTERNAL",
"scope": {
"name": "opentelemetry.instrumentation.llamaindex",
"version": "0.61.0"
},
"attributes": {
"traceloop.span.kind": "task",
"traceloop.entity.name": "FunctionTool.task",
"session.id": "sea-nyc-trip-2-turns-llamaindex-otel"
},
"status": {
"code": "OK"
}
}
```
```
{
"spanId": "5b332f3cd15ace04",
"traceId": "6a01eefa5c52f3d86a35038f35f5ba30",
"scope": {
"name": "opentelemetry.instrumentation.llamaindex"
},
"body": {
"input": {
"messages": [
{ "role": "user", "content": "{\"kwargs\": {\"origin\": \"SEA\", \"destination\": \"NYC\", \"date\": \"2025-03-15\"}}" }
]
},
"output": {
"messages": [
{ "content": "{\"blocks\": [{\"block_type\": \"text\", \"text\": \"{\\\"origin\\\": \\\"SEA\\\", \\\"destination\\\": \\\"NYC\\\", \\\"flights\\\": [ ... ]}\"}], \"tool_name\": \"search_flights\"}" }
]
}
}
}
```
`traceloop.span.kind` 属性 (`task`) `traceloop.entity.name`は、 で終わることのない で`Tool.task`、これを推論スパンとして識別します。LlamaIndex エージェントは、ターンごとにこれらのスパンのいくつかを生成します。各コンテンツは、シリアル化された JSON 文字列として にまとめられます `body.output` ( はありません`body.input`)。AgentCore Evaluations は、最初の推論スパンの chat-history 文字列 (`{"input": […]}`オブジェクト) から**ユーザープロンプト**を読み取り、最後の推論スパンのモデル結果文字列 (`{"result": {"response": …}}`オブジェクト) から**エージェントレスポンス**を読み取ります。
以下は、推論スパン自体です。
```
{
"traceId": "6a01eef11066751d68f90def0da1f80a",
"spanId": "d9a1f0c7b3e64a20",
"name": "BaseWorkflowAgent.task",
"kind": "INTERNAL",
"scope": {
"name": "opentelemetry.instrumentation.llamaindex",
"version": "0.61.0"
},
"attributes": {
"traceloop.span.kind": "task",
"traceloop.entity.name": "BaseWorkflowAgent.task",
"session.id": "sea-nyc-trip-2-turns-llamaindex-otel"
},
"status": {
"code": "OK"
}
}
```
最初の推論スパンでは、イベントレコードの`body.output`コンテンツはチャット履歴です。ユーザープロンプトは、ネストされた`input`配列内の `user`ロールテキストです。
```
{
"spanId": "d9a1f0c7b3e64a20",
"traceId": "6a01eef11066751d68f90def0da1f80a",
"scope": {
"name": "opentelemetry.instrumentation.llamaindex"
},
"body": {
"output": {
"messages": [
{
"content": "{\"input\": [{\"role\": \"user\", \"blocks\": [{\"block_type\": \"text\", \"text\": \"Hey, how can you help me\"}]}], \"current_agent_name\": \"Agent\"}"
}
]
}
}
}
```
最後の推論スパンでは、イベントレコードの`body.output`コンテンツがモデル結果になります。エージェントレスポンスは、ネストされた`result.response`オブジェクト内の `assistant`ロールテキストです。
```
{
"spanId": "826bc829697a9610",
"traceId": "6a01eef11066751d68f90def0da1f80a",
"scope": {
"name": "opentelemetry.instrumentation.llamaindex"
},
"body": {
"output": {
"messages": [
{
"content": "{\"result\": {\"response\": {\"role\": \"assistant\", \"blocks\": [{\"block_type\": \"text\", \"text\": \"Here are the available flights from Seattle to New York City ...\"}]}}, \"current_agent_name\": \"Agent\"}"
}
]
}
}
}
```
### OpenInference
**Example**
ルートワークフロースパンの`openinference.span.kind`属性 (`CHAIN`) は、これを呼び出しエージェントのスパンとして識別します。スパンには使用可能な会話コンテンツはありません。AgentCore Evaluations は、推論スパンからユーザープロンプトとエージェントレスポンスを再構築します。
```
{
"traceId": "6a387ee61078243c1cc455ed45c6c313",
"spanId": "0a7990d804132a9b",
"name": "ReActAgent.run",
"kind": "INTERNAL",
"scope": {
"name": "openinference.instrumentation.llama_index",
"version": "4.4.1"
},
"attributes": {
"openinference.span.kind": "CHAIN",
"input.mime_type": "application/json",
"output.mime_type": "text/plain",
"session.id": "sea-nyc-trip-2-turns-llamaindex-oi"
},
"status": {
"code": "OK"
}
}
```
`openinference.span.kind` 属性 (`TOOL`) は、これを実行ツールスパンとして識別します。 はツール名`tool.name`を保持します。ツール引数と結果は、相関イベントレコードに`blocks`それぞれ `kwargs`と でラップされます。
```
{
"traceId": "6a387ef07b8f4f3732fab45d3c0b51ff",
"spanId": "ab105c12cc40048f",
"name": "FunctionTool.acall",
"kind": "INTERNAL",
"scope": {
"name": "openinference.instrumentation.llama_index",
"version": "4.4.1"
},
"attributes": {
"openinference.span.kind": "TOOL",
"tool.name": "search_flights",
"tool.description": "search_flights(origin: str, destination: str, date: str) -> str ...",
"session.id": "sea-nyc-trip-2-turns-llamaindex-oi"
},
"status": {
"code": "OK"
}
}
```
```
{
"spanId": "ab105c12cc40048f",
"traceId": "6a387ef07b8f4f3732fab45d3c0b51ff",
"scope": {
"name": "openinference.instrumentation.llama_index"
},
"body": {
"input": {
"messages": [
{ "content": "{\"kwargs\": {\"origin\": \"SEA\", \"destination\": \"NYC\", \"date\": \"2025-03-15\"}}" }
]
},
"output": {
"messages": [
{ "content": "{\"blocks\": [{\"text\": \"{\\\"origin\\\": \\\"SEA\\\", \\\"destination\\\": \\\"NYC\\\", \\\"flights\\\": [ ... ]}\"}], \"tool_name\": \"search_flights\"}" }
]
}
}
}
```
`openinference.span.kind` 属性 (`LLM`) は、これを推論スパンとして識別します。メッセージロールはスパン属性にあり、コンテンツは相関イベントレコードに存在します。ADOT は入力ロールを にフラット化するため`user`、AgentCore Evaluations はユーザープロンプトとして最後のプレーンテキストの入力メッセージを使用します。LlamaIndex は、重複する`assistant:`プレフィックス付きの出力メッセージを発行します。このメッセージは AgentCore Evaluations がスキップし、クリーンコピーを優先します。
```
{
"traceId": "6a387ee61078243c1cc455ed45c6c313",
"spanId": "1221a062c7f90a8e",
"name": "OpenAI.astream_chat",
"kind": "INTERNAL",
"scope": {
"name": "openinference.instrumentation.llama_index",
"version": "4.4.1"
},
"attributes": {
"openinference.span.kind": "LLM",
"llm.system": "openai",
"llm.model_name": "gpt-4o-mini",
"llm.input_messages.0.message.role": "system",
"llm.input_messages.1.message.role": "user",
"llm.output_messages.0.message.role": "assistant",
"session.id": "sea-nyc-trip-2-turns-llamaindex-oi"
},
"status": {
"code": "OK"
}
}
```
```
{
"spanId": "1221a062c7f90a8e",
"traceId": "6a387ee61078243c1cc455ed45c6c313",
"scope": {
"name": "openinference.instrumentation.llama_index"
},
"body": {
"input": {
"messages": [
{ "role": "user", "content": "{\"messages\": [ ... ]}" },
{ "role": "user", "content": "You are designed to help with a variety of tasks ..." },
{ "role": "user", "content": "Hey, how can you help me" }
]
},
"output": {
"messages": [
{ "role": "assistant", "content": "assistant: Thought: ... Answer: I can help you plan your trip ..." },
{ "role": "assistant", "content": "Thought: ... Answer: I can help you plan your trip ..." }
]
}
}
}
```
## イベントレコードのないスパンの例
テレメトリが分割されていない場合、同じコンテンツはスパン属性に残り、個別のイベントレコードは生成されません。次の例は、LlamaIndex ReAct の旅行計画エージェントからのものです。各計測ライブラリの下に同じエージェントが表示されます。
**注記**
これらの例は完全なスパンではありません。実際のエージェントインタラクションからの代表的なデータが表示され、読みやすいように一部のフィールドは省略され、長い値は切り捨てられます。
### OpenTelemetry
**Example**
`traceloop.entity.input` 属性はツール引数を保持し ( でラップ`kwargs`)、 `traceloop.entity.output` 属性はツールの結果を保持します ( でラップ)`blocks`。
```
{
"traceId": "6a4de7c376913db82e6f0f336a16731d",
"spanId": "b64c37adefae74f0",
"name": "FunctionTool.task",
"kind": "INTERNAL",
"scope": {
"name": "opentelemetry.instrumentation.llamaindex",
"version": "0.61.0"
},
"attributes": {
"traceloop.span.kind": "task",
"traceloop.entity.name": "FunctionTool.task",
"traceloop.entity.input": "{\"kwargs\": {\"origin\": \"SEA\", \"destination\": \"NYC\", \"date\": \"2025-03-15\"}}",
"traceloop.entity.output": "{\"blocks\": [{\"block_type\": \"text\", \"text\": \"{\\\"origin\\\": \\\"SEA\\\", \\\"flights\\\": [ ... ]}\"}], \"tool_name\": \"search_flights\"}",
"session.id": "sea-nyc-trip-2-turns-unified"
},
"status": {
"code": "OK"
}
}
```
`traceloop.entity.output` 属性には、AgentCore Evaluations がユーザープロンプトを読み取るチャット履歴が保持されます。レスポンスは、最後の推論スパンのモデル結果から取得されます。
```
{
"traceId": "6a4de7b85e61747e6b568a1f4768e89d",
"spanId": "31ea3d5882dac680",
"name": "BaseWorkflowAgent.task",
"kind": "INTERNAL",
"scope": {
"name": "opentelemetry.instrumentation.llamaindex",
"version": "0.61.0"
},
"attributes": {
"traceloop.span.kind": "task",
"traceloop.entity.name": "BaseWorkflowAgent.task",
"traceloop.entity.output": "{\"input\": [{\"role\": \"user\", \"blocks\": [{\"block_type\": \"text\", \"text\": \"Hey, how can you help me\"}]}], \"current_agent_name\": \"Agent\"}",
"session.id": "sea-nyc-trip-2-turns-unified"
},
"status": {
"code": "OK"
}
}
```
### OpenInference
**Example**
`input.value` 属性はツール引数を保持し ( でラップ`kwargs`)、 `output.value` 属性はツールの結果を保持します ( でラップ)`blocks`。
```
{
"traceId": "6a387ef07b8f4f3732fab45d3c0b51ff",
"spanId": "d5a1c9e70b46f312",
"name": "FunctionTool.acall",
"kind": "INTERNAL",
"scope": {
"name": "openinference.instrumentation.llama_index",
"version": "4.4.2"
},
"attributes": {
"openinference.span.kind": "TOOL",
"tool.name": "search_flights",
"input.value": "{\"kwargs\": {\"origin\": \"SEA\", \"destination\": \"NYC\", \"date\": \"2025-03-15\"}}",
"output.value": "{\"blocks\": [{\"text\": \"{\\\"origin\\\": \\\"SEA\\\", \\\"flights\\\": [ ... ]}\"}], \"tool_name\": \"search_flights\"}",
"session.id": "sea-nyc-trip-2-turns-oi"
},
"status": {
"code": "OK"
}
}
```
メッセージの内容は、インデックス付き属性でインラインです。`llm.input_messages. ` 属性はシステムプロンプトとユーザープロンプトを保持し、`llm.output_messages.`属性はモデル出力を保持し、AgentCore評価はエージェントのレスポンス`Answer:`として の後にテキストを抽出します。
```
{
"traceId": "6a387ee61078243c1cc455ed45c6c313",
"spanId": "c9f0a2b41d773e88",
"name": "OpenAI.astream_chat",
"kind": "INTERNAL",
"scope": {
"name": "openinference.instrumentation.llama_index",
"version": "4.4.2"
},
"attributes": {
"openinference.span.kind": "LLM",
"llm.model_name": "gpt-4o-mini",
"llm.input_messages.0.message.role": "system",
"llm.input_messages.0.message.content": "You are designed to help with a variety of tasks ...",
"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.content": "Thought: ... Answer: I can help you plan your trip ...",
"session.id": "sea-nyc-trip-2-turns-oi"
},
"status": {
"code": "OK"
}
}
```
## LlamaIndex エージェントのベストプラクティス
LlamaIndex エージェントを構築して呼び出す方法は、テレメトリに表示される内容、つまりエージェントの評価の信頼性に影響します。以下のプラクティスは、ユーザープロンプト、エージェントのレスポンス、ツールアクティビティを回復可能にするのに役立ちます。
+ **LlamaIndex エージェントワークフローを使用します。**エージェントを LlamaIndex エージェントワークフロー ( `ReActAgent`や など`FunctionAgent`) として構築し、フレームワークが推論とツールの子スパンを含む最上位ワークフロースパンを出力できるようにします。AgentCore Evaluations は、これらの子スパンから呼び出しエージェントスパンを再構築します。
+ **ツールを`FunctionTool`オブジェクトとして登録します。**各ツールを LlamaIndex として定義します (または、LlamaIndex を生成する `@tool`スタイルのヘルパーを使用します）。 `FunctionTool`ツールスパンはエンティティ名で識別され、引数と結果は でシリアル化`kwargs`され、 `blocks`構造 AgentCore Evaluations がラップ解除します。
+ **ツールの結果をテキストシリアル化可能に保ちます。**ツールの結果を文字列または JSON シリアル化可能な値として返します。LlamaIndex はそれらをテキストブロックにラップします。シリアル化可能な状態にしておくと、ツールの結果がクリーンにキャプチャされます。
+ **ReAct エージェントの場合は、標準の出力形式を使用します。**AgentCore Evaluations は、ReAct エージェントの出力の `Answer:`セクションから最終的な回答を抽出します。標準の ReAct プロンプト (LlamaIndex のデフォルト) を使用すると、エージェントのレスポンスは回復可能になります。