トレースを使用してエージェントのステップバイステップの推論プロセスを追跡する - 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 — 後処理ステップの入力と出力をトレースします。このステップでは、エージェントがオーケストレーションの最終出力を処理し、レスポンスをユーザーに返す方法を決定します。

  • 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 オブジェクトのフィールドについて説明します。

各トレースタイプの詳細は、以下のセクションを参照してください。

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