Suivi du processus de raisonnement étape par étape de l’agent à l’aide de la trace - Amazon Bedrock
Structure de la trace

Suivi du processus de raisonnement étape par étape de l’agent à l’aide de la trace

Chaque réponse d’un agent Amazon Bedrock est accompagnée d’une trace qui détaille les étapes qu’il a orchestrées. 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 consulte pour répondre à l’utilisateur. En outre, la trace fournit des informations sur les sorties renvoyées 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 la trace, dans la réponse InvokeAgent, chaque chunk du flux est accompagné d’un champ trace qui est mappé à un objet TracePart. L’objet tracePart 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 d’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 l’objet TracePart :

  • agentId : identifiant unique de l’agent.

  • agentName : nom de l’agent.

  • collaboratorName : si la collaboration multi-agent est activée, nom de l’agent collaborateur.

  • agentVersion : version de l’agent.

  • agentAliasId : identifiant unique de l’alias de l’agent.

  • sessionId : identifiant unique de la session avec l’agent.

  • trace : contient le processus de raisonnement de l’agent et les résultats de l’appel des 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’ARN d’alias du même agent qui a publié la trace.

    • Si la collaboration multi-agent est activée, ce champ contiendra l’ARN d’alias de tous les agents qui ont transmis la demande d’utilisateur final à l’agent actuel.

Dans TracePart figure un champ trace qui est mappé à un objet Trace. La trace est affichée sous forme d’objet JSON à la fois dans la console et dans l’API. Chaque Étape de la console ou Trace de l’API peut être 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 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 les 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.

  • CustomOrchestrationTrace : détails sur l’étape d’orchestration personnalisée au cours de laquelle l’agent détermine l’ordre dans lequel les actions sont exécutées.

  • RoutingClassifierTrace : trace l’entrée et la sortie du classificateur de routage

  • FailureTrace : détermine la raison pour laquelle une étape a échoué.

  • GuardrailTrace : trace les actions de la barrière de protection.

Chacune des traces (sauf FailureTrace) contient un objet ModelInvocationInput. L’objet ModelInvocationInput contient les configurations définies dans le modèle d’invite de l’étape, en plus de l’invite fournie à l’agent à cette étape. Pour plus d’informations sur la modification des modèles d’invite, consultez Amélioration de la précision des agents à l’aide de modèles d’invite avancés dans Amazon Bedrock. La structure de l’objet ModelInvocationInput 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 de l’objet ModelInvocationInput :

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

PreProcessingTrace se compose d’un objet ModelInvocationInput et d’un objet PreProcessingModelInvocationOutput. PreProcessingModelInvocationOutput contient les champs suivants.

  • metadata : contient les informations suivantes sur la sortie du modèle de fondation.

    • usage : contient les informations suivantes sur l’utilisation du modèle de fondation.

      • inputTokens : contient les informations sur les jetons d’entrée issus de l’utilisation du modèle de fondation.

      • outputTokens : contient les informations sur les jetons de sortie issus de l’utilisation du modèle de fondation.

  • rawResponse : contient la sortie brute du modèle de fondation.

    • content : contenu de la sortie brute du modèle de fondation.

  • 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.

OrchestrationTrace comprend l’objet ModelInvocationInput, l’objet OrchestrationModelInvocationOutput et toute combinaison des objets Rationale, InvocationInput et Observation. OrchestrationModelInvocationOutput contient les champs suivants. Pour plus d’informations sur les objets Rationale, InvocationInput 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 a la valeur AGENT_COLLABORATOR et si le routage a été activé pour l’agent superviseur, OrchestrationModelInvocationOutput contiendra la structure suivante :

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

L’objet Rationale contient le raisonnement de l’agent en fonction de l’entrée 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 : processus de raisonnement de l’agent, basé sur l’invite d’entrée.

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’objet InvocationInput :

  • traceId : identifiant unique de la trace.

  • invocationType : spécifie si l’agent invoque un agent collaborateur, un groupe d’actions ou une base de connaissances, ou encore s’il met fin à la session.

  • agentCollaborationInvocationInput : contient l’entrée d’invocation destinée aux agents collaborateurs. Apparaît si type a la valeur AGENT_COLLABORATOR et si le routage est activé pour l’agent superviseur est activé. Pour plus d’informations, consultez Utilisation de la collaboration multi-agent avec les agents Amazon Bedrock .

    • La structure agentCollaborationInvocationInput se présente comme suit :

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

      Voici les descriptions des champs :

      • agentCollaboratorName : nom de l’agent collaborateur associé à l’agent superviseur.

      • agentCollaboratorAliasArn : ARN d’alias de l’agent collaborateur.

      • input : chaîne d’entrée pour l’agent collaborateur.

  • actionGroupInvocationInput : apparaît si type correspond à ACTION_GROUP. Pour plus d’informations, consultez Définition des actions dans le groupe d’actions. Peut être 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 les descriptions des champs :

      • actionGroupName : nom du groupe d’actions que l’agent prévoit d’invoquer.

      • apiPath : chemin d’accès à l’opération d’API à appeler, en fonction du schéma d’API.

      • verb : méthode d’API utilisée, en fonction du schéma d’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 d’API.

      • requestBody : contient le corps de la demande et ses propriétés, tels que définis dans le schéma d’API.

      • executionType : si l’exécution de l’action est transmise à une fonction Lambda (LAMBDA) ou si le contrôle est renvoyé via la réponse InvokeAgent (RETURN_CONTROL). Pour plus d’informations, consultez Gestion de l’exécution de l’action.

      • invocationId : identifiant de la demande d’invocation. Renvoyé uniquement si executionType a la valeur RETURN_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 les descriptions des champs :

      • actionGroupName : nom du groupe d’actions que l’agent prévoit d’invoquer.

      • function : nom de la fonction que l’agent prévoit d’appeler.

      • parameters : 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 réponse InvokeAgent (RETURN_CONTROL). Pour plus d’informations, consultez Gestion de l’exécution de l’action.

      • invocationId : identifiant de la demande d’invocation. Renvoyé uniquement si executionType a la valeur RETURN_CONTROL.

  • knowledgeBaseLookupInput : apparaît si type correspond à KNOWLEDGE_BASE. Pour plus d’informations, consultez Récupération de données et génération de réponses basées sur l’IA avec Amazon Bedrock Knowledge Bases. Contient les informations suivantes sur 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’actions 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’actions ou d’une base de connaissances, ou si l’agent renvoie une nouvelle 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 type a la valeur AGENT_COLLABORATOR et si le routage est activé pour l’agent superviseur est activé. Pour plus d’informations, consultez Utilisation de la collaboration multi-agent avec les agents Amazon Bedrock . Chaque réponse contient les champs suivants :

    • agentCollaboratorName : nom de l’agent collaborateur qui envoie la réponse.

    • agentCollaboratorAliasArn : ARN d’alias 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 qui a été invoquée par le groupe d’actions. Apparaît si type correspond à ACTION_GROUP. Pour plus d’informations, consultez Définition de schémas OpenAPI pour les groupes d’actions de l’agent dans Amazon Bedrock.

  • knowledgeBaseLookupOutput : contient du texte pertinent, extrait de la base de connaissances, pour répondre à l’invite, ainsi que l’emplacement Amazon S3 de la source de données. Apparaît si type correspond à KNOWLEDGE_BASE. Pour plus d’informations, consultez Récupération de données et génération de réponses basées sur l’IA avec Amazon Bedrock Knowledge Bases. 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"
    }
}

PostProcessingTrace se compose d’un objet ModelInvocationInput et d’un objet PostProcessingModelInvocationOutput. PostProcessingModelInvocationOutput comporte les champs suivants :

  • rawResponse : contient la sortie brute du modèle de fondation.

    • content : contenu de la sortie brute du modèle de fondation.

  • metadata : contient les informations suivantes sur la sortie du modèle de fondation.

    • usage : contient les informations suivantes sur l’utilisation du modèle de fondation.

      • inputTokens : contient les informations sur les jetons d’entrée issus de l’utilisation du modèle de fondation.

      • outputTokens : contient les informations sur les jetons de sortie issus de l’utilisation du modèle de fondation.

  • parsedResponse : contient le texte (text) à renvoyer à l’utilisateur après son traitement par la fonction d’analyse.

  • traceId : identifiant unique de la trace.

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

La liste suivante décrit les champs de l’objet FailureTrace :

  • 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’objet GuardrailAssessment :

  • action : indique si des barrières de protection sont intervenues ou non sur les données d’entrée. Les options sont GUARDRAIL_INTERVENED ou NONE.

  • inputAssessments : détails de l’évaluation des barrières de protection sur l’entrée utilisateur.

  • outputAssessments : détails de l’évaluation des barrières de protection sur la réponse.

Pour plus de détails sur l’objet GuardrailAssessment et le test d’une barrière de protection, consultez Test de votre barrière de protection.

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