Nachverfolgen des schrittweisen Argumentationsprozesses des Agenten mit Trace - Amazon Bedrock
Struktur des Trace

Nachverfolgen des schrittweisen Argumentationsprozesses des Agenten mit Trace

Jede Antwort eines Agenten für Amazon Bedrock wird von einem Trace begleitet, die es Ihnen ermöglicht, Ereignisse zu den Schritten zu empfangen, die vom Agenten orchestriert werden. Mithilfe des Trace können Sie den Argumentationsprozess des Agenten verfolgen, der diesen zu der Antwort führt, die er zu diesem Zeitpunkt in der Konversation gibt.

Verwenden Sie den Trace, um den Pfad des Agenten von der Benutzereingabe bis zur zurückgegebenen Antwort nachzuverfolgen. Der Trace liefert Informationen zu den Eingaben in die Aktionsgruppen, die der Agent aufruft, und die Wissensdatenbanken, die er abfragt, um dem Benutzer zu antworten. Darüber hinaus stellt der Trace Informationen zu den Ausgaben bereit, die von den Aktionsgruppen und Wissensdatenbanken zurückgegeben werden. Sie können sich die Argumentation ansehen, anhand derer der Agent bestimmt, welche Aktion er ausführt, oder die Abfrage, die er an eine Wissensdatenbank stellt. Wenn ein Schritt im Trace fehlschlägt, gibt diese einen Grund für den Fehler zurück. Verwenden Sie die detaillierten Informationen im Trace, um Probleme mit Ihrem Agenten zu beheben. Sie können Schritte identifizieren, die beim Agent zu Problemen oder zu einem unerwarteten Verhalten führen. Anhand dieser Informationen können Sie dann überlegen, wie Sie das Verhalten des Agenten verbessern können.

Struktur des Trace

Wenn Sie den Trace aktivieren, wird in der InvokeAgent-Antwort jedes chunk-Element im Stream von einem trace-Feld begleitet, das einem TracePart-Objekt zugeordnet ist. Das tracePart-Objekt enthält Informationen zum Agenten und zu den Sitzungen sowie den Argumentationsprozess des Agenten und die Ergebnisse des Aufrufs von API-Funktionen. 

{
    "agentId": "string",
    "agentName": "string",
    "collaboratorName": "string",
    "agentAliasId": "string",
    "sessionId": "string",
    "agentVersion": "string",
    "trace": { ...},    
    "callerChain": [{
        "agentAliasArn": "agent alias arn"
    }]
}

Die folgende Liste beschreibt die Felder des TracePart-Objekts:

  • agentId – Die eindeutige Kennung des Agenten.

  • agentName – Der Name des Agenten.

  • collaboratorName – Wenn die Zusammenarbeit mehrerer Agenten aktiviert ist, der Name des Agenten.

  • agentVersion – Die Version des Agenten.

  • agentAliasId – Die eindeutige Kennung des Agenten.

  • sessionId – Die eindeutige Kennung der Sitzung mit den Agenten.

  • trace – Enthält den Argumentationsprozess des Agenten und die Ergebnisse des Aufrufs von API-Aktionen. Weitere Informationen hierzu finden Sie unten.

  • callerChain – Die Liste der Anrufer zwischen dem Agenten, der diesen Trace veröffentlicht hat, und dem Endbenutzer.

    • Wenn es sich um einen einzelnen Agenten handelt, enthält dieses Feld den Alias „Arn“ desselben Agenten, der den Trace veröffentlicht hat.

    • Wenn die Zusammenarbeit mehrerer Agenten aktiviert ist, enthält dieses Feld den Alias „Arn“ aller Agenten, die die Endbenutzeranforderung an den aktuellen Agenten weitergeleitet haben.

Im TracePart befindet sich ein trace-Feld, das einem Trace-Objekt zugeordnet ist. Der Trace wird sowohl in der Konsole als auch in der API als JSON-Objekt angezeigt. Jeder Schritt in der Konsole oder jede Trace in der API kann eine der folgenden Ablaufverfolgungen sein:

  • PreProcessingTrace – Verfolgt die Eingabe und Ausgabe des Vorverarbeitungsschritts, in dem der Agent Benutzereingaben kontextualisiert und kategorisiert und deren Gültigkeit überprüft.

  • OrchestrationTrace – Verfolgt die Eingabe und Ausgabe des Orchestrierungsschritts, in dem der Agent die Eingabe interpretiert, Aktionsgruppen aufruft, Wissensdatenbanken abfragt. Dann gibt der Agent die Ausgabe zurück, um die Orchestrierung fortzusetzen oder dem Benutzer zu antworten.

  • PostProcessingTrace – Verfolgt die Eingabe und Ausgabe des Nachbearbeitungsschritts, in dem der Agent die endgültige Ausgabe der Orchestrierung verarbeitet und bestimmt, wie die Antwort an den Benutzer zurückgegeben werden soll.

  • CustomOrchestrationTrace – Details zum benutzerdefinierten Orchestrierungsschritt, in dem der Agent die Reihenfolge bestimmt, in der Aktionen ausgeführt werden.

  • RoutingClassifierTrace – Verfolgt die Eingabe und Ausgabe des Routing-Klassifizierers.

  • FailureTrace – Verfolgt den Grund für das Fehlschlagen eines Schritts.

  • GuardrailTrace – Verfolgt die Aktionen des Integritätsschutzes.

Jede der Ablaufverfolgungen (außerFailureTrace) enthält ein ModelInvocationInput-Objekt. Das ModelInvocationInput-Objekt enthält neben dem Prompt, die dem Agenten in diesem Schritt zur Verfügung gestellt wird, Konfigurationen, die in der Prompt-Vorlage für den Schritt festgelegt sind. Weitere Informationen zum Ändern von Prompt-Vorlagen finden Sie unter Verbessern der Korrektheit von Agenten mithilfe erweiterter Prompt-Vorlagen in Amazon Bedrock. Die Struktur des ModelInvocationInput-Objekts ist wie folgt:

{
    "traceId": "string",
    "text": "string",
    "type": "PRE_PROCESSING | ORCHESTRATION | ROUTING_CLASSIFIER | KNOWLEDGE_BASE_RESPONSE_GENERATION | POST_PROCESSING",
    "foundationModel":string",
    "inferenceConfiguration": {
        "maximumLength": number,
        "stopSequences": ["string"],
        "temperature": float,
        "topK": float,
        "topP": float
    },
    "promptCreationMode": "DEFAULT | OVERRIDDEN",
    "parserMode": "DEFAULT | OVERRIDDEN",
    "overrideLambda": "string"
}

Die folgende Liste beschreibt die Felder des ModelInvocationInput-Objekts:

Weitere Informationen zu den einzelnen Trace-Typen finden Sie in den folgenden Abschnitten:

{
    "modelInvocationInput": { // see above for details }
    "modelInvocationOutput": {
        "metadata": {
             "usage": {
                  "inputToken":: int,
                  "outputToken":: int
           },
         "rawResponse": {
              "content": "string"
          }
        "parsedResponse": {
            "isValid": boolean,
            "rationale": "string"
        },
        "traceId": "string"
    }
}

Der PreProcessingTrace besteht aus einem ModelInvocationInput- und einem PreProcessingModelInvocationOutput-Objekt. Die PreProcessingModelInvocationOutput enthält die folgenden Felder.

  • metadata – Enthält die folgenden Informationen zur Ausgabe des Basismodells.

    • usage – Enthält die folgenden Informationen zur Verwendung des Basismodells.

      • inputTokens – Enthält die Informationen zu den Eingabe-Token aus der Verwendung des Basismodells.

      • outputTokens – Enthält die Informationen zu den Ausgabe-Token aus der Verwendung des Basismodells.

  • rawResponse – Enthält die Rohausgabe des Basismodells.

    • content – Der Inhalt der Rohausgabe des Basismodells.

  • parsedResponse – Enthält die folgenden Details zur analysierten Benutzeraufforderung.

    • isValid – Gibt an, ob der Benutzer-Prompt gültig ist oder nicht.

    • rationale – Gibt die Argumentation des Agenten für die nächsten Schritte an.

  • traceId – Die eindeutige Kennung des Trace.

Der OrchestrationTrace besteht aus dem ModelInvocationInput-Objekt, dem OrchestrationModelInvocationOutput-Objekt und einer beliebigen Kombination der Objekte Rationale, InvocationInput und Observation. Die OrchestrationModelInvocationOutput enthält die folgenden Felder. Weitere Informationen zu den Objekten Rationale, InvocationInput und Observation erhalten Sie durch Auswahl einer der folgenden Registerkarten. 

{
    "modelInvocationInput": { // see above for details },
     "modelInvocationOutput": {
        "metadata": {
             "usage": {
                  "inputToken":: int,
                  "outputToken":: int
           },
         "rawResponse": {
              "content": "string"
          },
    "rationale": { ... },
    "invocationInput": { ... },
    "observation": { ... }
}

Wenn der type auf AGENT_COLLABORATOR festgelegt und das Routing für den Vorgesetzten-Agenten aktiviert wurde, enthält OrchestrationModelInvocationOutput die folgende Struktur:

routingClassifierModelInvocationOutput: {
        traceId: "string",
        rawResponse: "string",
        routerClassifierParsedResponse: {...} 
        metadata: {
            inputTokens: "..."
            outputTokens: "..."    
        }
    }
Rationale

Das Rationale-Objekt enthält die Argumentation des Agenten anhand der Benutzereingabe. Im Folgenden finden Sie die Struktur:

{
       "traceId": "string",
       "text": "string"
    }

Die folgende Liste beschreibt die Felder des Rationale-Objekts:

  • traceId – Die eindeutige Kennung des Trace-Schritts.

  • text – Der Argumentationsprozess des Agenten, der auf dem Eingabe-Prompt basiert.

InvocationInput

Das InvocationInput-Objekt enthält Informationen, die in die Aktionsgruppe oder Wissensdatenbank eingegeben werden, die aufgerufen oder abgefragt werden soll. Im Folgenden finden Sie die Struktur:

{
    "traceId": "string",
    "invocationType": "AGENT_COLLABORATOR" | "ACTION_GROUP | KNOWLEDGE_BASE | FINISH",
     "agentCollaboratorInvocationInput": { 
        // see below for details
    },
    "actionGroupInvocationInput": {
        // see below for details
    },
    "knowledgeBaseLookupInput": {
        "knowledgeBaseId": "string",
        "text": "string"
    }
}

Die folgende Liste beschreibt die Felder des InvocationInput-Objekts:

  • traceId – Die eindeutige Kennung des Trace.

  • invocationType – Gibt an, ob der Agent einen Collaborator-Agenten, eine Aktionsgruppe oder eine Wissensdatenbank aufruft oder die Sitzung beendet.

  • agentCollaborationInvocationInput – Enthält die Aufrufeingabe für die Collaborator-Agenten. Wird angezeigt, wenn type auf AGENT_COLLABORATOR festgelegt und das Routing für den Supervisor-Agenten aktiviert ist. Weitere Informationen finden Sie unter Verwenden der Zusammenarbeit mehrerer Agenten mit Agenten für Amazon Bedrock .

    • Die agentCollaborationInvocationInput -Struktur lautet wie folgt:

      {
  "agentCollaboratorName": "string",
  "agentCollaboratorAliasArn": "string",
  "input": {
      "text": "string"           
     }
  }

      Nachfolgend finden Sie Beschreibungen der Felder:

      • agentCollaboratorName – Der Name des Collaborator-Agenten, der dem Supervisor-Agenten zugeordnet ist.

      • agentCollaboratorAliasArn – Der Alias „Arn“ des Collaborator-Agenten, der die Antwort sendet.

      • input – Die Eingabezeichenfolge für den Collaborator-Agenten.

  • actionGroupInvocationInput – Wird angezeigt, wenn der type auf ACTION_GROUP festgelegt ist. Weitere Informationen finden Sie unter Definieren von Aktionen in der Aktionsgruppe. Dabei kann es sich um eine der folgenden Strukturen handeln:

    • Wenn die Aktionsgruppe durch ein API-Schema definiert ist, sieht die Struktur wie folgt aus:

      {
    "actionGroupName": "string",
    "apiPath": "string",
    "verb": "string",
    "parameters": [
        {
            "name": "string",
            "type": "string",
            "value": "string"
        },
        ...
    ],
    "requestBody": {
        "content": {
            "<content-type>": [
                {
                    "name": "string",
                    "type": "string",
                    "value": "string"
                }   
            ]
        }
    },
    "executionType": "LAMBDA | RETURN_CONTROL",
    "invocationId": "string"
}

      Nachfolgend finden Sie Beschreibungen der Felder:

      • actionGroupName – Der Name der Aktionsgruppe, die laut Vorhersage des Agenten aufgerufen werden sollte.

      • apiPath – Der Pfad zur aufzurufenden API-Operation gemäß dem API-Schema.

      • verb – Die verwendete API-Methode gemäß dem API-Schema.

      • parameters – Enthält eine Liste von Objekten. Jedes Objekt enthält den Namen, den Typ und den Wert eines Parameters in der API-Operation, wie im API-Schema definiert.

      • requestBody – Enthält den Text der Anforderung und ihre Eigenschaften, wie im API-Schema definiert.

      • executionType – Gibt an, ob die Ausführung der Aktion an eine Lambda-Funktion (LAMBDA) übergeben wird oder ob die Steuerung durch die InvokeAgent-Antwort (RETURN_CONTROL) zurückgegeben wird. Weitere Informationen finden Sie unter Verarbeiten der Ausführung der Aktion.

      • invocationId – Der eindeutige Bezeichner des Aufrufs. Wird nur zurückgegeben, wenn executionType auf RETURN_CONTROL festgelegt ist.

    • Wenn die Aktionsgruppe durch Funktionsdetails definiert ist, sieht die Struktur wie folgt aus:

      {
    "actionGroupName": "string",
    "function": "string",
    "parameters": [
        {
            "name": "string",
            "type": "string",
            "value": "string"
        },
        ...
    ],
    "executionType": "LAMBDA | RETURN_CONTROL",
    "invocationId": "string"
}

      Nachfolgend finden Sie Beschreibungen der Felder:

      • actionGroupName – Der Name der Aktionsgruppe, die laut Vorhersage des Agenten aufgerufen werden sollte.

      • function – Der Name der Funktion, die laut Vorhersage des Agenten aufgerufen werden sollte.

      • parameters – Die Parameter der Funktion.

      • executionType – Gibt an, ob die Ausführung der Aktion an eine Lambda-Funktion (LAMBDA) übergeben wird oder ob die Steuerung durch die InvokeAgent-Antwort (RETURN_CONTROL) zurückgegeben wird. Weitere Informationen finden Sie unter Verarbeiten der Ausführung der Aktion.

      • invocationId – Der eindeutige Bezeichner des Aufrufs. Wird nur zurückgegeben, wenn executionType auf RETURN_CONTROL festgelegt ist.

  • knowledgeBaseLookupInput – Wird angezeigt, wenn der type auf KNOWLEDGE_BASE festgelegt ist. Weitere Informationen finden Sie unter Abrufen von Daten und Generieren von KI-Antworten mit Wissensdatenbanken für Amazon Bedrock. Enthält die folgenden Informationen über die Wissensdatenbank und die Suchabfrage für die Wissensdatenbank:

    • knowledgeBaseId – Die eindeutige Kennung der Wissensdatenbank, nach der der Agent sucht.

    • text – Die an die Wissensdatenbank gestellte Abfrage.

Observation

Das Observation-Objekt enthält das Ergebnis eines Agent-Partners, einer Aktionsgruppe oder Wissensdatenbank oder die Antwort an den Benutzer. Im Folgenden finden Sie die Struktur:

{
    "traceId": "string",
    "type": "AGENT_COLLABORATOR |ACTION_GROUP | KNOWLEDGE_BASE | REPROMPT | ASK_USER | FINISH",
    "agentCollaboratorInvocationOutput": { 
            "agentCollaboratorName": "string",
            "agentCollaboratorAliasArn": "string",
            "output": {
                "text": "string"
            },
    "actionGroupInvocation": {
        "text": "JSON-formatted string"
    },
    "knowledgeBaseLookupOutput": {
        "retrievedReferences": [
            {
                "content": {
                    "text": "string"
                },
                "location": {
                    "type": "S3",
                    "s3Location": {
                        "uri": "string"
                    }
                }
            },
            ...
        ]
    },
    "repromptResponse": {
        "source": "ACTION_GROUP | KNOWLEDGE_BASE | PARSER",
        "text": "string"
    },
    "finalResponse": {
        "text"
    }
}

Die folgende Liste beschreibt die Felder des Observation-Objekts:

  • traceId – Die eindeutige Kennung des Trace.

  • type – Gibt an, ob die Beobachtung des Agenten anhand des Ergebnisses eines Agent-Partners, einer Aktionsgruppe oder einer Wissensdatenbank zurückgegeben wird oder ob der Agent den Benutzer erneut auffordert, nach weiteren Informationen fragt oder das Gespräch beendet.

  • agentCollaboratorInvocationOutput – Enthält die Antwort des Collaborator-Agenten oder die endgültige Antwort. Wird angezeigt, wenn type auf AGENT_COLLABORATOR festgelegt und das Routing für den Supervisor-Agenten aktiviert ist. Weitere Informationen finden Sie unter Verwenden der Zusammenarbeit mehrerer Agenten mit Agenten für Amazon Bedrock . Jede Ressource enthält die folgenden Felder:

    • agentCollaboratorName – Der Name des Collaborator-Agenten, der die Antwort sendet.

    • agentCollaboratorAliasArn – Der Alias „Arn“ des Collaborator-Agenten, der die Antwort sendet.

    • output – Enthält die Antwort, die vom Collaborator-Agenten gesendet wurde.

  • actionGroupInvocationOutput – Enthält die Zeichenfolge im JSON-Format, die von der API zurückgegeben wird, die von der Aktionsgruppe aufgerufen wurde. Erscheint, wenn der type ACTION_GROUP ist. Weitere Informationen finden Sie unter Definieren von OpenAPI-Schemas für die Aktionsgruppen Ihres Agenten in Amazon Bedrock.

  • knowledgeBaseLookupOutput – Enthält aus der Wissensdatenbank abgerufenen Text, der für die Beantwortung des Prompts relevant ist, sowie den Amazon-S3-Speicherort der Datenquelle. Erscheint, wenn der type KNOWLEDGE_BASE ist. Weitere Informationen finden Sie unter Abrufen von Daten und Generieren von KI-Antworten mit Wissensdatenbanken für Amazon Bedrock. Jedes Objekt in der retrievedReferences-Liste enthält die folgenden Felder:

    • content – Enthält text aus der Wissensdatenbank, der aufgrund der Abfrage der Wissensdatenbank zurückgegeben wird.

    • location – Enthält den Amazon-S3-URI der Datenquelle, in der der zurückgegebene Text gefunden wurde.

  • repromptResponse – Wird angezeigt, wenn der type auf REPROMPT festgelegt ist. Enthält den text, der erneut nach einem Prompt fragt, zusammen mit der source, warum der Agent eine weitere Prompts ausgibt.

  • finalResponse: Erscheint, wenn der type ASK_USER oder FINISH ist. Enthält den text, der den Benutzer nach weiteren Informationen fragt oder eine Antwort an den Benutzer ist.

{
    "modelInvocationInput": { // see above for details }
    "modelInvocationOutput": {
        "rawResponse": {
            "content": "string"
        },
        "metadata": {
            "usage": {
                "inputToken": int,
                "outputToken": int    
             }     
         },
        "parsedResponse": {
            "text": "string"
        },
        "traceId": "string"
    }
}

Der PostProcessingTrace besteht aus einem ModelInvocationInput- und einem PostProcessingModelInvocationOutput-Objekt. Die PostProcessingModelInvocationOutput enthält die folgenden Felder.

  • rawResponse – Enthält die Rohausgabe des Basismodells.

    • content – Der Inhalt der Rohausgabe des Basismodells.

  • metadata – Enthält die folgenden Informationen zur Ausgabe des Basismodells.

    • usage – Enthält die folgenden Informationen zur Verwendung des Basismodells.

      • inputTokens – Enthält die Informationen zu den Eingabe-Token aus der Verwendung des Basismodells.

      • outputTokens – Enthält die Informationen zu den Ausgabe-Token aus der Verwendung des Basismodells.

  • parsedResponse – Enthält den text, der nach der Verarbeitung durch die Parser-Funktion an den Benutzer zurückgegeben werden soll.

  • traceId – Die eindeutige Kennung des Trace.

{
    "failureReason": "string",
    "traceId": "string"
}

Die folgende Liste beschreibt die Felder des FailureTrace-Objekts:

  • failureReason – Der Grund, warum der Schritt fehlgeschlagen ist.

  • traceId – Die eindeutige Kennung des Trace.

{
    "action": "GUARDRAIL_INTERVENED" | "NONE",
    "inputAssessments": [GuardrailAssessment],
    "outputAssessments": [GuardrailAssessment]
}

Die folgende Liste beschreibt die Felder des GuardrailAssessment-Objekts:

  • action – Gibt an, ob bei den Eingabedaten der Integritätsschutz eingegriffen hat oder nicht. Die Optionen lauten GUARDRAIL_INTERVENED oder NONE.

  • inputAssessments – Die Details der Bewertung des Integritätsschutzes hinsichtlich der Benutzereingabe.

  • outputAssessments – Die Details der Bewertung des Integritätsschutzes hinsichtlich der Antwort.

Weitere Informationen zum GuardrailAssessment-Objekt und zum Testen des Integritätsschutzes finden Sie unter So testen Sie Ihren Integritätsschutz.

Beispiel für GuardrailAssessment:

{
    "topicPolicy": {
        "topics": [{
            "name": "string",
            "type": "string",
            "action": "string"
        }]
    },
    "contentPolicy": {
        "filters": [{
            "type": "string",
            "confidence": "string",
            "action": "string"
        }]
    },
    "wordPolicy": {
        "customWords": [{
            "match": "string",
            "action": "string"
        }],
        "managedWordLists": [{
            "match": "string",
            "type": "string",
            "action": "string"
        }]
    },
    "sensitiveInformationPolicy": {
        "piiEntities": [{
            "type": "string",
            "match": "string",
            "action": "string"
        }],
        "regexes": [{
            "name": "string",
            "regex": "string",
            "match": "string",
            "action": "string"
        }]
    }
}