Realice un seguimiento del proceso de step-by-step razonamiento del agente mediante trace - Amazon Bedrock
Estructura del seguimiento

Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

Realice un seguimiento del proceso de step-by-step razonamiento del agente mediante trace

Cada respuesta de un agente de Amazon Bedrock va acompañada de un seguimiento que le permite detallar los pasos que está orquestando el agente. El seguimiento le ayuda a seguir el proceso de razonamiento del agente que lo lleva a la respuesta que da en ese momento de la conversación.

Utilice el seguimiento para rastrear la ruta del agente desde la entrada del usuario hasta la respuesta que devuelve. El seguimiento proporciona información sobre las entradas de los grupos de acciones que invoca el agente y las bases de conocimientos que consulta para responder al usuario. Además, el seguimiento proporciona información sobre los resultados que devuelven los grupos de acción y las bases de conocimientos. Puede ver el razonamiento que utiliza el agente para determinar la acción que lleva a cabo o la consulta que realiza a una base de conocimientos. Si se produce un error en un paso del seguimiento, el seguimiento devuelve el motivo del error. Utilice la información detallada del seguimiento para solucionar los problemas del agente. Puede identificar los pasos en los que el agente tiene problemas o en los que genera un comportamiento inesperado. A continuación, puede utilizar esta información para considerar formas de mejorar el comportamiento del agente.

Estructura del seguimiento

Si habilita el rastreo, en el InvokeAgentrespuesta, cada chunk elemento de la secuencia va acompañado de un trace campo que se asigna a un TracePartobjeto. El tracePart objeto contiene información sobre el agente y las sesiones, junto con el proceso de razonamiento del agente, y es el resultado de API las funciones de llamada. 

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

La siguiente lista describe los campos de TracePartobjeto:

  • agentId— El identificador único del agente.

  • agentName— El nombre del agente.

  • collaboratorName— Si la colaboración entre varios agentes está habilitada, el nombre del agente colaborador.

  • agentVersion— La versión del agente.

  • agentAliasId— El identificador único del alias del agente.

  • sessionId— El identificador único de la sesión con el agente.

  • trace— Contiene el proceso de razonamiento del agente y los resultados de la convocatoria de API acciones. Para obtener más información, consulte las secciones siguientes.

  • callerChain— Lista de personas que llamaron entre el agente que publicó este rastreo y el usuario final.

    • Si se trata de un solo agente, este campo contendrá el alias Arn del mismo agente que publicó el rastreo.

    • Si la colaboración entre varios agentes está habilitada, este campo contendrá el alias Arn de todos los agentes que reenviaron la solicitud del usuario final al agente actual.

Dentro del TracePartes un trace campo que se asigna a un Traceobjeto. La traza se muestra como un JSON objeto tanto en la consola como en laAPI. Cada paso de la consola o Traceen el API puede haber una de las siguientes trazas:

  • PreProcessingTrace— Rastrea la entrada y la salida del paso de preprocesamiento, en el que el agente contextualiza y categoriza la entrada del usuario y determina si es válida.

  • OrchestrationTrace— Rastrea la entrada y la salida del paso de orquestación, en el que el agente interpreta la entrada, invoca grupos de acción y consulta las bases de conocimiento. A continuación, el agente devuelve la salida para continuar con la orquestación o para responder al usuario.

  • PostProcessingTrace— Realiza un seguimiento de las entradas y salidas del paso de posprocesamiento, en el que el agente gestiona el resultado final de la orquestación y determina cómo devolver la respuesta al usuario.

  • FailureTrace— Rastrea el motivo por el que se ha producido un error en un paso.

  • GuardrailTrace— Rastrea las acciones de la barandilla.

Cada uno de los trazos (exceptoFailureTrace) contiene un ModelInvocationInputobjeto. Con la ModelInvocationInputel objeto contiene las configuraciones establecidas en la plantilla de solicitud del paso, junto con la solicitud proporcionada al agente en este paso. Para obtener más información acerca de cómo modificar las plantillas de peticiones, consulte Mejora de la precisión del agente con plantillas de peticiones avanzadas en Amazon Bedrock. La estructura del objeto ModelInvocationInput es la siguiente:

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

En la siguiente lista se describen los campos del ModelInvocationInputobjeto:

Para obtener más información acerca de cada tipo de seguimiento, consulte las secciones siguientes:

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

Se compone de un PreProcessingTraceModelInvocationInputobjeto y un PreProcessingModelInvocationOutputobjeto. Con la PreProcessingModelInvocationOutputcontiene los siguientes campos.

  • metadata: contiene la siguiente información acerca del resultado del modelo fundacional.

    • usage: contiene la siguiente información acerca del uso del modelo fundacional.

      • inputTokens: contiene la información sobre los tokens de entrada del uso del modelo fundacional.

      • outputTokens: contiene la información sobre los tokens de salida del uso del modelo fundacional.

  • rawResponse: contiene la salida sin procesar del modelo fundacional.

    • content: es el contenido de salida sin procesar del modelo fundacional.

  • parsedResponse: contiene los siguientes detalles sobre la petición del usuario analizada.

    • isValid: especifica si la petición del usuario es válida.

    • rationale: especifica el razonamiento del agente sobre los siguientes pasos que tomar.

  • traceId: el identificador único del seguimiento.

Se OrchestrationTracecompone de ModelInvocationInputobjeto, OrchestrationModelInvocationOutputobjeto y cualquier combinación de los objetos Rationale InvocationInputy Observation. Con la OrchestrationModelInvocationOutputcontiene los siguientes campos. Para obtener más información sobre los objetos Rationale y Observation, seleccione una de las siguientes pestañas. InvocationInput 

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

Si el enrutamiento type está habilitado para el agente supervisor AGENT_COLLABORATOR y si lo estaba, OrchestrationModelInvocationOutputcontendrá la siguiente estructura:

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

El objeto Rationale contiene el razonamiento del agente según la información proporcionada por el usuario. La estructura es la siguiente:

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

En la siguiente lista se describen los campos del objeto Rationale:

  • traceId: el identificador único del paso de seguimiento.

  • text: es el proceso de razonamiento del agente, basado en la petición de entrada.

InvocationInput

El objeto InvocationInput contiene información que se introducirá en el grupo de acción o en la base de conocimientos que se va a invocar o consultar. La estructura es la siguiente:

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

En la siguiente lista se describen los campos del objeto InvocationInput:

  • traceId: el identificador único del seguimiento.

  • invocationType— Especifica si el agente invoca a un agente colaborador, a un grupo de acción o a una base de conocimientos, o si finaliza la sesión.

  • agentCollaborationInvocationInput— Contiene la entrada de invocación para los agentes colaboradores. Aparece si el enrutamiento type está activado AGENT_COLLABORATOR y si está activado para el agente supervisor. Para obtener más información, consulte Utilice la colaboración entre varios agentes con Amazon Bedrock Agents .

    • La agentCollaborationInvocationInput estructura es la siguiente:

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

      A continuación, se indican las descripciones de los campos:

      • agentCollaboratorName— El nombre del agente colaborador asociado al agente supervisor.

      • agentCollaboratorAliasArn— El alias Arn del agente colaborador.

      • input— La cadena de entrada del agente colaborador.

  • actionGroupInvocationInput: aparece si el type es ACTION_GROUP. Para obtener más información, consulte Definición de acciones en el grupo de acciones. Puede ser una de las siguientes estructuras:

    • Si el grupo de acciones está definido por un API esquema, la estructura es la siguiente:

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

      A continuación, se indican las descripciones de los campos:

      • actionGroupName: es el nombre del grupo de acciones que el agente predice que debería invocarse.

      • apiPath— La ruta a la API operación a la que se va a llamar, según el API esquema.

      • verb— El API método que se utiliza, según el API esquema.

      • parameters: contiene una lista de objetos. Cada objeto contiene el nombre, el tipo y el valor de un parámetro de la API operación, tal como se define en el API esquema.

      • requestBody— Contiene el cuerpo de la solicitud y sus propiedades, tal y como se definen en el API esquema.

      • executionType: si el cumplimiento de la acción se transfiere a una función de Lambda (LAMBDA) o si el control se devuelve a través de la respuesta de InvokeAgent (RETURN_CONTROL). Para obtener más información, consulte Gestión del cumplimiento de la acción.

      • invocationId: es el identificador único de la invocación. Solo se devuelve si el executionType es RETURN_CONTROL.

    • Si el grupo de acciones se define por los detalles de la función, la estructura es la siguiente:

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

      A continuación, se indican las descripciones de los campos:

      • actionGroupName: es el nombre del grupo de acciones que el agente predice que debería invocarse.

      • function: es el nombre de la función que el agente predice que se debería llamar.

      • parameters: son los parámetros de la función.

      • executionType: si el cumplimiento de la acción se transfiere a una función de Lambda (LAMBDA) o si el control se devuelve a través de la respuesta de InvokeAgent (RETURN_CONTROL). Para obtener más información, consulte Gestión del cumplimiento de la acción.

      • invocationId: es el identificador único de la invocación. Solo se devuelve si el executionType es RETURN_CONTROL.

  • knowledgeBaseLookupInput: aparece si el type es KNOWLEDGE_BASE. Para obtener más información, consulte Recupere datos y genere respuestas de IA con las bases de conocimiento de Amazon Bedrock. Contiene la siguiente información sobre la base de conocimientos y la consulta de búsqueda de la base de conocimientos:

    • knowledgeBaseId: el identificador único de la base de conocimientos que el agente va a buscar.

    • text: la consulta que se debe realizar a la base de conocimientos.

Observation

El objeto Observation contiene el resultado o la salida de un agente colaborador, un grupo de acción o una base de conocimientos, o la respuesta al usuario. La estructura es la siguiente:

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

En la siguiente lista se describen los campos del objeto Observation:

  • traceId: el identificador único del seguimiento.

  • type— Especifica si la observación del agente proviene del resultado de un agente colaborador, un grupo de acción o una base de conocimientos, si el agente vuelve a preguntar al usuario, solicita más información o finaliza la conversación.

  • agentCollaboratorInvocationOutput— Contiene la respuesta del agente colaborador o la respuesta final. Aparece si el enrutamiento type está activado para el agente supervisor AGENT_COLLABORATOR y si está activado. Para obtener más información, consulte Utilice la colaboración entre varios agentes con Amazon Bedrock Agents . Cada respuesta contiene los siguientes campos:

    • agentCollaboratorName— El nombre del agente colaborador que envía la respuesta.

    • agentCollaboratorAliasArn— El alias Arn del agente colaborador que envía la respuesta.

    • output— Contiene la respuesta enviada por el agente colaborador.

  • actionGroupInvocationOutput— Contiene la cadena JSON con formato -devuelta por la API operación que fue invocada por el grupo de acciones. Aparece si el type es ACTION_GROUP. Para obtener más información, consulte Definir OpenAPI esquemas para los grupos de acción de su agente en Amazon Bedrock.

  • knowledgeBaseLookupOutput: contiene el texto recuperado de la base de conocimientos que sea relevante para responder a la petición, junto con la ubicación en Amazon S3 del origen de datos. Aparece si el type es KNOWLEDGE_BASE. Para obtener más información, consulte Recupere datos y genere respuestas de IA con las bases de conocimiento de Amazon Bedrock. Cada objeto de la lista de retrievedReferences contiene los siguientes campos:

    • content: contiene el text de la base de conocimientos que se devuelve de la consulta de la base de conocimientos.

    • location— Contiene el Amazon S3 URI de la fuente de datos en la que se encontró el texto devuelto.

  • repromptResponse: aparece si el type es REPROMPT. Contiene el text que solicita una nueva petición junto con el source de por qué el agente necesita volver a solicitarlo.

  • finalResponse: aparece si el type es ASK_USER o FINISH. Contiene el text que solicita al usuario más información o es una respuesta al usuario.

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

Se PostProcessingTracecompone de un ModelInvocationInputobjeto y un PostProcessingModelInvocationOutputobjeto. Con la PostProcessingModelInvocationOutputcontiene los siguientes campos:

  • rawResponse: contiene la salida sin procesar del modelo fundacional.

    • content: es el contenido de salida sin procesar del modelo fundacional.

  • metadata: contiene la siguiente información acerca del resultado del modelo fundacional.

    • usage: contiene la siguiente información acerca del uso del modelo fundacional.

      • inputTokens: contiene la información sobre los tokens de entrada del uso del modelo fundacional.

      • outputTokens: contiene la información sobre los tokens de salida del uso del modelo fundacional.

  • parsedResponse: contiene el text que se devuelve al usuario tras ser procesado por la función del analizador.

  • traceId: el identificador único del seguimiento.

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

En la siguiente lista se describen los campos del objeto FailureTrace:

  • failureReason: el motivo por el que el paso falló.

  • traceId: el identificador único del seguimiento.

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

La siguiente lista describe los campos del GuardrailAssessment objeto:

  • action: indica si las barreras de protección han intervenido o no en los datos de entrada. Las opciones son GUARDRAIL_INTERVENED y NONE.

  • inputAssessments: son los detalles de la evaluación de la barrera de protección de la entrada del usuario.

  • outputAssessments: son los detalles de la evaluación de la barrera de protección en la respuesta.

Para obtener más información sobre el objeto GuardrailAssessment y sobre las pruebas de una barrera de protección, consulte Prueba de una barrera de protección.

GuardrailAssessment ejemplo:

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