Instrumen agen Anda Bagaimana rentang diidentifikasi Bagaimana bidang evaluasi diekstraksi Contoh membentang dengan catatan acara Contoh membentang tanpa catatan peristiwa Praktik terbaik untuk LlamaIndex agen

LlamaIndex

Halaman ini menjelaskan cara instrumen LlamaIndexagen, bagaimana rentang diidentifikasi, dan bagaimana bidang evaluasi diekstraksi. Ini ditutup dengan praktik terbaik untuk penataan LlamaIndex agen sehingga dapat dievaluasi dengan andal.

Topik

Instrumen agen Anda
Bagaimana rentang diidentifikasi
Bagaimana bidang evaluasi diekstraksi
- Dari catatan acara
- Dari atribut span
Contoh membentang dengan catatan acara
Contoh membentang tanpa catatan peristiwa
Praktik terbaik untuk LlamaIndex agen

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.

contoh

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. traceloop.span.kind Karena LlamaIndex menandai operasi inferensi dan alat sebagaitask, 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)

OpenInference

Pustaka OpenInference instrumentasi mengklasifikasikan rentang menggunakan atribut. openinference.span.kind LlamaIndex memancarkanCHAIN,LLM, dan TOOL membentang; itu tidak memancarkan AGENT bentang. Rentang alur kerja root (aCHAIN) 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`

catatan

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 bentukThought: … Answer: <response>, AgentCore Evaluasi mengekstrak teks Answer: setelahnya sebagai respons agen.

Lokasi konten ini tergantung pada bagaimana telemetri dikumpulkan. Atribut pengidentifikasi (traceloop.span.kindatauopeninference.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 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.

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.

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

contoh

Invoke agent span

traceloop.span.kindAtribut (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"
  }
}

Execute tool span

traceloop.span.kindAtribut (task) dengan traceloop.entity.name akhiran Tool.task mengidentifikasi ini sebagai rentang alat eksekusi. Catatan peristiwa yang berkorelasi membawa argumen alat (dibungkuskwargs) dan hasil alat (dibungkusblocks), 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\"}" }
      ]
    }
  }
}

Inference span

traceloop.span.kindAtribut (task), dengan a traceloop.entity.name yang tidak berakhirTool.task, mengidentifikasi ini sebagai rentang inferensi. LlamaIndex Agen menghasilkan beberapa bentang ini per giliran. Di masing-masing, konten dikemas ke dalam body.output (tidak adabody.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 bersaranginput.


{
  "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 bersarangresult.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

contoh

Invoke agent span

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

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, 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\"}" }
      ]
    }
  }
}

Inference span

openinference.span.kindAtribut (LLM) mengidentifikasi ini sebagai rentang inferensi. Peran pesan ada pada atribut rentang; konten hidup dalam catatan peristiwa yang berkorelasi. ADOT meratakan peran inputuser, 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

contoh

OpenInference

contoh

Execute tool span

input.valueAtribut memegang argumen alat (dibungkuskwargs), dan output.value atribut memegang hasil alat (dibungkusblocks).


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

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 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 atauFunctionAgent) 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.

Awas Javascript dinonaktifkan atau tidak tersedia di browser Anda.

Untuk menggunakan Dokumentasi AWS, Javascript harus diaktifkan. Lihat halaman Bantuan browser Anda untuk petunjuk.

Konvensi Dokumen

Agen OpenAI

Google ADK