Suivez le processus de step-by-step raisonnement de l'agent à l'aide de Trace

Chaque réponse d'un agent Amazon Bedrock est accompagnée d'une trace détaillant les étapes orchestrées par l'agent. Cette trace vous aide à suivre le processus de raisonnement de l’agent qui le conduit à la réponse qu’il donne à ce moment de la conversation.

Utilisez la trace pour suivre le parcours de l’agent depuis l’entrée utilisateur jusqu’à la réponse qu’il renvoie. La trace fournit des informations sur les entrées des groupes d'actions que l'agent invoque et sur les bases de connaissances qu'il interroge pour répondre à l'utilisateur. En outre, le suivi fournit des informations sur les résultats renvoyés par les groupes d'action et les bases de connaissances. Vous pouvez consulter le raisonnement utilisé par l’agent pour déterminer l’action qu’il entreprend ou la requête qu’il adresse à une base de connaissances. Si une étape de la trace échoue, la raison de cet échec est renvoyée. Utilisez les informations détaillées de la trace pour dépanner votre agent. Vous pouvez identifier les étapes au cours desquelles l'agent rencontre des problèmes ou celles au cours desquelles il produit un comportement inattendu. Vous pouvez ensuite utiliser ces informations pour réfléchir aux moyens d'améliorer le comportement de l'agent.

Structure de la trace

Si vous activez le suivi, dans le InvokeAgentréponse, chaque chunk élément du flux est accompagné d'un trace champ qui correspond à un TracePartobjet. L'tracePartobjet contient des informations sur l'agent et les sessions, ainsi que le processus de raisonnement de l'agent et les résultats de l'appel des fonctions de l'API.


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

La liste suivante décrit les champs de TracePartobjet :

agentId— L'identifiant unique de l'agent.
agentName— Le nom de l'agent.
collaboratorName— Si la collaboration multi-agents est activée, le nom de l'agent collaborateur.
agentVersion— La version de l'agent.
agentAliasId— L'identifiant unique de l'alias de l'agent.
sessionId— L'identifiant unique de la session avec l'agent.
trace— Contient le processus de raisonnement de l'agent et les résultats des appels d'actions d'API. Voir ci-dessous pour plus d'informations.
callerChain— Liste des appelants entre l'agent qui a publié cette trace et l'utilisateur final.
- S'il s'agit d'un agent unique, ce champ contiendra l'alias Arn du même agent qui a publié la trace.
- Si la collaboration multi-agents est activée, ce champ contiendra l'alias Arn de tous les agents qui ont transmis la demande de l'utilisateur final à l'agent actuel.

Au sein du TracePartest un trace champ qui correspond à un Traceobjet. La trace est affichée sous forme d'objet JSON à la fois dans la console et dans l'API. Chaque étape dans la console ou Tracedans l'API, il peut y avoir l'une des traces suivantes :

PreProcessingTrace— Trace l'entrée et la sortie de l'étape de prétraitement, au cours de laquelle l'agent contextualise et catégorise les entrées de l'utilisateur et détermine si elles sont valides.
OrchestrationTrace— Trace l'entrée et la sortie de l'étape d'orchestration, au cours de laquelle l'agent interprète les entrées, invoque des groupes d'action et interroge les bases de connaissances. L'agent renvoie ensuite la sortie pour poursuivre l'orchestration ou pour répondre à l'utilisateur.
PostProcessingTrace— Trace l'entrée et la sortie de l'étape de post-traitement, au cours de laquelle l'agent gère le résultat final de l'orchestration et détermine comment renvoyer la réponse à l'utilisateur.
FailureTrace— Détermine la raison pour laquelle une étape a échoué.
GuardrailTrace— Retrace les actions du garde-corps.

Chacune des traces (saufFailureTrace) contient un ModelInvocationInputobjet. La ModelInvocationInputL'objet contient les configurations définies dans le modèle d'invite pour l'étape, ainsi que l'invite fournie à l'agent lors de cette étape. Pour plus d'informations sur la modification des modèles d'invite, consultezAméliorez la précision des agents à l'aide de modèles d'invite avancés dans Amazon Bedrock. La structure de l'ModelInvocationInputobjet est la suivante :


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

La liste suivante décrit les champs du ModelInvocationInputobjet :

traceId : identifiant unique de la trace.
text : texte de l’invite fournie à l’agent à cette étape.
type : étape actuelle du processus de l’agent.
foundationModel— Le modèle de base de l'agent collaborateur dans la collaboration multi-agents. Ce champ est rempli uniquement si type c'est le casROUTING_CLASSIFIER. Si le modèle par défaut utilisé pour l'invite de routage est remplacé, ce champ indique le modèle de l'agent de supervision utilisé pour acheminer l'invite.
inferenceConfiguration : paramètres d’inférence qui influencent la génération de réponses. Pour de plus amples informations, veuillez consulter Influencez la génération de réponses avec des paramètres d'inférence.
promptCreationMode— Si le modèle d'invite de base par défaut de l'agent a été remplacé pour cette étape. Pour de plus amples informations, veuillez consulter Améliorez la précision des agents à l'aide de modèles d'invite avancés dans Amazon Bedrock.
parserMode— Si l'analyseur de réponse par défaut de l'agent a été remplacé pour cette étape. Pour de plus amples informations, veuillez consulter Améliorez la précision des agents à l'aide de modèles d'invite avancés dans Amazon Bedrock.
overrideLambda— Le nom de ressource Amazon (ARN) de la fonction Lambda de l'analyseur utilisée pour analyser la réponse, si l'analyseur par défaut a été remplacé. Pour de plus amples informations, veuillez consulter Améliorez la précision des agents à l'aide de modèles d'invite avancés dans Amazon Bedrock.

Pour plus d'informations sur chaque type de trace, consultez les sections suivantes :


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

PreProcessingTraceIl se compose d'un ModelInvocationInputobjet et un PreProcessingModelInvocationOutputobjet. La PreProcessingModelInvocationOutputcontient les champs suivants.

metadata— Contient les informations suivantes concernant la sortie du modèle de base.
- usage— Contient les informations suivantes sur l'utilisation du modèle de base.
  - inputTokens— Contient les informations sur les jetons d'entrée issus de l'utilisation du modèle de base.
  - outputTokens— Contient les informations sur les jetons de sortie issus de l'utilisation du modèle de base.
rawResponse— Contient le résultat brut du modèle de base.
- content— Le contenu brut de sortie du modèle de base.
parsedResponse : contient les informations suivantes concernant l’invite utilisateur analysée.
- isValid— Spécifie si l'invite de l'utilisateur est valide.
- rationale : spécifie le raisonnement de l’agent pour les prochaines étapes à suivre.
traceId : identifiant unique de la trace.

OrchestrationTraceIl se compose du ModelInvocationInputobjet, OrchestrationModelInvocationOutputobjet, et toute combinaison des objets InvocationInputRationale et Observation. La OrchestrationModelInvocationOutputcontient les champs suivants. Pour plus d'informations sur les objets InvocationInputRationale et Observation, sélectionnez l'un des onglets suivants.


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

Si type c'est le cas AGENT_COLLABORATOR et si le routage a été activé pour l'agent superviseur, OrchestrationModelInvocationOutputcontiendra la structure suivante :


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

Rationale

L'objet Rationale contient le raisonnement de l'agent en fonction des données saisies par l'utilisateur. Voici la structure :


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

La liste suivante décrit les champs de l'objet Rationale :

traceId : identifiant unique de l’étape de la trace.
text— Le processus de raisonnement de l'agent, basé sur l'invite de saisie.

InvocationInput

L’objet InvocationInput contient des informations qui seront entrées dans le groupe d’actions ou la base de connaissances à invoquer ou à interroger. Voici la structure :


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

La liste suivante décrit les champs de l'InvocationInputobjet :

traceId : identifiant unique de la trace.
invocationType— Spécifie si l'agent appelle un agent collaborateur, un groupe d'action ou une base de connaissances, ou s'il met fin à la session.
agentCollaborationInvocationInput— Contient l'entrée d'invocation destinée aux agents collaborateurs. Apparaît si le routage type est activé pour l'agent superviseur AGENT_COLLABORATOR et s'il est activé. Pour de plus amples informations, veuillez consulter Utilisez la collaboration multi-agents avec Amazon Bedrock Agents .
- La agentCollaborationInvocationInput structure est la suivante :
```
{
  "agentCollaboratorName": "string",
  "agentCollaboratorAliasArn": "string",
  "input": {
      "text": "string"           
     }
  }                                             
```
  Voici la description des champs :
  - agentCollaboratorName— Le nom de l'agent collaborateur associé à l'agent superviseur.
  - agentCollaboratorAliasArn— L'alias Arn de l'agent collaborateur.
  - input— Chaîne de saisie pour l'agent collaborateur.
actionGroupInvocationInput : apparaît si type correspond à ACTION_GROUP. Pour de plus amples informations, veuillez consulter Définissez les actions dans le groupe d'actions. Il peut s'agir de l'une des structures suivantes :
- Si le groupe d'actions est défini par un schéma d'API, la structure est la suivante :
```
{
    "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"
}
```
  Voici la description des champs :
  - actionGroupName— Le nom du groupe d'actions qui, selon les prévisions de l'agent, doit être invoqué.
  - apiPath— Le chemin d'accès à l'opération d'API à appeler, conformément au schéma de l'API.
  - verb— La méthode d'API utilisée, conformément au schéma de l'API.
  - parameters : contient une liste d’objets. Chaque objet contient le nom, le type et la valeur d'un paramètre de l'opération d'API, tel que défini dans le schéma de l'API.
  - requestBody— Contient le corps de la demande et ses propriétés, tels que définis dans le schéma de l'API.
  - executionType— Si l'exécution de l'action est transmise à une fonction Lambda (LAMBDA) ou si le contrôle est renvoyé via la InvokeAgent réponse (RETURN_CONTROL). Pour de plus amples informations, veuillez consulter Gérer l'exécution de l'action.
  - invocationId— L'identifiant unique de l'invocation. Renvoyé uniquement si executionType c'est le casRETURN_CONTROL.
- Si le groupe d'actions est défini par les détails de la fonction, la structure est la suivante :
```
{
    "actionGroupName": "string",
    "function": "string",
    "parameters": [
        {
            "name": "string",
            "type": "string",
            "value": "string"
        },
        ...
    ],
    "executionType": "LAMBDA | RETURN_CONTROL",
    "invocationId": "string"
}
```
  Voici la description des champs :
  - actionGroupName— Le nom du groupe d'actions qui, selon les prévisions de l'agent, doit être invoqué.
  - function— Le nom de la fonction que l'agent prédit doit être appelée.
  - parameters— Les paramètres de la fonction.
  - executionType— Si l'exécution de l'action est transmise à une fonction Lambda (LAMBDA) ou si le contrôle est renvoyé via la InvokeAgent réponse (RETURN_CONTROL). Pour de plus amples informations, veuillez consulter Gérer l'exécution de l'action.
  - invocationId— L'identifiant unique de l'invocation. Renvoyé uniquement si executionType c'est le casRETURN_CONTROL.
knowledgeBaseLookupInput : apparaît si type correspond à KNOWLEDGE_BASE. Pour de plus amples informations, veuillez consulter Récupérez des données et générez des réponses basées sur l'IA avec les bases de connaissances Amazon Bedrock. Contient les informations suivantes concernant la base de connaissances et la requête de recherche de la base de connaissances :
- knowledgeBaseId : identifiant unique de la base de connaissances que l’agent recherche.
- text : requête envoyée à la base de connaissances.

Observation

L'objet Observation contient le résultat ou la sortie d'un agent collaborateur, d'un groupe d'action ou d'une base de connaissances, ou la réponse à l'utilisateur. Voici la structure :


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

La liste suivante décrit les champs de l'objet Observation :

traceId : identifiant unique de la trace.
type— Spécifie si l'observation de l'agent est renvoyée à partir du résultat d'un agent collaborateur, d'un groupe d'action ou d'une base de connaissances, si l'agent réinvite l'utilisateur, demande plus d'informations ou met fin à la conversation.
agentCollaboratorInvocationOutput— Contient la réponse de l'agent collaborateur ou la réponse finale. Apparaît si le routage type est activé pour l'agent superviseur AGENT_COLLABORATOR et s'il est activé. Pour de plus amples informations, veuillez consulter Utilisez la collaboration multi-agents avec Amazon Bedrock Agents . Chaque réponse contient les champs suivants :
- agentCollaboratorName— Le nom de l'agent collaborateur qui envoie la réponse.
- agentCollaboratorAliasArn— L'alias Arn de l'agent collaborateur qui envoie la réponse.
- output— Contient la réponse envoyée par l'agent collaborateur.
actionGroupInvocationOutput— Contient la chaîne au format JSON renvoyée par l'opération d'API invoquée par le groupe d'actions. Apparaît si type correspond à ACTION_GROUP. Pour de plus amples informations, veuillez consulter Définir OpenAPI schémas pour les groupes d'action de votre agent dans Amazon Bedrock.
knowledgeBaseLookupOutput— Contient du texte extrait de la base de connaissances pertinent pour répondre à l'invite, ainsi que l'emplacement de la source de données sur Amazon S3. Apparaît si type correspond à KNOWLEDGE_BASE. Pour de plus amples informations, veuillez consulter Récupérez des données et générez des réponses basées sur l'IA avec les bases de connaissances Amazon Bedrock. Chaque objet de la liste retrievedReferences contient les champs suivants :
- content : contient du texte (text), extrait de la base de connaissances, renvoyé par la requête de la base de connaissances.
- location— Contient l'URI Amazon S3 de la source de données à partir de laquelle le texte renvoyé a été trouvé.
repromptResponse : apparaît si type correspond à REPROMPT. Contient le texte (text) qui demande à nouveau une invite ainsi que la raison (source) pour laquelle l’agent doit renvoyer une invite.
finalResponse : apparaît si type correspond à ASK_USER ou FINISH. Contient le texte (text) qui demande des informations supplémentaires à l’utilisateur ou qui est une réponse à ce dernier.


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

PostProcessingTraceIl se compose d'un ModelInvocationInputobjet et un PostProcessingModelInvocationOutputobjet. La PostProcessingModelInvocationOutputcontient les champs suivants :

rawResponse— Contient le résultat brut du modèle de base.
- content— Le contenu brut de sortie du modèle de base.
metadata— Contient les informations suivantes concernant la sortie du modèle de base.
- usage— Contient les informations suivantes sur l'utilisation du modèle de base.
  - inputTokens— Contient les informations sur les jetons d'entrée issus de l'utilisation du modèle de base.
  - outputTokens— Contient les informations sur les jetons de sortie issus de l'utilisation du modèle de base.
parsedResponse— Contient le text code à renvoyer à l'utilisateur une fois le texte traité par la fonction d'analyse.
traceId : identifiant unique de la trace.


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

La liste suivante décrit les champs de l'FailureTraceobjet :

failureReason : raison pour laquelle l’étape a échoué.
traceId : identifiant unique de la trace.


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

La liste suivante décrit les champs de l' GuardrailAssessment objet :

action— indique si des garde-corps sont intervenus ou non sur les données d'entrée. Les options sont GUARDRAIL_INTERVENED ouNONE.
inputAssessments— Les détails de l'évaluation Guardrail sur la base des données saisies par l'utilisateur.
outputAssessments— Les détails de l'évaluation de Guardrail sur la réponse.

Pour plus de détails sur l'GuardrailAssessmentobjet et le test d'un garde-corps, voir. Testez un garde-corps

GuardrailAssessment exemple :


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

Avertissement JavaScript est désactivé ou n'est pas disponible dans votre navigateur.

Pour que vous puissiez utiliser la documentation AWS, Javascript doit être activé. Vous trouverez des instructions sur les pages d'aide de votre navigateur.

Conventions de rédaction

Tester et résoudre les problèmes liés au comportement des agents

Afficher le tracé