トレースを使用してエージェントの推論プロセスを追跡する step-by-step

Amazon Bedrock エージェントからの各レスポンスには、エージェントによってオーケストレーションされるステップの詳細を示すトレースが伴います。トレースにより、エージェントが会話のその時点で返すレスポンスに至るまでの推論プロセスを追跡できます。

トレースを使用して、ユーザー入力からレスポンスを返すまでの、エージェントのパスを追跡します。トレースは、エージェントが呼び出すアクショングループへの入力と、ユーザーに応答するためにクエリするナレッジベースに関する情報を提供します。さらに、トレースは、アクショングループとナレッジベースが返す出力に関する情報を提供します。エージェントが実行するアクションやナレッジベースに対して行うクエリを決定するために使用する推論を確認できます。トレースのステップが失敗した場合、トレースは失敗の理由を返します。トレースの詳細な情報を使用して、エージェントのトラブルシューティングを行います。エージェントに問題が発生したり、予期しない動作が発生したりするステップを特定できます。次に、この情報を使用して、エージェントの動作を改善できる方法を検討できます。

トレースの構造

トレースは、コンソールとの両方でJSONオブジェクトとして表示されますAPI。コンソールまたはの各ステップ Trace のは、次のいずれかのトレースAPIになります。

PreProcessingTrace – 前処理ステップの入出力をトレースします。この場合、エージェントはユーザー入力をコンテキスト化して分類し、有効かどうかを判断します。
OrchestrationTrace – エージェントが入力を解釈し、アクショングループを呼び出し、ナレッジベースをクエリするオーケストレーションステップの入出力をトレースします。次に、エージェントはオーケストレーションを継続するか、ユーザーに応答するために出力を返します。
PostProcessingTrace – 後処理ステップの入力と出力をトレースします。このステップでは、エージェントがオーケストレーションの最終出力を処理し、ユーザーにレスポンスを返す方法を決定します。
FailureTrace – ステップが失敗した理由をトレースします。
GuardrailTrace – Guardrail のアクションをトレースします。

各トレース ( を除くFailureTrace) には、 ModelInvocationInput オブジェクト。ModelInvocationInput オブジェクトには、このステップのプロンプトテンプレートで設定された設定と、このステップでエージェントに提供されるプロンプトが含まれています。プロンプトテンプレートを変更する方法の詳細については、「」を参照してくださいAmazon Bedrock の高度なプロンプトテンプレートを使用してエージェントの精度を向上させる。ModelInvocationInput オブジェクトの構造は次のとおりです。


{
    "traceId": "string",
    "text": "string",
    "type": "PRE_PROCESSING | ORCHESTRATION | KNOWLEDGE_BASE_RESPONSE_GENERATION | POST_PROCESSING",
    "inferenceConfiguration": {
        "maximumLength": number,
        "stopSequences": ["string"],
        "temperature": float,
        "topK": float,
        "topP": float
    },
    "promptCreationMode": "DEFAULT | OVERRIDDEN",
    "parserMode": "DEFAULT | OVERRIDDEN",
    "overrideLambda": "string"
}

次のリストは、のフィールドについて説明しています。 ModelInvocationInput オブジェクト：

traceId - トレースの一意な識別子。
text - このステップでエージェントに提供されたプロンプトのテキスト。
type - エージェントのプロセスの現在のステップ。
inferenceConfiguration - レスポンス生成に影響する推論パラメータ。詳細については、「推論パラメータによる影響レスポンスの生成」を参照してください。
promptCreationMode – このステップでエージェントのデフォルトのベースプロンプトテンプレートが上書きされたかどうか。詳細については、「Amazon Bedrock の高度なプロンプトテンプレートを使用してエージェントの精度を向上させる」を参照してください。
parserMode – このステップでエージェントのデフォルトのレスポンスパーサーがオーバーライドされたかどうか。詳細については、「Amazon Bedrock の高度なプロンプトテンプレートを使用してエージェントの精度を向上させる」を参照してください。
overrideLambda – デフォルトのパーサーが上書きされた場合にレスポンスを解析するために使用されるパーサー Lambda 関数の Amazon リソースネーム (ARN）。詳細については、「Amazon Bedrock の高度なプロンプトテンプレートを使用してエージェントの精度を向上させる」を参照してください。

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


{
    "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 – 基盤モデルからの raw 出力が含まれます。
- content – 基盤モデルの raw 出力コンテンツ。
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": { ... }
}

Rationale

Rationale オブジェクトには、ユーザー入力を指定したエージェントの推論が含まれます。構造は次のとおりです。


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

次のリストは、根拠オブジェクトのフィールドについて説明しています。

traceId - トレースのステップの一意な識別子。
text – 入力プロンプトに基づくエージェントの推論プロセス。

InvocationInput

InvocationInput オブジェクトには、呼び出しまたはクエリするアクショングループまたはナレッジベースに入力される情報が含まれます。構造は次のとおりです。


{
    "traceId": "string",
    "invocationType": "ACTION_GROUP | KNOWLEDGE_BASE | FINISH",
    "actionGroupInvocationInput": {
        // see below for details
    },
    "knowledgeBaseLookupInput": {
        "knowledgeBaseId": "string",
        "text": "string"
    }
}

次のリストは、 InvocationInput オブジェクトのフィールドについて説明しています。

traceId - トレースの一意な識別子。
invocationType – エージェントがアクショングループまたはナレッジベースを呼び出すか、セッションを終了するかを指定します。
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 の場合に表示されます。詳細については、「ナレッジベースを使用してデータを取得し、AI レスポンスを生成する」を参照してください。ナレッジベースとナレッジベースの検索クエリに関する以下の情報が含まれます。
- knowledgeBaseId - エージェントが検索するナレッジベースの一意の識別子。
- text - ナレッジベースに対して実行されるクエリ。

Observation

オブザベーションオブジェクトには、アクショングループまたはナレッジベースの結果または出力、またはユーザーへのレスポンスが含まれます。構造は次のとおりです。


{
    "traceId": "string",
    "type": "ACTION_GROUP | KNOWLEDGE_BASE | REPROMPT | ASK_USER | FINISH",
    "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"
    }
}

次のリストは、オブザベーションオブジェクトのフィールドについて説明しています。

traceId - トレースの一意な識別子。
type – エージェントがユーザーに再プロンプトする場合、詳細情報をリクエストする場合、または会話を終了する場合、アクショングループまたはナレッジベースの結果からエージェントの観察結果が返されるかどうかを指定します。
actionGroupInvocationOutput – アクショングループによって呼び出された API オペレーションによって返された JSON形式の文字列が含まれます。type が ACTION_GROUP の場合に表示されます。詳細については、「定義 OpenAPI Amazon Bedrock でのエージェントのアクショングループのスキーマ」を参照してください。
knowledgeBaseLookupOutput – データソースの Amazon S3 の場所とともに、プロンプトへの応答に関連するナレッジベースから取得したテキストが含まれます。type が KNOWLEDGE_BASE の場合に表示されます。詳細については、「ナレッジベースを使用してデータを取得し、AI レスポンスを生成する」を参照してください。のリスト内の各オブジェクトには、次のフィールドretrievedReferencesが含まれます。
- content – ナレッジベースクエリから返されたナレッジベースの text が含まれます。
- location – 返されたテキストが見つかったデータソースURIの Amazon S3 が含まれます。
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 – 基盤モデルからの raw 出力が含まれます。
- content – 基盤モデルの raw 出力コンテンツ。
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 – ユーザー入力の Guardrail 評価の詳細。
outputAssessments – レスポンスの Guardrail 評価の詳細。

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

ブラウザで JavaScript が無効になっているか、使用できません。

AWS ドキュメントを使用するには、JavaScript を有効にする必要があります。手順については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

エージェント動作のテストとトラブルシューティング

トレースを表示する