Individua il tuo agente Come vengono identificati gli intervalli Come vengono estratti i campi di valutazione Esempi di intervalli nella telemetria divisa Esempi di intervalli nella telemetria unificata Procedure consigliate per gli agenti LlamaIndex

LlamaIndex

Questa pagina spiega come strumentare un LlamaIndex agente, 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 identificati gli intervalli
Come vengono estratti i campi di valutazione
- Dai registri degli eventi
- Dagli attributi span
Esempi di intervalli nella telemetria divisa
Esempi di intervalli nella telemetria unificata
Procedure LlamaIndex consigliate per gli agenti

Individua 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 ciascuno di essi.

Quando l'agente viene eseguito con 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. Usa l'ultima versione disponibile a meno che tu non abbia un motivo per bloccarlo.

Esempio

Nota

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

Come vengono identificati gli intervalli

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

Esempio

OpenTelemetry

La libreria di OpenTelemetry strumentazione classifica gli intervalli utilizzando l'attributo. traceloop.span.kind Poiché LlamaIndex contrassegna sia l'inferenza che le operazioni sullo strumento cometask, AgentCore Evaluations le distingue con l'traceloop.entity.nameattributo: una il task cui nome di entità termina con è un intervallo di esecuzione dello strumento; qualsiasi Tool.task altra è un intervallo di inferenza. task

Tipo 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` fine 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 e CHAIN si LLM TOOL estende; non emette intervalli. AGENT L'intervallo del flusso di lavoro principale (aCHAIN) funge da estensione dell'agente invoke.

Tipo di intervallo	Attributo identificativo
Invoca l'agente	`openinference.span.kind`= `CHAIN` (intervallo di flusso di lavoro principale)
Strumento di esecuzione	`openinference.span.kind` = `TOOL`
Inferenza	`openinference.span.kind` = `LLM`

Nota

LlamaIndex emette diversi intervalli intermedi CHAIN (ad esempio, per l'analisi dell'output e il routing degli strumenti). AgentCore Evaluations considera solo l'intervallo del flusso di lavoro principale come intervallo dell'agente invoke e ricostruisce il prompt dell'utente e la risposta dell'agente in base agli intervalli di inferenza () nella traccia. LLM

Come vengono estratti i campi di valutazione

L' LlamaIndex agente è un flusso di lavoro e l'intervallo di primo livello viene emesso prima dell'intervallo secondario. Tale intervallo di flusso di lavoro non comporta alcun contenuto di conversazione utilizzabile di per sé, pertanto 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 collega all'intervallo dell'agente invoke.

LlamaIndex inoltre serializza i contenuti come JSON annidato. Gli argomenti dello strumento sono racchiusi come {"kwargs": {…}} e i risultati dello strumento sono racchiusi come. {"blocks": [{"text": "…"}], …} AgentCore Le valutazioni estrapolano questi moduli. Quando un LlamaIndex ReAct agente produce un output nel moduloThought: … Answer: <response>, AgentCore Evaluations estrae il testo successivo come risposta dell'agente. Answer:

La posizione di questo contenuto dipende dal modo in cui è stata raccolta la telemetria. L'attributo identificativo (traceloop.span.kindoopeninference.span.kind) è indicato sullo span in entrambi i casi. Per ulteriori informazioni, vedere Configurazione e consegna della telemetria.

Dai registri degli eventi

Con la telemetria divisa, 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 Nella OpenTelemetry libreria, il prompt dell'utente proviene dal contenuto della cronologia delle chat e la risposta dell'agente dal contenuto dei risultati del modello. Nella OpenInference libreria, il prompt dell'utente è il messaggio di input in testo normale e la risposta dell'agente è l'output del modello (con il testo dopo essere stato utilizzato per un agente). Answer: ReAct
Chiamata allo strumento: il nome dello strumento in base all'intervallo di esecuzione dello strumento. Gli argomenti e i risultati dello strumento provengono dal record degli eventi di quell'intervallo, in body.input (estratto da{"kwargs": {…}}) e body.output (estratto da). {"blocks": […]}

Per ulteriori informazioni, consulta Esempi di intervalli di telemetria divisa.

Dagli attributi span

Con la telemetria unificata, lo stesso contenuto rimane nello span come gli attributi. Gli attributi dipendono dalla libreria di strumentazione:

OpenTelemetry: il contenuto si riferisce agli traceloop.entity.output attributi traceloop.entity.input e di ogni intervallo. AgentCore Le valutazioni applicano la stessa cronologia delle chat, i risultati e gli stessi strumenti a questi valori.
OpenInference: il contenuto dell'inferenza è sugli attributi del messaggio indicizzato (e). llm.input_messages.* llm.output_messages.* Gli argomenti dello strumento provengono da input.value (scartati da{"kwargs": {…}}) e il risultato dello strumento da output.value (decompresso da). {"blocks": […]}

Per ulteriori informazioni, consulta Esempi di intervalli nella telemetria unificata.

Esempi di intervalli nella telemetria divisa

Con la telemetria divisa, l'intervallo riporta 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 di 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 a partire dagli 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 l'estremità per lo Tool.task identifica come traceloop.entity.name un intervallo dello strumento di esecuzione. Il record dell'evento correlato contiene gli argomenti dello strumento (racchiusikwargs) e il risultato dello strumento (racchiusi inblocks), insieme 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 valore traceloop.entity.name che non termina inTool.task, lo identifica come intervallo di inferenza. Un LlamaIndex agente produce diversi di questi intervalli per turno. In ognuno di essi, il contenuto viene impacchettato body.output (non c'èbody.input), come stringa JSON serializzata. AgentCore Le valutazioni leggono il prompt dell'utente dalla stringa della cronologia della chat (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 dell'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) nell'intervallo del flusso di lavoro principale lo identifica come un invoke agent span. L'intervallo 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 dello strumento di esecuzione; contiene il nome dello strumento. tool.name Gli argomenti e i risultati dello strumento si trovano nel record dell'evento correlato, racchiusi rispettivamente in kwargs e. 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 intervallo di inferenza. I ruoli dei messaggi si trovano negli 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 normale come prompt dell'utente. LlamaIndex emette un messaggio di output con assistant: prefisso duplicato, che Evaluations ignora 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 ..." }
      ]
    }
  }
}

Esempi di intervalli nella telemetria unificata

Con la telemetria unificata, lo stesso contenuto rimane negli attributi span e non viene prodotto alcun record di evento separato. I seguenti esempi 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 di 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 (racchiusi inblocks).


{
  "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 AgentCore Evaluations estrae il testo in seguito Answer: come risposta dell'agente.


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

Procedure consigliate 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 sulla sua affidabilità. Le seguenti pratiche aiutano a garantire che il prompt dell'utente, la risposta dell'agente e l'attività dello strumento siano recuperabili.

Utilizza il flusso di lavoro di un LlamaIndex agente. Crea il tuo flusso di lavoro agente come LlamaIndex agente (ad esempio, un ReActAgent orFunctionAgent) in modo che il framework emetta un intervallo di flusso di lavoro di primo livello con inferenza e intervalli secondari dello strumento. AgentCore Le valutazioni ricostruiscono l'intervallo di invocazione dell'agente a partire da questi intervalli secondari.
Registra FunctionTool gli strumenti come oggetti. Definisci ogni strumento come un LlamaIndex FunctionTool (o usa degli helper @tool in stile -style che ne producono uno). Gli intervalli degli strumenti sono identificati dal nome dell'entità e i relativi argomenti e risultati sono serializzati nelle sezioni e strutture Evaluations kwargs unwraps. blocks AgentCore
Mantieni i risultati degli strumenti serializzabili come testo. Restituisce i risultati dello strumento come stringhe o JSON-serializable valori. LlamaIndex li racchiude in un blocco di testo; mantenerli serializzabili assicura che il risultato dello strumento venga catturato in modo pulito.
Per ReAct gli agenti, utilizzate il formato di output standard. AgentCore Le valutazioni estraggono la risposta finale dalla Answer: sezione dell'output di un ReAct agente. L'utilizzo del ReAct prompt standard ( LlamaIndex impostazione predefinita) mantiene la risposta dell'agente recuperabile.

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

Vercel AI SDK

Google ADK