Strumenta il tuo agente Come vengono identificati gli intervalli Come vengono estratti i campi di valutazione L'esempio si estende ai record degli eventi L'esempio si estende senza record di eventi Le migliori pratiche per gli agenti LlamaIndex

LlamaIndex

Questa pagina spiega come strumentare un LlamaIndexagente, come vengono identificati gli intervalli e come vengono estratti i campi di valutazione. Si chiude con le migliori pratiche per strutturare un LlamaIndex agente in modo che possa essere valutato in modo affidabile.

Argomenti

Strumenta il tuo agente
Come vengono identificate le campate
Come vengono estratti i campi di valutazione
- Dai registri degli eventi
- Dagli attributi span
L'esempio include i record degli eventi
Esempio di intervalli senza record di eventi
Le migliori pratiche per gli agenti LlamaIndex

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.

Esempio

Nota

La strumentazione è un passo nella configurazione dell'osservabilità. Per esportare la telemetria per la valutazione, completa la configurazione completa in Imposta l'osservabilità.

Come vengono identificati gli intervalli

L'attributo utilizzato per classificare gli intervalli differisce tra le due librerie di strumentazione.

Esempio

OpenTelemetry

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 cometask, AgentCore Evaluations le disambigua in base all'traceloop.entity.nameattributo: 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)

OpenInference

La libreria di OpenInference strumentazione classifica gli intervalli utilizzando l'attributo. openinference.span.kind LlamaIndex emette CHAINLLM, e si estende; non emette TOOL intervalli. AGENT Il root workflow span (aCHAIN) 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`

Nota

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 moduloThought: … Answer: <response>, 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.kindoopeninference.span.kind) è presente nell'intervallo in entrambi i casi. Per ulteriori informazioni, consulta Intervalli, record di eventi e segnali di telemetria.

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.

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 daoutput.value). {"blocks": […]}

Per esempi, vedete Example spans 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

Esempio

Invoke agent span

L'traceloop.span.kindattributo (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"
  }
}

Execute tool span

L'traceloop.span.kindattributo (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 (racchiusikwargs) e il risultato dello strumento (racchiusoblocks), 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\"}" }
      ]
    }
  }
}

Inference span

L'traceloop.span.kindattributo (task), con un traceloop.entity.name che non termina conTool.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

Esempio

Invoke agent span

L'openinference.span.kindattributo (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"
  }
}

Execute tool span

L'openinference.span.kindattributo (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\"}" }
      ]
    }
  }
}

Inference span

L'openinference.span.kindattributo (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 auser, 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

Esempio

OpenInference

Esempio

Execute tool span

L'input.valueattributo contiene gli argomenti dello strumento (racchiusikwargs) e l'output.valueattributo 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"
  }
}

Inference span

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

Avvertimento JavaScript è disabilitato o non è disponibile nel tuo browser.

Per usare la documentazione AWS, JavaScript deve essere abilitato. Consulta le pagine della guida del browser per le istruzioni.

Convenzioni dei documenti

Agenti OpenAI

Google ADK