# LlamaIndex Questa pagina spiega come strumentare un [LlamaIndex](https://docs.llamaindex.ai/)agente, come vengono identificati gli intervalli e come vengono estratti i campi di valutazione. Si chiude con le [migliori pratiche](#llamaindex-best-practices) per strutturare un LlamaIndex agente in modo che possa essere valutato in modo affidabile. **Argomenti** + [Strumenta il tuo agente](#llamaindex-instrument) + [Come vengono identificate le campate](#llamaindex-span-identification) + [Come vengono estratti i campi di valutazione](#llamaindex-extraction) + [Dai registri degli eventi](#llamaindex-extraction-event-records) + [Dagli attributi span](#llamaindex-extraction-attributes) + [L'esempio include i record degli eventi](#llamaindex-examples-with) + [Esempio di intervalli senza record di eventi](#llamaindex-examples-without) + [Le migliori pratiche per gli agenti LlamaIndex ](#llamaindex-best-practices) ## Strumenta il tuo agente Puoi strumentare un LlamaIndex agente con una delle due librerie di strumentazione: **OpenTelemetry**(`opentelemetry-instrumentation-llamaindex`) o **OpenInference**(`openinference-instrumentation-llama-index`). Amazon Bedrock AgentCore Evaluations supporta entrambe le librerie. Le librerie emettono nomi di ambito diversi e utilizzano attributi span diversi. Il servizio di valutazione estrae gli stessi valori da ciascuna di esse. Quando il tuo agente utilizza AWS Distro for OpenTelemetry (ADOT), ad esempio su Amazon Bedrock AgentCore Runtime, non è necessario aggiungere codice di strumentazione esplicito. È sufficiente aggiungere la libreria di strumentazione alle dipendenze del progetto. ADOT la rileva all'avvio e la attiva automaticamente. Aggiungi la libreria di strumentazione per il percorso che desideri alle tue dipendenze. Utilizzate l'ultima versione disponibile a meno che non abbiate un motivo per bloccarla. **Example** NOTA: utilizza la versione `0.61.0` o successiva. Questa è la prima versione testata con il servizio di valutazione. `opentelemetry-instrumentation-llamaindex`Aggiungila alle tue dipendenze. Il nome dell'ambito emesso è. `opentelemetry.instrumentation.llamaindex` `requirements.txt`: ``` opentelemetry-instrumentation-llamaindex>=0.61.0 ``` `pyproject.toml`: ``` [project] dependencies = [ "opentelemetry-instrumentation-llamaindex>=0.61.0", ] ``` NOTA: utilizza la versione `4.4.1` o successiva. Questa è la prima versione testata con il servizio di valutazione. `openinference-instrumentation-llama-index`Aggiungila alle tue dipendenze. Il nome dell'ambito emesso è. `openinference.instrumentation.llama_index` `requirements.txt`: ``` openinference-instrumentation-llama-index>=4.4.1 ``` `pyproject.toml`: ``` [project] dependencies = [ "openinference-instrumentation-llama-index>=4.4.1", ] ``` **Nota** La strumentazione è un passo nella configurazione dell'osservabilità. [Per esportare la telemetria per la valutazione, completa la configurazione completa in Imposta l'osservabilità.](supported-frameworks.md#supported-frameworks-setup) ## Come vengono identificati gli intervalli L'attributo utilizzato per classificare gli intervalli differisce tra le due librerie di strumentazione. **Example** La libreria di OpenTelemetry strumentazione classifica gli intervalli utilizzando l'attributo. `traceloop.span.kind` Poiché LlamaIndex etichetta sia l'inferenza che le operazioni dello strumento come`task`, AgentCore Evaluations le disambigua in base all'`traceloop.entity.name`attributo: a il `task` cui nome di entità termina con è uno strumento di esecuzione; qualsiasi `Tool.task` altro è un intervallo di inferenza. `task` | Tipo di span | Attributo identificativo | | --- | --- | | Invoca l'agente | `traceloop.span.kind` = `workflow` | | Strumento di esecuzione | `traceloop.span.kind`=`tool`, o `traceloop.span.kind` = `task` con `traceloop.entity.name` terminazione in `Tool.task` | | Inferenza | `traceloop.span.kind`= `task` (non è un'operazione strumentale) | La libreria di OpenInference strumentazione classifica gli intervalli utilizzando l'attributo. `openinference.span.kind` LlamaIndex emette `CHAIN``LLM`, e si estende; non emette `TOOL` intervalli. `AGENT` Il root workflow span (a`CHAIN`) funge da invoke agent span. | Tipo di span | Attributo identificativo | | --- | --- | | Invoca l'agente | `openinference.span.kind`= `CHAIN` (intervallo del flusso di lavoro principale) | | Strumento di esecuzione | `openinference.span.kind` = `TOOL` | | Inferenza | `openinference.span.kind` = `LLM` | LlamaIndex emette diversi intervalli `CHAIN` intermedi (ad esempio, per l'analisi dell'output e il routing degli strumenti). AgentCore Evaluations considera solo l'intervallo del flusso di lavoro principale come invoke agent span e ricostruisce il prompt dell'utente e la risposta dell'agente dagli intervalli di inferenza () presenti nella traccia. `LLM` ## Come vengono estratti i campi di valutazione L' LlamaIndex agente è un **flusso di lavoro** e il relativo intervallo di livello superiore viene emesso prima dell'intervallo secondario. Tale intervallo di flusso di lavoro non contiene contenuti di conversazione propri utilizzabili, quindi AgentCore Evaluations ricostruisce il prompt dell'utente e la risposta dell'agente a partire dagli intervalli secondari (l'intervallo di inferenza e quello degli strumenti) e li associa all'intervallo dell'agente di invoke. LlamaIndex serializza anche i contenuti come JSON annidato. Gli argomenti dello strumento vengono racchiusi come `{"kwargs": {…​}}` e i risultati dello strumento vengono racchiusi come. `{"blocks": [{"text": "…​"}], …​}` AgentCore Evaluations elimina questi moduli. Quando un LlamaIndex ReAct agente produce un output nel modulo`Thought: …​ Answer: `, AgentCore Evaluations estrae il testo successivo alla risposta dell'`Answer:`agente. La posizione di questo contenuto dipende dal modo in cui è stata raccolta la telemetria. L'attributo identificativo (`traceloop.span.kind`o`openinference.span.kind`) è presente nell'intervallo in entrambi i casi. Per ulteriori informazioni, consulta [Intervalli, record di eventi e segnali di telemetria](supported-frameworks-telemetry.md). ### Dai registri degli eventi Quando la telemetria viene suddivisa, AgentCore Evaluations legge il contenuto del record dell'evento correlato a ciascun intervallo: + **Richiesta dell'utente** e **risposta dell'agente**: ricostruita a partire dai record degli eventi degli intervalli di inferenza, in. `body.output` Con la OpenTelemetry libreria, il prompt dell'utente proviene dal contenuto della cronologia delle chat e la risposta dell'agente dal contenuto del risultato del modello. Nella OpenInference libreria, il prompt dell'utente è il messaggio di input in testo semplice e la risposta dell'agente è l'output del modello (con il testo successivamente utilizzato per un agente). `Answer:` ReAct + **Chiamata allo strumento**: il nome dello strumento dall'intervallo di esecuzione dello strumento. Gli argomenti e i risultati dello strumento provengono dal record degli eventi di quell'intervallo, in `body.input` (unwrapped from`{"kwargs": {…​}}`) e `body.output` (unwrapped from). `{"blocks": […​]}` Per esempi, vedete Example spans with event [records](#llamaindex-examples-with). ### Dagli attributi span Quando la telemetria non viene suddivisa, lo stesso contenuto rimane nell'intervallo degli attributi. Gli attributi dipendono dalla libreria di strumentazione: + **OpenTelemetry**: il contenuto si trova negli `traceloop.entity.output` attributi `traceloop.entity.input` e di ogni intervallo. AgentCore Le valutazioni applicano la stessa cronologia delle chat, i risultati e lo stesso strumento di analisi a questi valori. + **OpenInference**: il contenuto dell'inferenza si trova sugli attributi indicizzati del messaggio (e). `llm.input_messages. ` `llm.output_messages.` Gli argomenti dello strumento provengono da `input.value` (scartati da`{"kwargs": {…​}}`) e lo strumento risulta da (decompresso da`output.value`). `{"blocks": […​]}` Per esempi, vedete [Example spans](#llamaindex-examples-without) without event records. ## L'esempio si estende ai record degli eventi Quando la telemetria viene suddivisa, l'intervallo contiene gli attributi identificativi e il contenuto risiede in un record di eventi correlato. I seguenti esempi sono tratti da un agente di LlamaIndex ReAct pianificazione dei viaggi distribuito su Amazon Bedrock Runtime. AgentCore Lo stesso agente è mostrato in ogni libreria di strumentazione. **Nota** Questi esempi non sono intervalli completi. Mostrano dati rappresentativi derivanti da un'interazione con un agente reale, con alcuni campi omessi e valori lunghi troncati per motivi di leggibilità. ### OpenTelemetry **Example** L'`traceloop.span.kind`attributo (`workflow`) lo identifica come un invoke agent span. L'intervallo del flusso di lavoro non contiene contenuti di conversazione; AgentCore Evaluations ricostruisce il prompt dell'utente e la risposta dell'agente negli intervalli secondari. ``` { "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" } } ``` L'`traceloop.span.kind`attributo (`task`) con una `traceloop.entity.name` terminazione lo `Tool.task` identifica come un intervallo di strumenti di esecuzione. Il record dell'evento correlato contiene gli argomenti dello strumento (racchiusi`kwargs`) e il risultato dello strumento (racchiuso`blocks`), oltre al nome dello strumento. ``` { "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\"}" } ] } } } ``` L'`traceloop.span.kind`attributo (`task`), con un `traceloop.entity.name` che non termina con`Tool.task`, lo identifica come un intervallo di inferenza. Un LlamaIndex agente produce diversi di questi intervalli per turno. In ognuna di esse, il contenuto è impacchettato `body.output` (non ce n'è`body.input`), come stringa JSON serializzata. AgentCore Evaluations legge il **prompt dell'utente** dalla stringa chat-history (un `{"input": […​]}` oggetto) nel primo intervallo di inferenza e la **risposta dell'agente** dalla stringa del risultato del modello (un oggetto) nell'ultimo intervallo di inferenza. `{"result": {"response": …​}}` Quanto segue è l'intervallo di inferenza stesso. ``` { "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" } } ``` Nel primo intervallo di inferenza, il `body.output` contenuto del record dell'evento è la cronologia della chat. Il prompt utente è il testo `user` -role all'interno dell'array annidato. `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\"}" } ] } } } ``` Nell'ultimo intervallo di inferenza, il `body.output` contenuto del record dell'evento è il risultato del modello. La risposta dell'agente è il testo `assistant` -role all'interno dell'oggetto annidato. `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** L'`openinference.span.kind`attributo (`CHAIN`) sul root workflow span lo identifica come un invoke agent span. Lo span non contiene contenuti di conversazione utilizzabili; AgentCore Evaluations ricostruisce il prompt dell'utente e la risposta dell'agente a partire dagli intervalli di inferenza. ``` { "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" } } ``` L'`openinference.span.kind`attributo (`TOOL`) lo identifica come un intervallo di strumenti di esecuzione; contiene il nome dello strumento. `tool.name` Gli argomenti e i risultati dello strumento risiedono nel record degli eventi correlato, racchiuso rispettivamente in e. `kwargs` `blocks` ``` { "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\"}" } ] } } } ``` L'`openinference.span.kind`attributo (`LLM`) lo identifica come un intervallo di inferenza. I ruoli dei messaggi si basano sugli attributi span; il contenuto risiede nel record dell'evento correlato. ADOT riduce i ruoli di input a`user`, quindi AgentCore Evaluations utilizza l'ultimo messaggio di input in testo semplice come prompt dell'utente. LlamaIndex emette un messaggio di output duplicato con `assistant:` prefisso, che Evaluations salta a favore della copia pulita. AgentCore ``` { "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 ..." } ] } } } ``` ## L'esempio si estende senza record di eventi Quando la telemetria non viene suddivisa, lo stesso contenuto rimane negli attributi span e non viene prodotto alcun record di eventi separato. Gli esempi seguenti sono tratti da un addetto alla pianificazione dei viaggi. LlamaIndex ReAct Lo stesso agente è mostrato in ogni libreria di strumentazione. **Nota** Questi esempi non sono intervalli completi. Mostrano dati rappresentativi derivanti da un'interazione con un agente reale, con alcuni campi omessi e valori lunghi troncati per motivi di leggibilità. ### OpenTelemetry **Example** L'`traceloop.entity.input`attributo contiene gli argomenti dello strumento (racchiusi`kwargs`) e l'`traceloop.entity.output`attributo contiene il risultato dello strumento (racchiuso). `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" } } ``` L'`traceloop.entity.output`attributo contiene la cronologia della chat, dalla quale AgentCore Evaluations legge il prompt dell'utente. La risposta proviene dal risultato del modello sull'ultimo intervallo di inferenza. ``` { "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** L'`input.value`attributo contiene gli argomenti dello strumento (racchiusi`kwargs`) e l'`output.value`attributo contiene il risultato dello strumento (racchiuso). `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" } } ``` Il contenuto del messaggio è in linea negli attributi indicizzati. Gli `llm.input_messages. ` attributi contengono il prompt di sistema e il prompt dell'utente e `llm.output_messages.` gli attributi contengono l'output del modello, da cui Evaluations estrae il testo dopo di che AgentCore Evaluations estrae il testo come risposta dell'agente. `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" } } ``` ## Le migliori pratiche per gli agenti LlamaIndex Il modo in cui si crea e si richiama un LlamaIndex agente influisce su ciò che appare nella sua telemetria e quindi sull'affidabilità della valutazione dell'agente. Le seguenti pratiche aiutano a garantire che il prompt dell'utente, la risposta dell'agente e l'attività dello strumento siano ripristinabili. + **Utilizza un flusso di lavoro per agenti LlamaIndex .** Crea il tuo agente come flusso di lavoro di un LlamaIndex agente (ad esempio, a `ReActAgent` or`FunctionAgent`) in modo che il framework emetta un flusso di lavoro di alto livello con inferenza e intervalli secondari. AgentCore Evaluations ricostruisce lo span dell'agente invoke partendo da questi intervalli secondari. + **Registra gli strumenti come oggetti. `FunctionTool`** Definisci ogni strumento come LlamaIndex `FunctionTool` (o usa gli helper `@tool` -style che ne producono uno). Gli intervalli degli strumenti sono identificati dal nome dell'entità e i relativi argomenti e risultati sono serializzati negli and structures Evaluations `kwargs` unwraps. `blocks` AgentCore + **Mantieni i risultati dello strumento serializzabili in base al testo.** Restituisce i risultati dello strumento come stringhe o valori. JSON-serializable LlamaIndex li racchiude in un blocco di testo; mantenendoli serializzabili si garantisce che il risultato dello strumento venga acquisito in modo chiaro. + **Per ReAct gli agenti, utilizzate il formato di output standard.** AgentCore Evaluations estrae la risposta finale dalla `Answer:` sezione dell'output di un ReAct agente. L'utilizzo del ReAct prompt standard ( LlamaIndex impostazione predefinita) consente di ripristinare la risposta dell'agente.