Instrumente a su agente Cómo se identifican los intervalos Cómo se extraen los campos de evaluación Ejemplos de intervalos en telemetría dividida Un ejemplo abarca la telemetría unificada Mejores prácticas para los LlamaIndex agentes

LlamaIndex

En esta página se explica cómo instrumentar un LlamaIndex agente, cómo se identifican los intervalos y cómo se extraen los campos de evaluación. Termina con las mejores prácticas para estructurar un LlamaIndex agente de manera que pueda evaluarse de manera confiable.

Temas

Instrumente a su agente
Cómo se identifican los tramos
Cómo se extraen los campos de evaluación
- De los registros de eventos
- De los atributos de span
Ejemplo de intervalos en telemetría dividida
Ejemplos de intervalos en telemetría unificada
Mejores prácticas para los agentes LlamaIndex

Instrumente a su agente

Puede instrumentar un LlamaIndex agente con cualquiera de las dos bibliotecas de instrumentación: OpenTelemetry (opentelemetry-instrumentation-llamaindex) o OpenInference (openinference-instrumentation-llama-index). Amazon Bedrock AgentCore Evaluations es compatible con ambas bibliotecas. Las bibliotecas emiten distintos nombres de ámbito y utilizan distintos atributos de intervalo. El servicio de evaluación extrae los mismos valores de cada uno.

Cuando su agente se ejecuta con la AWS distribución para OpenTelemetry (ADOT), como en Amazon Bedrock AgentCore Runtime, no es necesario añadir código de instrumentación explícito. Basta con añadir la biblioteca de instrumentación a las dependencias de su proyecto. ADOT la descubre al inicio y la activa automáticamente.

Agregue la biblioteca de instrumentación para la ruta que desee a sus dependencias. Usa la última versión disponible a menos que tengas un motivo para anclar.

ejemplo

nota

La instrumentación es un paso para configurar la observabilidad. Para exportar la telemetría para su evaluación, complete la configuración completa en Configurar la observabilidad.

Cómo se identifican los intervalos

El atributo utilizado para clasificar los intervalos difiere entre las dos bibliotecas de instrumentación.

ejemplo

OpenTelemetry

La biblioteca de OpenTelemetry instrumentación clasifica los intervalos mediante el atributo. traceloop.span.kind Dado que las operaciones de inferencia y de herramienta se LlamaIndex etiquetan como task tales, AgentCore Evaluations las desambigua según el traceloop.entity.name atributo: a task cuyo nombre de entidad termina en un intervalo de la herramienta de ejecución; cualquier otro Tool.task es un intervalo de inferencia. task

Tipo de intervalo	Atributo identificativo
Invocar al agente	`traceloop.span.kind` = `workflow`
Ejecute la herramienta	`traceloop.span.kind`=`tool`, o `traceloop.span.kind` = `task` con `traceloop.entity.name` terminación en `Tool.task`
Inferencia	`traceloop.span.kind`= `task` (no es una tarea de herramientas)

OpenInference

La biblioteca de OpenInference instrumentación clasifica los intervalos mediante el atributo. openinference.span.kind LlamaIndex emite CHAINLLM, y TOOL abarca; no emite intervalos. AGENT El intervalo del flujo de trabajo raíz (aCHAIN) actúa como el intervalo del agente de invocación.

Tipo de intervalo	Atributo identificativo
Invocar al agente	`openinference.span.kind`= `CHAIN` (intervalo de flujo de trabajo raíz)
Ejecute la herramienta	`openinference.span.kind` = `TOOL`
Inferencia	`openinference.span.kind` = `LLM`

nota

LlamaIndex emite varios CHAIN intervalos intermedios (por ejemplo, para el análisis de los resultados y el enrutamiento de las herramientas). AgentCore Evaluations trata solo el intervalo del flujo de trabajo raíz como el intervalo del agente de invocación y reconstruye el aviso del usuario y la respuesta del agente a partir de los intervalos de inferencia () del seguimiento. LLM

Cómo se extraen los campos de evaluación

El LlamaIndex agente es un flujo de trabajo y su intervalo de nivel superior se emite antes que el de hijo. Ese intervalo de flujo de trabajo no contiene ningún contenido de conversación utilizable por sí solo, por lo que AgentCore Evaluations reconstruye la respuesta del agente y la respuesta del usuario a partir de los intervalos secundarios (los intervalos de la inferencia y la herramienta) y los adjunta al intervalo del agente de invocación.

LlamaIndex también serializa el contenido como JSON anidado. Los argumentos de la herramienta se empaquetan como y {"kwargs": {…}} los resultados de la herramienta se empaquetan como. {"blocks": [{"text": "…"}], …} AgentCore Las evaluaciones ocultan estos formularios. Cuando un LlamaIndex ReAct agente produce resultados en el formularioThought: … Answer: <response>, AgentCore Evaluations extrae el siguiente texto Answer: como respuesta del agente.

La ubicación de este contenido depende de cómo se recopiló la telemetría. El atributo identificativo (traceloop.span.kindoopeninference.span.kind) está en el intervalo en ambos casos. Para obtener más información, consulte Configuración y entrega de telemetría.

De los registros de eventos

Con la telemetría dividida, AgentCore las evaluaciones leen el contenido del registro de eventos en relación con cada intervalo:

Mensaje del usuario y respuesta del agente: se reconstruyeron a partir de los registros de eventos de los intervalos de inferencia, en. body.output En la OpenTelemetry biblioteca, la solicitud de usuario proviene del contenido del historial de chat y la respuesta del agente proviene del contenido del resultado del modelo. En la OpenInference biblioteca, la línea de comandos del usuario es el mensaje de entrada en texto plano y la respuesta del agente es la salida del modelo (con el texto que sigue a continuación se usa para un agente). Answer: ReAct
Llamada a la herramienta: el nombre de la herramienta del conjunto de herramientas de ejecución. Los argumentos y el resultado de la herramienta provienen del registro de eventos de ese intervalo, en body.input (sin empaquetar de{"kwargs": {…}}) y body.output (sin empaquetar de{"blocks": […]}).

Para obtener más información, consulte Ejemplos de intervalos en telemetría dividida.

A partir de los atributos de intervalo

Con la telemetría unificada, el mismo contenido permanece en el intervalo que los atributos. Los atributos dependen de la biblioteca de instrumentación:

OpenTelemetry: el contenido está en los traceloop.entity.output atributos traceloop.entity.input y atributos de cada tramo. AgentCore Las evaluaciones aplican el mismo historial de chat, resultados y herramientas para desempaquetar estos valores.
OpenInference: el contenido de la inferencia se basa en los atributos del mensaje indexado (y). llm.input_messages.* llm.output_messages.* Los argumentos de la herramienta provienen de input.value (sin empaquetar de{"kwargs": {…}}) y el resultado de la herramienta proviene de output.value (sin empaquetar de). {"blocks": […]}

Para obtener más información, consulte Ejemplos de intervalos en telemetría unificada.

Ejemplos de intervalos en telemetría dividida

Con la telemetría dividida, el intervalo contiene los atributos de identificación y el contenido se encuentra en un registro de eventos correlacionado. Los siguientes ejemplos provienen de un agente de LlamaIndex ReAct planificación de viajes implementado en Amazon Bedrock Runtime. AgentCore El mismo agente se muestra en cada biblioteca de instrumentación.

nota

Estos ejemplos no son conjuntos completos. Muestran datos representativos de una interacción real con un agente; se omiten algunos campos y se truncan los valores largos para facilitar la lectura.

OpenTelemetry

ejemplo

Invoke agent span

El traceloop.span.kind atributo (workflow) lo identifica como un intervalo de agentes de invocación. El intervalo del flujo de trabajo no contiene contenido de conversación; AgentCore las evaluaciones reconstruyen la respuesta del agente y del mensaje del usuario a partir de los intervalos secundarios.


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

El traceloop.span.kind atributo (task) que traceloop.entity.name termina en lo Tool.task identifica como un intervalo de ejecución de la herramienta. El registro de eventos correlacionados contiene los argumentos de la herramienta (incluidoskwargs) y el resultado de la herramienta (incluidoblocks), junto con el nombre de la herramienta.


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

El traceloop.span.kind atributo (task), con un traceloop.entity.name que no termina enTool.task, lo identifica como un intervalo de inferencia. Un LlamaIndex agente produce varios de estos intervalos por turno. En cada uno de ellos, el contenido se empaqueta en forma de cadena JSON serializada body.output (no existebody.input). AgentCore Las evaluaciones leen la solicitud del usuario de la cadena del historial de chat (un {"input": […]} objeto) en el primer intervalo de inferencia y la respuesta del agente de la cadena de resultados del modelo (un {"result": {"response": …}} objeto) en el último intervalo de inferencia.

El siguiente es el intervalo de inferencia propiamente dicho.


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

En el primer intervalo de inferencia, el body.output contenido del registro de eventos es el historial de chat. La línea de comandos del usuario es el texto user -role que se encuentra dentro de la matriz input anidada.


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

En el último intervalo de inferencia, el body.output contenido del registro de eventos es el resultado del modelo. La respuesta del agente es el texto assistant -role que se encuentra dentro del objeto result.response anidado.


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

ejemplo

Invoke agent span

El openinference.span.kind atributo (CHAIN) del intervalo de flujo de trabajo raíz lo identifica como un intervalo de agentes de invocación. El intervalo no contiene contenido de conversación utilizable; AgentCore Evaluations reconstruye el aviso del usuario y la respuesta del agente a partir de los intervalos de inferencia.


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

El openinference.span.kind atributo (TOOL) lo identifica como un intervalo de herramientas de ejecución; tool.name contiene el nombre de la herramienta. Los argumentos y el resultado de la herramienta se encuentran en el registro de eventos correlacionados, incluidos en kwargs y blocks respectivamente.


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

El openinference.span.kind atributo (LLM) lo identifica como un intervalo de inferencia. Los roles de los mensajes se encuentran en los atributos del intervalo; el contenido se encuentra en el registro de eventos correlacionados. ADOT reduce los roles de entrada para user que AgentCore Evaluations utilice el último mensaje de texto sin formato como mensaje de usuario. LlamaIndex emite un mensaje de salida con assistant: prefijo duplicado, que AgentCore Evaluations omite en favor de la copia limpia.


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

Un ejemplo abarca la telemetría unificada

Con la telemetría unificada, el mismo contenido permanece en los atributos del intervalo y no se produce ningún registro de eventos independiente. Los siguientes ejemplos son de un agente de LlamaIndex ReAct planificación de viajes. El mismo agente se muestra en cada biblioteca de instrumentación.

nota

Estos ejemplos no son conjuntos completos. Muestran datos representativos de una interacción real con un agente; se omiten algunos campos y se truncan los valores largos para facilitar la lectura.

OpenTelemetry

ejemplo

OpenInference

ejemplo

Execute tool span

El input.value atributo contiene los argumentos de la herramienta (kwargsincluidos) y el output.value resultado de la herramienta (incluidoblocks).


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

El contenido del mensaje está alineado con los atributos indexados. Los llm.input_messages.* atributos contienen la solicitud del sistema y la solicitud del usuario, y los llm.output_messages.* atributos contienen la salida del modelo, de la que AgentCore Evaluations extrae el texto posterior Answer: como respuesta del 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"
  }
}

Mejores prácticas para los LlamaIndex agentes

La forma en que se crea e invoca un LlamaIndex agente afecta a lo que aparece en su telemetría y, por lo tanto, a la fiabilidad con la que se puede evaluar el agente. Las siguientes prácticas ayudan a garantizar que la respuesta del usuario, la respuesta del agente y la actividad de la herramienta sean recuperables.

Utilice un flujo de trabajo LlamaIndex de agente. Cree su agente como un flujo de trabajo de LlamaIndex agente (por ejemplo, un ReActAgent oFunctionAgent) para que el marco emita un intervalo de flujo de trabajo de nivel superior con intervalos de inferencia y herramientas secundarias. AgentCore Las evaluaciones reconstruyen el intervalo del agente invocador a partir de estos intervalos secundarios.
Registra las herramientas como objetos. FunctionTool Defina cada herramienta como LlamaIndex FunctionTool (o utilice ayudantes de @tool estilo que produzcan una). Los intervalos de herramientas se identifican por el nombre de su entidad, y sus argumentos y resultados se serializan en las blocks estructuras kwargs y estructuras AgentCore que contienen las evaluaciones.
Mantenga los resultados de la herramienta serializables en texto. Devuelve los resultados de la herramienta como cadenas o JSON-serializable valores. LlamaIndex los envuelve en un bloque de texto; mantenerlos serializables garantiza que el resultado de la herramienta se capture de forma limpia.
Para los ReAct agentes, utilice el formato de salida estándar. AgentCore Las evaluaciones extraen la respuesta final de la Answer: sección del resultado de un ReAct agente. El uso del ReAct indicador estándar (el LlamaIndex predeterminado) permite recuperar la respuesta del agente.

Aviso JavaScript está desactivado o no está disponible en su navegador.

Para utilizar la documentación de AWS, debe estar habilitado JavaScript. Para obtener más información, consulte las páginas de ayuda de su navegador.

Convenciones del documento

Vercel AI SDK

ADK de Google