使用追蹤以追蹤代理程式的逐步推理程序 - Amazon Bedrock
追蹤結構

使用追蹤以追蹤代理程式的逐步推理程序

來自 Amazon Bedrock 代理程式的每個回應都隨附一個追蹤，可詳細說明代理程式正在協調的步驟。追蹤功能幫助您遵循代理程式的推論過程，進而引導其在對話中的該點給出回應。

使用追蹤功能來追蹤從使用者輸入到傳回回應的代理程式路徑。追蹤提供代理程式調用的動作群組輸入，及其查詢以回應使用者的知識庫相關資訊。此外，追蹤會提供動作群組和知識庫傳回之輸出的相關資訊。您可以檢視代理程式用來判斷所採取的動作或對知識庫進行查詢的推論。如果追蹤中的步驟失敗，追蹤會傳回失敗的原因。使用追蹤中的詳細資訊來疑難排解您的代理程式。您可以識別代理程式發生問題或產生意外行為的步驟。然後，您可以使用此資訊來思考改善代理程式的方式。

追蹤結構

如果您啟用追蹤，在 InvokeAgent 回應中，串流中的每個 chunk 都會伴隨一個映射到 TracePart 物件的 trace 欄位。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 內是映射到 Trace 物件的 trace 欄位。追蹤在主控台和 API 中會顯示為 JSON 物件。主控台中的每個步驟或 API 中的 Trace 會是下列其中一個追蹤：

  • PreProcessingTrace — 追蹤預先處理步驟的輸入和輸出，其中代理程式會對使用者輸入進行情境化和分類，並判斷其是否有效。

  • OrchestrationTrace — 追蹤協同運作步驟的輸入和輸出，代理程式會在其中解譯輸入、調用動作群組，及查詢資料庫。然後，代理程式會傳回輸出，以繼續協同運作或回應使用者。

  • PostProcessingTrace — 追蹤後置處理步驟的輸入與輸出，代理程式會在其中處理協同運作過程的最終輸出，並決定如何將回應傳回給使用者。

  • CustomOrchestrationTrace – 詳細介紹自訂協同運作步驟，代理程式使用這些步驟決定執行動作的順序。。

  • RoutingClassifierTrace – 追蹤路由分類器的輸入和輸出

  • FailureTrace — 追蹤步驟失敗的原因。

  • GuardrailTrace – 追蹤 Guardrail 的動作。

每個追蹤 (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 物件的欄位：

如需每個追蹤類型的詳細資訊，請參閱下列各節：

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

PreProcessingTrace 包含 ModelInvocationInput 物件和 PreProcessingModelInvocationOutput 物件。PreProcessingModelInvocationOutput 包含下列欄位。

  • metadata – 包含有關基礎模型輸出的下列資訊。

    • usage – 包含基礎模型用量的下列資訊。

      • inputTokens – 包含來自基礎模型用量之輸入字符的相關資訊。

      • outputTokens – 包含來自基礎模型用量之輸出字符的相關資訊。

  • rawResponse – 包含基礎模型的原始輸出。

    • content – 基礎模型的原始輸出內容。

  • parsedResponse— 包含有關已剖析使用者提示的下列詳細資訊。

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

    • rationale— 指定代理程式的推論，以利於進行下一步。

  • traceId – 追蹤的唯一識別符。

OrchestrationTrace 包含 ModelInvocationInput 物件、OrchestrationModelInvocationOutput 物件，以及 Rationale、InvocationInput 和 Observation 物件的任何組合。OrchestrationModelInvocationOutput 包含下列欄位。如需 Rationale、InvocationInput 和 Observation 物件的詳細資訊，請選取下列索引標籤。

{
    "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 代理程式使用多代理協同作業 。

    • 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

Observation 物件包含代理程式協作者、動作群組或知識庫的結果或輸出，或對使用者的回應。以下是結構：

{
    "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 代理程式使用多代理協同作業 。每個回應均包含下列欄位：

    • agentCollaboratorName – 傳送回應的協作者代理程式名稱。

    • agentCollaboratorAliasArn – 傳送回應的協作者代理程式其別名 Arn。

    • output – 包含協作者代理程式傳送的回應。

  • actionGroupInvocationOutput – 包含動作群組調用之 API 操作傳回的 JSON 格式字串。如果 type 是 ACTION_GROUP，則會顯示。如需詳細資訊，請參閱 在 Amazon Bedrock 中為代理程式的動作群組定義 OpenAPI 結構描述。

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

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

PostProcessingTrace 包含 ModelInvocationInput 物件和 PostProcessingModelInvocationOutput 物件。PostProcessingModelInvocationOutput 包含下列欄位：

  • rawResponse – 包含基礎模型的原始輸出。

    • content – 基礎模型的原始輸出內容。

  • metadata – 包含有關基礎模型輸出的下列資訊。

    • usage – 包含基礎模型用量的下列資訊。

      • inputTokens – 包含來自基礎模型用量之輸入字符的相關資訊。

      • outputTokens – 包含來自基礎模型用量之輸出字符的相關資訊。

  • parsedResponse – 包含剖析器函數處理文字後要傳回給使用者的 text。

  • traceId – 追蹤的唯一識別符。

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

下列清單描述 FailureTrace 物件的欄位：

  • failureReason— 步驟失敗的原因。

  • traceId – 追蹤的唯一識別符。

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