Instrumentieren Sie Ihren Agenten Wie werden Spannweiten identifiziert Wie werden Bewertungsfelder extrahiert Beispiel für Zeitspannen mit Ereignisdatensätzen Beispiel: Spans ohne Ereignisdatensätze Bewährte Methoden für LlamaIndex Agenten

LlamaIndex

Auf dieser Seite wird erklärt, wie ein LlamaIndexAgent instrumentiert wird, wie Spans identifiziert werden und wie Bewertungsfelder extrahiert werden. Abschließend werden bewährte Verfahren zur Strukturierung eines LlamaIndex Agenten beschrieben, sodass er zuverlässig bewertet werden kann.

Topics

Instrumentieren Sie Ihren Agenten
Wie werden Spannweiten identifiziert
Wie werden Bewertungsfelder extrahiert
- Aus Ereignisaufzeichnungen
- Aus Span-Attributen
Beispiel für Spans mit Ereignisdatensätzen
Beispiel für Spans ohne Ereignisdatensätze
Bewährte Methoden für Agenten LlamaIndex

Instrumentieren Sie Ihren Agenten

Sie können einen LlamaIndex Agenten mit einer von zwei Instrumentierungsbibliotheken instrumentieren: OpenTelemetry(opentelemetry-instrumentation-llamaindex) oder OpenInference(openinference-instrumentation-llama-index). Amazon Bedrock AgentCore Evaluations unterstützt beide Bibliotheken. Die Bibliotheken geben unterschiedliche Bereichsnamen aus und verwenden unterschiedliche Span-Attribute. Der Bewertungsservice extrahiert aus jedem die gleichen Werte.

Wenn Ihr Agent mit AWS Distro for OpenTelemetry (ADOT) ausgeführt wird, z. B. auf Amazon Bedrock AgentCore Runtime, müssen Sie keinen expliziten Instrumentierungscode hinzufügen. Es reicht aus, die Instrumentierungsbibliothek zu den Abhängigkeiten Ihres Projekts hinzuzufügen. ADOT erkennt es beim Start und aktiviert es automatisch.

Fügen Sie die Instrumentierungsbibliothek für den gewünschten Pfad zu Ihren Abhängigkeiten hinzu. Verwenden Sie die neueste verfügbare Version, es sei denn, Sie haben einen Grund zum Pin.

Beispiel

Anmerkung

Die Instrumentierung ist ein Schritt bei der Einrichtung der Beobachtbarkeit. Um Telemetrie zur Auswertung zu exportieren, schließen Sie die vollständigen Einstellungen unter Beobachtbarkeit einrichten ab.

Wie werden Spannweiten identifiziert

Das zur Klassifizierung von Spans verwendete Attribut unterscheidet sich zwischen den beiden Instrumentierungsbibliotheken.

Beispiel

OpenTelemetry

Die OpenTelemetry Instrumentierungsbibliothek klassifiziert Spans anhand des Attributs. traceloop.span.kind Da sowohl LlamaIndex Inferenz- als auch Werkzeugoperationen als gekennzeichnet werdentask, unterscheidet AgentCore Evaluations sie anhand des traceloop.entity.name Attributs: a, task dessen Entitätsname auf „steht“, ist ein Ausführungs-Tool-Span, jeder andere Tool.task ist ein Inferenz-Bereich. task

Typ der Spanne	Identifizierendes Attribut
Agent aufrufen	`traceloop.span.kind` = `workflow`
Tool ausführen	`traceloop.span.kind`=`tool`, oder `traceloop.span.kind` = `task` mit der `traceloop.entity.name` Endung `Tool.task`
Inferenz	`traceloop.span.kind`= `task` (keine Werkzeugaufgabe)

OpenInference

Die OpenInference Instrumentierungsbibliothek klassifiziert Spannweiten anhand des openinference.span.kind Attributs. LlamaIndex gibt „CHAINLLM,“ und „TOOLSpans“ aus; es werden keine Spannen ausgegeben. AGENT Der Stamm-Workflow-Bereich (aCHAIN) fungiert als Span für den Invoke-Agent.

Span-Typ	Identifizierendes Attribut
Agent aufrufen	`openinference.span.kind`= `CHAIN` (Stamm-Workflow-Bereich)
Tool ausführen	`openinference.span.kind` = `TOOL`
Inferenz	`openinference.span.kind` = `LLM`

Anmerkung

LlamaIndex gibt mehrere Zwischenbereiche aus CHAIN (z. B. für die Ausgabeanalyse und das Tool-Routing). AgentCore Evaluations behandelt nur den Workflow-Stammbereich als Span des Invoke-Agents und rekonstruiert die Benutzereingabe und die Agentenantwort anhand der Inference () -Bereiche im Trace. LLM

Wie werden Bewertungsfelder extrahiert

Der LlamaIndex Agent ist ein Workflow, und sein Bereich auf oberster Ebene wird vor seinem untergeordneten Bereich ausgegeben. Dieser Workflow-Bereich enthält keinen eigenen nutzbaren Konversationsinhalt. Daher rekonstruiert AgentCore Evaluations die Benutzereingabe und die Agentenantwort anhand der untergeordneten Bereiche (Inferenz- und Tool-Spans) und fügt sie der Spanne des Invoke-Agents hinzu.

LlamaIndex serialisiert Inhalte auch als verschachteltes JSON. Werkzeugargumente werden als umschlossen und {"kwargs": {…}} Werkzeugergebnisse werden als umschlossen. {"blocks": [{"text": "…"}], …} AgentCore Evaluationen entpackt diese Formulare. Wenn ein LlamaIndex ReAct Agent eine Ausgabe im Formular erstelltThought: … Answer: <response>, extrahiert AgentCore Evaluations den Text danach Answer: als Antwort des Agenten.

Der Speicherort dieser Inhalte hängt davon ab, wie die Telemetriedaten erfasst wurden. Das identifizierende Attribut (traceloop.span.kindoderopeninference.span.kind) befindet sich in beiden Fällen auf der Spanne. Weitere Informationen finden Sie unter Spans, Ereignisdatensätze und Telemetriesignale.

Aus Ereignisaufzeichnungen

Wenn die Telemetrie aufgeteilt wird, liest AgentCore Evaluations Inhalte aus den Ereignisdatensätzen, die den einzelnen Bereichen zugeordnet sind:

Benutzereingabe und Antwort des Agenten: rekonstruiert aus den Ereignisaufzeichnungen der Inferenzspannen, in. body.output Bei der OpenTelemetry Bibliothek stammt die Benutzeraufforderung aus dem Inhalt des Chat-Verlaufs und die Antwort des Agenten aus dem Inhalt der Modellergebnisse. Bei der OpenInference Bibliothek ist die Benutzereingabeaufforderung die Klartext-Eingabenachricht und die Antwort des Agenten die Modellausgabe (wobei der Text danach Answer: für einen Agenten verwendet wird). ReAct
Werkzeugaufruf: Der Werkzeugname aus dem Bereich des Ausführungswerkzeugs. Die Werkzeugargumente und das Ergebnis stammen aus dem Ereignisdatensatz dieser Spanne, in body.input (ausgepackt von{"kwargs": {…}}) und body.output (ausgepackt von{"blocks": […]}).

Beispiele finden Sie unter Beispiel für Spans mit Ereignisdatensätzen.

Aus Span-Attributen

Wenn die Telemetrie nicht aufgeteilt wird, verbleibt derselbe Inhalt als Attribute im Bereich. Die Attribute hängen von der Instrumentierungsbibliothek ab:

OpenTelemetry: Der Inhalt befindet sich in den traceloop.entity.output Attributen traceloop.entity.input und der einzelnen Bereiche. AgentCore Evaluations wendet denselben Chat-Verlauf, dasselbe Ergebnis und dieselbe Tool-Entschlüsselung auf diese Werte an.
OpenInference: Der Inhalt der Inferenz bezieht sich auf die indizierten Nachrichtenattribute (und). llm.input_messages. llm.output_messages. Die Werkzeugargumente stammen von input.value (entpackt von{"kwargs": {…}}) und das Werkzeugergebnis von output.value (ausgepackt von). {"blocks": […]}

Beispiele finden Sie unter Beispiel für Spans ohne Ereignisdatensätze.

Beispiel für Zeitspannen mit Ereignisdatensätzen

Wenn die Telemetrie aufgeteilt wird, enthält die Spanne die identifizierenden Attribute und der Inhalt befindet sich in einem korrelierten Ereignisdatensatz. Die folgenden Beispiele stammen von einem LlamaIndex ReAct Reiseplanungsagenten, der auf Amazon AgentCore Bedrock Runtime eingesetzt wurde. Derselbe Agent wird unter jeder Instrumentierungsbibliothek angezeigt.

Anmerkung

Bei diesen Beispielen handelt es sich nicht um vollständige Datenreihen. Sie zeigen repräsentative Daten aus einer echten Agenteninteraktion, wobei einige Felder weggelassen und lange Werte aus Gründen der Lesbarkeit gekürzt wurden.

OpenTelemetry

Beispiel

Invoke agent span

Das traceloop.span.kind Attribut (workflow) identifiziert dies als eine Spanne für den Aufruf-Agenten. Der Workflow-Bereich enthält keinen Konversationsinhalt. AgentCore Evaluations rekonstruiert die Benutzereingabe und die Antwort des Agenten anhand der untergeordneten Bereiche.


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

Das traceloop.span.kind Attribut (task) mit der traceloop.entity.name Endung auf Tool.task identifiziert diesen Vorgang als einen Bereich für das Ausführungstool. Der korrelierte Ereignisdatensatz enthält die Werkzeugargumente (eingeschlossenkwargs) und das Werkzeugergebnis (eingeschlossenblocks) zusammen mit dem Werkzeugnamen.


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

Das traceloop.span.kind Attribut (task) mit einem, traceloop.entity.name das nicht auf endetTool.task, identifiziert dies als eine Inferenzspanne. Ein LlamaIndex Agent erzeugt mehrere dieser Spannen pro Spielzug. In jedem Fall wird der Inhalt als serialisierte JSON-Zeichenfolge in eine serialisierte JSON-Zeichenfolge gepackt body.output (es gibt keinebody.input). AgentCore Evaluations liest die Benutzeraufforderung aus der Chat-Verlaufszeichenfolge (ein {"input": […]} Objekt) im ersten Inferenzbereich und die Antwort des Agenten aus der Modellergebniszeichenfolge (ein {"result": {"response": …}} Objekt) in der letzten Inferenzspanne.

Das Folgende ist der Inferenzbereich selbst.


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

In der ersten Inferenzspanne ist der body.output Inhalt des Ereignisdatensatzes der Chat-Verlauf. Die Benutzereingabeaufforderung ist der Text user -role innerhalb des input verschachtelten Arrays.


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

In der letzten Inferenzspanne ist der body.output Inhalt des Ereignisdatensatzes das Modellergebnis. Die Antwort des Agenten ist der Text assistant -role innerhalb des result.response verschachtelten Objekts.


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

Beispiel

Invoke agent span

Das openinference.span.kind Attribut (CHAIN) im Stamm-Workflow-Bereich identifiziert dies als Span für den Invoke-Agent. Die Spanne enthält keinen brauchbaren Konversationsinhalt. AgentCore Evaluations rekonstruiert die Benutzereingabe und die Antwort des Agenten anhand der Inferenzspannen.


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

Das openinference.span.kind Attribut (TOOL) identifiziert dies als Span für das Ausführungstool; es tool.name enthält den Namen des Tools. Die Werkzeugargumente und das Ergebnis befinden sich im korrelierten Ereignisdatensatz, eingeschlossen in kwargs blocks bzw..


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

Das openinference.span.kind Attribut (LLM) identifiziert dies als eine Inferenzspanne. Nachrichtenrollen befinden sich in den Span-Attributen; der Inhalt befindet sich im korrelierten Ereignisdatensatz. ADOT reduziert die Eingaberollen aufuser, sodass AgentCore Evaluations die letzte Klartext-Eingabemeldung als Benutzeraufforderung verwendet. LlamaIndex gibt eine doppelte assistant: Ausgabenachricht mit Präfix aus, die AgentCore Evaluations zugunsten der sauberen Kopie überspringt.


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

Beispiel: Spans ohne Ereignisdatensätze

Wenn die Telemetrie nicht aufgeteilt wird, verbleibt derselbe Inhalt in den Span-Attributen und es wird kein separater Ereignisdatensatz erstellt. Die folgenden Beispiele stammen von einem LlamaIndex ReAct Reiseplanungsbüro. Derselbe Agent wird unter jeder Instrumentenbibliothek angezeigt.

Anmerkung

OpenTelemetry

Beispiel

OpenInference

Beispiel

Execute tool span

Das input.value Attribut enthält die Werkzeugargumente (eingeschlossenkwargs), und das output.value Attribut enthält das Werkzeugergebnis (eingeschlossenblocks).


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

Der Nachrichteninhalt befindet sich direkt in den indizierten Attributen. Die llm.input_messages. Attribute enthalten die System- und Benutzereingabeaufforderung, und die llm.output_messages. Attribute enthalten die Modellausgabe, aus der AgentCore Evaluations den Text Answer: als Antwort des Agenten extrahiert.


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

Bewährte Methoden für LlamaIndex Agenten

Die Art und Weise, wie Sie einen LlamaIndex Agenten erstellen und aufrufen, wirkt sich darauf aus, was in seiner Telemetrie angezeigt wird und wie zuverlässig der Agent bewertet werden kann. Mit den folgenden Methoden wird sichergestellt, dass die Benutzeraufforderung, die Antwort des Agenten und die Aktivität des Tools wiederhergestellt werden können.

Verwenden Sie einen LlamaIndex Agenten-Workflow. Erstellen Sie Ihren Agenten als LlamaIndex Agenten-Workflow (z. B. ein ReActAgent oderFunctionAgent), sodass das Framework einen Workflow-Bereich auf oberster Ebene mit Inferenz- und Tool-Unterbereichen ausgibt. AgentCore Evaluations rekonstruiert anhand dieser untergeordneten Bereiche die Spanne des Agentenaufrufs.
Registrieren Sie Werkzeuge als Objekte. FunctionTool Definieren Sie jedes Werkzeug als ein LlamaIndex FunctionTool (oder verwenden Sie Helfer @tool im -stil, die eines erzeugen). Die einzelnen Tools werden anhand ihres Entity-Namens identifiziert, und ihre Argumente und Ergebnisse werden in den Unwraps kwargs und blocks Structures AgentCore Evaluations serialisiert.
Sorgen Sie dafür, dass die Werkzeugergebnisse textserialisierbar sind. Gibt Werkzeugergebnisse als Zeichenfolgen oder Werte zurück. JSON-serializable LlamaIndex verpackt sie in einen Textblock. Wenn sie serialisierbar bleiben, wird sichergestellt, dass das Werkzeugergebnis sauber erfasst wird.
Verwenden Sie für ReAct Agenten das Standardausgabeformat. AgentCore Evaluationen extrahiert die endgültige Antwort aus dem Answer: Abschnitt der Ausgabe eines ReAct Agenten. Bei Verwendung der ReAct Standardaufforderung ( LlamaIndex Standardeinstellung) kann die Antwort des Agenten wiederhergestellt werden.

Warnung JavaScript ist in Ihrem Browser nicht verfügbar oder deaktiviert.

Zur Nutzung der AWS-Dokumentation muss JavaScript aktiviert sein. Weitere Informationen finden auf den Hilfe-Seiten Ihres Browsers.

Dokumentkonventionen

OpenAI-Agenten

Google ADK