# LlamaIndex Halaman ini menjelaskan cara instrumen [LlamaIndex](https://docs.llamaindex.ai/)agen, bagaimana rentang diidentifikasi, dan bagaimana bidang evaluasi diekstraksi. Ini ditutup dengan [praktik terbaik](#llamaindex-best-practices) untuk penataan LlamaIndex agen sehingga dapat dievaluasi dengan andal. **Topik** + [Instrumen agen Anda](#llamaindex-instrument) + [Bagaimana rentang diidentifikasi](#llamaindex-span-identification) + [Bagaimana bidang evaluasi diekstraksi](#llamaindex-extraction) + [Dari catatan acara](#llamaindex-extraction-event-records) + [Dari atribut span](#llamaindex-extraction-attributes) + [Contoh membentang dengan catatan acara](#llamaindex-examples-with) + [Contoh membentang tanpa catatan peristiwa](#llamaindex-examples-without) + [Praktik terbaik untuk LlamaIndex agen](#llamaindex-best-practices) ## Instrumen agen Anda Anda dapat menginstrumentasikan LlamaIndex agen dengan salah satu dari dua pustaka instrumentasi: **OpenTelemetry**(`opentelemetry-instrumentation-llamaindex`) atau **OpenInference**(`openinference-instrumentation-llama-index`). 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-llamaindex` ke dependensi Anda. Nama lingkup yang dipancarkan adalah. `opentelemetry.instrumentation.llamaindex` `requirements.txt`: ``` opentelemetry-instrumentation-llamaindex>=0.61.0 ``` `pyproject.toml`: ``` [project] dependencies = [ "opentelemetry-instrumentation-llamaindex>=0.61.0", ] ``` CATATAN: Gunakan versi `4.4.1` atau yang lebih baru. Ini adalah versi paling awal yang diuji dengan layanan evaluasi. Tambahkan `openinference-instrumentation-llama-index` ke dependensi Anda. Nama lingkup yang dipancarkan adalah. `openinference.instrumentation.llama_index` `requirements.txt`: ``` openinference-instrumentation-llama-index>=4.4.1 ``` `pyproject.toml`: ``` [project] dependencies = [ "openinference-instrumentation-llama-index>=4.4.1", ] ``` **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. `traceloop.span.kind` Karena LlamaIndex menandai operasi inferensi dan alat sebagai`task`, AgentCore Evaluasi mendisambiguasi mereka dengan `traceloop.entity.name` atribut: a `task` yang nama entitasnya berakhir `Tool.task` adalah rentang alat eksekusi; yang lainnya `task` adalah rentang inferensi. | Jenis rentang | Mengidentifikasi atribut | | --- | --- | | Memohon agen | `traceloop.span.kind` = `workflow` | | Jalankan alat | `traceloop.span.kind`=`tool`, atau `traceloop.span.kind` = `task` dengan `traceloop.entity.name` berakhiran `Tool.task` | | Inferensi | `traceloop.span.kind`= `task` (bukan tugas alat) | Pustaka OpenInference instrumentasi mengklasifikasikan rentang menggunakan atribut. `openinference.span.kind` LlamaIndex memancarkan`CHAIN`,`LLM`, dan `TOOL` membentang; itu tidak memancarkan `AGENT` bentang. Rentang alur kerja root (a`CHAIN`) bertindak sebagai rentang agen pemanggilan. | Jenis rentang | Mengidentifikasi atribut | | --- | --- | | Memohon agen | `openinference.span.kind`= `CHAIN` (rentang alur kerja root) | | Jalankan alat | `openinference.span.kind` = `TOOL` | | Inferensi | `openinference.span.kind` = `LLM` | LlamaIndex memancarkan beberapa `CHAIN` rentang menengah (misalnya, untuk penguraian keluaran dan perutean alat). AgentCore Evaluasi hanya memperlakukan rentang alur kerja root sebagai rentang agen pemanggilan dan merekonstruksi prompt pengguna dan respons agen dari rentang inferensi () `LLM` dalam jejak. ## Bagaimana bidang evaluasi diekstraksi LlamaIndex Agen adalah **alur kerja**, dan rentang tingkat atasnya dipancarkan sebelum rentang anaknya. Rentang alur kerja itu tidak membawa konten percakapan yang dapat digunakan sendiri, jadi AgentCore Evaluations merekonstruksi prompt pengguna dan respons agen dari rentang anak (inferensi dan rentang alat) dan menempelkannya ke rentang agen pemanggilan. LlamaIndex juga membuat serial konten sebagai JSON bersarang. Argumen alat dibungkus sebagai`{"kwargs": {…​}}`, dan hasil alat dibungkus sebagai`{"blocks": [{"text": "…​"}], …​}`. AgentCore Evaluasi membuka bentuk-bentuk ini. Ketika LlamaIndex ReAct agen menghasilkan output dalam bentuk`Thought: …​ Answer: `, AgentCore Evaluasi mengekstrak teks `Answer:` setelahnya sebagai respons agen. Lokasi konten ini tergantung pada bagaimana telemetri dikumpulkan. Atribut pengidentifikasi (`traceloop.span.kind`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 dari catatan peristiwa yang berkorelasi dengan setiap rentang: + **Prompt pengguna** dan **respons agen**: direkonstruksi dari catatan peristiwa rentang inferensi, di. `body.output` Dengan OpenTelemetry library, prompt pengguna berasal dari konten riwayat obrolan dan respons agen dari konten hasil model. Dengan OpenInference perpustakaan, prompt pengguna adalah pesan input teks biasa dan respons agen adalah keluaran model (dengan teks setelah `Answer:` digunakan untuk agen). ReAct + **Panggilan alat**: nama alat dari rentang alat eksekusi. Argumen dan hasil alat berasal dari catatan peristiwa rentang itu, di `body.input` (unwrapped from`{"kwargs": {…​}}`) dan `body.output` (unwrapped from`{"blocks": […​]}`). Sebagai contoh, lihat [Contoh bentang dengan catatan peristiwa](#llamaindex-examples-with). ### Dari atribut span Ketika telemetri tidak dibagi, konten yang sama tetap pada rentang sebagai atribut. Atribut tergantung pada pustaka instrumentasi: + **OpenTelemetry**: konten ada di `traceloop.entity.input` dan `traceloop.entity.output` atribut setiap rentang. AgentCore Evaluasi menerapkan riwayat obrolan, hasil, dan alat yang sama yang membuka bungkusnya ke nilai-nilai ini. + **OpenInference**: konten inferensi ada pada atribut pesan yang diindeks (`llm.input_messages. `dan). `llm.output_messages.` Argumen alat berasal dari `input.value` (dibuka dari`{"kwargs": {…​}}`) dan alat dihasilkan dari `output.value` (dibuka dari`{"blocks": […​]}`). Sebagai contoh, lihat [Contoh rentang tanpa catatan peristiwa](#llamaindex-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 LlamaIndex ReAct perencanaan perjalanan 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** `traceloop.span.kind`Atribut (`workflow`) mengidentifikasi ini sebagai rentang agen pemanggilan. Rentang alur kerja tidak membawa konten percakapan; AgentCore Evaluasi merekonstruksi prompt pengguna dan respons agen dari rentang anak. ``` { "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`Atribut (`task`) dengan `traceloop.entity.name` akhiran `Tool.task` mengidentifikasi ini sebagai rentang alat eksekusi. Catatan peristiwa yang berkorelasi membawa argumen alat (dibungkus`kwargs`) dan hasil alat (dibungkus`blocks`), bersama dengan nama alat. ``` { "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`Atribut (`task`), dengan a `traceloop.entity.name` yang tidak berakhir`Tool.task`, mengidentifikasi ini sebagai rentang inferensi. LlamaIndex Agen menghasilkan beberapa bentang ini per giliran. Di masing-masing, konten dikemas ke dalam `body.output` (tidak ada`body.input`), sebagai string JSON serial. AgentCore Evaluasi membaca **prompt pengguna** dari string riwayat obrolan (`{"input": […​]}`objek) pada rentang inferensi pertama, dan **respons agen** dari string hasil model (`{"result": {"response": …​}}`objek) pada rentang inferensi terakhir. Berikut ini adalah rentang inferensi itu sendiri. ``` { "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" } } ``` Pada rentang inferensi pertama, `body.output` konten rekaman acara adalah riwayat obrolan. Prompt pengguna adalah teks `user` -role di dalam array bersarang`input`. ``` { "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\"}" } ] } } } ``` Pada rentang inferensi terakhir, `body.output` konten catatan peristiwa adalah hasil model. Respons agen adalah teks `assistant` -role di dalam objek bersarang`result.response`. ``` { "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`Atribut (`CHAIN`) pada rentang alur kerja root mengidentifikasi ini sebagai rentang agen pemanggilan. Rentang tidak membawa konten percakapan yang dapat digunakan; AgentCore Evaluasi merekonstruksi prompt pengguna dan respons agen dari rentang inferensi. ``` { "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`Atribut (`TOOL`) mengidentifikasi ini sebagai rentang alat eksekusi; `tool.name` memegang nama alat. Argumen dan hasil alat hidup dalam catatan peristiwa yang berkorelasi, dibungkus `kwargs` dan `blocks` masing-masing. ``` { "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`Atribut (`LLM`) mengidentifikasi ini sebagai rentang inferensi. Peran pesan ada pada atribut rentang; konten hidup dalam catatan peristiwa yang berkorelasi. ADOT meratakan peran input`user`, sehingga AgentCore Evaluations menggunakan pesan input teks biasa terakhir sebagai prompt pengguna. LlamaIndex memancarkan pesan keluaran `assistant:` -prefixed duplikat, yang AgentCore dilewati Evaluasi demi salinan bersih. ``` { "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 ..." } ] } } } ``` ## 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 LlamaIndex ReAct perencanaan perjalanan. 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** `traceloop.entity.input`Atribut memegang argumen alat (dibungkus`kwargs`), dan `traceloop.entity.output` atribut memegang hasil alat (dibungkus`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`Atribut menyimpan riwayat obrolan, dari mana AgentCore Evaluasi membaca prompt pengguna. Respons berasal dari hasil model pada rentang inferensi terakhir. ``` { "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`Atribut memegang argumen alat (dibungkus`kwargs`), dan `output.value` atribut memegang hasil alat (dibungkus`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" } } ``` Konten pesan sebaris pada atribut yang diindeks. `llm.input_messages. `Atribut menahan prompt sistem dan prompt pengguna, dan `llm.output_messages.` atribut menahan keluaran model, dari mana AgentCore Evaluations mengekstrak teks `Answer:` setelahnya sebagai respons agen. ``` { "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" } } ``` ## Praktik terbaik untuk LlamaIndex agen Bagaimana Anda membangun dan memanggil LlamaIndex agen memengaruhi apa yang muncul dalam telemetrinya, dan oleh karena itu seberapa andal agen tersebut dapat dievaluasi. Praktik berikut membantu memastikan prompt pengguna, respons agen, dan aktivitas alat dapat dipulihkan. + **Gunakan alur kerja LlamaIndex agen.** Bangun agen Anda sebagai alur kerja LlamaIndex agen (misalnya, a `ReActAgent` atau`FunctionAgent`) sehingga kerangka kerja memancarkan rentang alur kerja tingkat atas dengan inferensi dan rentang anak alat. AgentCore Evaluasi merekonstruksi rentang agen pemanggilan dari rentang anak ini. + **Daftarkan alat sebagai `FunctionTool` objek.** Tentukan setiap alat sebagai LlamaIndex `FunctionTool` (atau gunakan `@tool` -style helper yang menghasilkan satu). Rentang alat diidentifikasi berdasarkan nama entitas mereka, dan argumen serta hasilnya diserialisasikan dalam `kwargs` dan `blocks` struktur AgentCore Evaluasi dibuka. + **Jaga agar hasil alat dapat diserialkan teks.** Kembalikan hasil alat sebagai string atau JSON-serializable nilai. LlamaIndex membungkusnya dalam blok teks; menjaganya agar dapat diserialkan memastikan hasil alat ditangkap dengan bersih. + **Untuk ReAct agen, gunakan format output standar.** AgentCore Evaluasi mengekstrak jawaban akhir dari `Answer:` bagian output ReAct agen. Menggunakan ReAct prompt standar ( LlamaIndex default) membuat respons agen dapat dipulihkan.