使用跟踪跟踪代理的 step-by-step推理过程

来自 Amazon Bedrock 代理的每个响应都附有跟踪记录，其中详细说明了由代理编排的步骤。跟踪记录可以帮助您跟踪代理的推理过程，该过程可引导它做出它当时在对话中做出的响应。

使用跟踪记录来跟踪代理从用户输入到它返回的响应的路径。跟踪记录提供有关代理为响应用户而调用的操作组以及查询的知识库的输入的信息。此外，跟踪记录还提供有关操作组和知识库返回的输出的信息。您可以查看代理用来确定其采取的操作或对知识库的查询的推理。如果跟踪中的某个步骤失败，则跟踪功能会返回失败的原因。使用跟踪中的详细信息对代理执行故障排除。您可以确定代理在哪些步骤中遇到问题或在哪些步骤中产生意外行为。然后，您可以利用此信息来考虑如何改善代理的行为。

跟踪的结构

如果您启用跟踪，请在 InvokeAgentresponse，流chunk中的每一个都附带一个映射到的trace字段 TracePart对象。该tracePart对象包含有关代理和会话的信息，以及代理的推理过程和调用 API 函数的结果。

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

以下列表描述了以下字段 TracePart对象：

• agentId— 代理的唯一标识符。

• agentName— 代理的名字。

• collaboratorName— 如果启用了多代理协作，则为协作者代理的名称。

• agentVersion— 代理的版本。

• agentAliasId— 代理别名的唯一标识符。

• sessionId— 与代理会话的唯一标识符。

• trace— 包含代理的推理过程和调用 API 操作的结果。有关更多信息，请参阅下文。

• callerChain— 发布此跟踪的代理和最终用户之间的呼叫者列表。

  • 如果是单个代理，则此字段将包含发布跟踪的同一个代理的别名 Arn。

  • 如果启用了多代理协作，则此字段将包含将最终用户请求转发给当前代理的所有代理的别名 Arn。

在里面 TracePart是一个映射到 a 的trace字段 Trace对象。跟踪在控制台和 API 中均以 JSON 对象的形式显示。控制台中的每个步骤或 TraceAPI 中可以是以下轨迹之一：

• PreProcessingTrace— 跟踪预处理步骤的输入和输出，在该步骤中，代理对用户输入进行情境化和分类，并确定其是否有效。

• OrchestrationTrace— 跟踪协调步骤的输入和输出，在该步骤中，代理解释输入、调用操作组和查询知识库。然后，代理会返回输出以继续编排或响应用户。

• PostProcessingTrace— 跟踪后处理步骤的输入和输出，在该步骤中，代理处理编排的最终输出并确定如何将响应返回给用户。

• FailureTrace— 追踪步骤失败的原因。

• GuardrailTrace— 追踪护栏的动作。

每条痕迹（除外FailureTrace）都包含一个 ModelInvocationInput对象。这些区域有：ModelInvocationInput对象包含在该步骤的提示模板中设置的配置，以及在此步骤中向代理提供的提示。有关如何修改提示模板的更多信息，请参阅使用 Amazon Bedrock 中的高级提示模板提高代理的准确性。ModelInvocationInput 对象的结构如下所示：

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

以下列表描述了的字段 ModelInvocationInput对象：

• traceId – 跟踪的唯一标识符。

• text – 在相应步骤中向代理提供的提示文本。

• type – 代理过程的当前步骤。

• foundationModel— 多代理协作中协作代理的基础模型。仅当为时，才会填充此字段ROUTING_CLASSIFIER。type如果用于路由提示的默认模型被覆盖，则此字段将显示用于路由提示符的主管代理的模型。

• inferenceConfiguration – 影响响应生成的推理参数。有关更多信息，请参阅 利用推理参数影响响应生成。

• promptCreationMode – 相应步骤中代理的默认基本提示模板是否被覆盖。有关更多信息，请参阅 使用 Amazon Bedrock 中的高级提示模板提高代理的准确性。

• parserMode – 相应步骤中代理的默认响应解析器是否被覆盖。有关更多信息，请参阅 使用 Amazon Bedrock 中的高级提示模板提高代理的准确性。

• overrideLambda – 在默认解析器被覆盖的情况下，用于解析响应的解析器 Lambda 函数的 Amazon 资源名称（ARN）。有关更多信息，请参阅 使用 Amazon Bedrock 中的高级提示模板提高代理的准确性。

有关每个跟踪类型的更多信息，请参阅以下部分：

PreProcessingTrace

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

由 a PreProcessingTrace组成 ModelInvocationInput对象和 PreProcessingModelInvocationOutput对象。这些区域有：PreProcessingModelInvocationOutput包含以下字段。

• metadata – 包含有关基础模型输出的以下信息。

  • usage – 包含有关基础模型使用的以下信息。

    • inputTokens – 包含有关基础模型使用的输入词元的信息。

    • outputTokens – 包含有关基础模型使用的输出词元的信息。

• rawResponse – 包含基础模型的原始输出。

  • content – 基础模型的原始输出内容。

• parsedResponse – 包含已解析的用户提示的以下相关详细信息。

  • isValid – 指定用户提示是否有效。

  • rationale – 用于指定代理对后续行动的推理。

• traceId – 跟踪的唯一标识符。

OrchestrationTrace

由OrchestrationTrace以下部分组成 ModelInvocationInput对象，OrchestrationModelInvocationOutput对象，以及 “基本原理” 和 “观察” 对象的任意组合。InvocationInput这些区域有：OrchestrationModelInvocationOutput包含以下字段。有关 “基本原理” 和 “观测InvocationInput值” 对象的更多信息，请从以下选项卡中进行选择。

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

如果type是，AGENT_COLLABORATOR并且已为主管代理启用路由，OrchestrationModelInvocationOutput将包含以下结构：

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

Rationale

Rationale 对象包含在给定用户输入的情况下代理进行的推理。结构如下所示：

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

下面的列表介绍了 Rationale 对象的字段：

• traceId – 跟踪步骤的唯一标识符。

• text – 代理基于输入提示的推理过程。

InvocationInput

InvocationInput 对象包含将输入到要调用或查询的操作组或知识库中的信息。结构如下所示：

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

下面的列表介绍了 InvocationInput 对象的字段：

• traceId – 跟踪的唯一标识符。

• invocationType— 指定代理是在调用协作者代理、操作组或知识库，还是正在结束会话。

• agentCollaborationInvocationInput— 包含协作代理的调用输入。如果type是，AGENT_COLLABORATOR并且已为主管代理启用路由，则会出现。有关更多信息，请参阅 与 Amazon Bedrock Agents 使用多代理协作 。

  • agentCollaborationInvocationInput 结构如下：

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

    以下是对字段的描述：

    • agentCollaboratorName— 与主管代理关联的协作者代理的名称。

    • agentCollaboratorAliasArn— 合作者代理的别名 Arn。

    • input-协作者代理的输入字符串。

• actionGroupInvocationInput – 如果 type 为 ACTION_GROUP，则会显示此字段。有关更多信息，请参阅 在操作组中定义操作。结构可以是以下形式之一：

  • 如果操作组由 API 架构定义，则结构如下所示：

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

    以下是对字段的描述：

    • actionGroupName – 代理预测应调用的操作组的名称。

    • apiPath – 根据 API 架构要调用的 API 操作的路径。

    • verb – 根据 API 架构要使用的 API 方法。

    • parameters – 包含对象列表。每个对象都包含 API 操作中参数的名称、类型和值，如 API 架构中所定义。

    • requestBody – 包含请求正文及其属性，如 API 架构中所定义。

    • executionType – 是将操作的完成传递给 Lambda 函数（LAMBDA），还是通过 InvokeAgent 响应（RETURN_CONTROL）返回控制。有关更多信息，请参阅 操作的完成处理。

    • invocationId – 调用的唯一标识符。仅当 executionType 为 RETURN_CONTROL 时，才返回此字段。

  • 如果操作组由函数详细信息定义，则结构如下所示：

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

    以下是对字段的描述：

    • actionGroupName – 代理预测应调用的操作组的名称。

    • function – 代理预测应调用的函数的名称。

    • parameters – 函数的参数。

    • executionType – 是将操作的完成传递给 Lambda 函数（LAMBDA），还是通过 InvokeAgent 响应（RETURN_CONTROL）返回控制。有关更多信息，请参阅 操作的完成处理。

    • invocationId – 调用的唯一标识符。仅当 executionType 为 RETURN_CONTROL 时，才返回此字段。

• knowledgeBaseLookupInput – 如果 type 为 KNOWLEDGE_BASE，则会显示此字段。有关更多信息，请参阅 使用 Amazon Bedrock 知识库检索数据并生成 AI 响应。包含有关知识库和知识库搜索查询的以下信息：

  • knowledgeBaseId – 代理将查询的知识库的唯一标识符。

  • text – 对知识库的查询。

Observation

O b servation 对象包含代理协作者、操作组或知识库的结果或输出，或者对用户的响应。结构如下所示：

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

下面的列表介绍了 Observation 对象的字段：

• traceId – 跟踪的唯一标识符。

• type— 指定代理的观察结果是从代理协作者、操作组还是知识库的结果中返回，以及代理是否在重新提示用户、请求更多信息或结束对话。

• agentCollaboratorInvocationOutput— 包含协作者代理的响应或最终响应。如果type是，AGENT_COLLABORATOR并且已为主管代理启用路由，则会出现。有关更多信息，请参阅 与 Amazon Bedrock Agents 使用多代理协作 。每个响应都包含以下字段：

  • agentCollaboratorName— 发送响应的协作者代理的名称。

  • agentCollaboratorAliasArn— 发送响应的协作者代理的别名 Arn。

  • output— 包含合作者代理发送的响应。

• actionGroupInvocationOutput – 包含操作组调用的 API 操作返回的 JSON 格式的字符串。如果 type 为 ACTION_GROUP，则显示此字段。有关更多信息，请参阅 定义 OpenAPI Amazon Bedrock 中代理人行动小组的架构。

• knowledgeBaseLookupOutput – 包含从知识库中检索到的与响应提示相关的文本，以及数据来源的 Amazon S3 位置。如果 type 为 KNOWLEDGE_BASE，则显示此字段。有关更多信息，请参阅 使用 Amazon Bedrock 知识库检索数据并生成 AI 响应。retrievedReferences 列表中的每个对象都包含以下字段：

  • content – 包含从知识库查询返回的知识库 text。

  • location – 包含从中找到返回文本的数据来源的 Amazon S3 URI。

• repromptResponse – 如果 type 为 REPROMPT，则会显示此字段。包含要求再次提示的 text，以及代理需要重新提示的原因 source。

• finalResponse – 如果 type 为 ASK_USER 或 FINISH，则会显示此字段。包含要求用户提供更多信息或回应用户的 text。

PostProcessingTrace

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

由 a PostProcessingTrace组成 ModelInvocationInput对象和 PostProcessingModelInvocationOutput对象。这些区域有：PostProcessingModelInvocationOutput包含以下字段：

• rawResponse – 包含基础模型的原始输出。

  • content – 基础模型的原始输出内容。

• metadata – 包含有关基础模型输出的以下信息。

  • usage – 包含有关基础模型使用的以下信息。

    • inputTokens – 包含有关基础模型使用的输入词元的信息。

    • outputTokens – 包含有关基础模型使用的输出词元的信息。

• parsedResponse – 包含在解析器函数处理文本后返回给用户的 text。

• traceId – 跟踪的唯一标识符。

FailureTrace

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

下面的列表介绍了 FailureTrace 对象的字段：

• failureReason – 步骤失败的原因。

• traceId – 跟踪的唯一标识符。

GuardrailTrace

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

以下列表描述了 GuardrailAssessment 对象的字段：

• action – 指示防护机制是否干预了输入数据。选项有 GUARDRAIL_INTERVENED 或 NONE。

• inputAssessments – 针对用户输入进行防护机制评测的详细信息。

• outputAssessments – 针对响应进行防护机制评测的详细信息。

有关 GuardrailAssessment 对象和测试防护机制的更多详细信息，请参阅测试防护机制。

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