View a markdown version of this page

推奨事項 - Amazon Bedrock AgentCore
設定入力モードエージェントトレースソース

推奨事項

推奨事項では、AI を使用して、実際のセッショントレースから最適化されたエージェント設定を生成します。プロンプトやツールの説明を手動で書き換える代わりに、サービスがエージェントのトレースを指し、ターゲット評価者を報酬シグナルとして指定し、最適化された設定を受け取ります。

注記

レコメンデーションは LLMs。適用する前に確認してテストします。

Amazon Bedrock AgentCore は、次の 2 つのレコメンデーションタイプをサポートしています。

  • システムプロンプトの推奨事項: エージェントトレースを分析し、ターゲット評価者のパフォーマンスを向上させる最適化されたシステムプロンプトを生成します。このサービスは障害パターンを識別し、特定の動作指示を追加します。

  • ツールの説明に関する推奨事項: エージェントトレースを分析し、ツール選択の混乱を軽減するための詳細なツールの説明を生成します。これは、エージェントがあいまいなリクエストに対して間違ったツールを選択する場合に便利です。

各レコメンデーションには、最適化する現在のエージェント設定と分析するエージェントトレースの 2 つの入力が必要です。

トピック

設定入力モード

現在の設定は、次の 2 つの方法のいずれかで指定します。

  • インラインテキスト: API リクエストで文字列として設定を直接指定します。システムプロンプトの推奨事項については、 systemPrompt.textフィールドにプロンプトテキストを渡します。ツールの説明に関する推奨事項については、各ツールの名前と説明をtoolDescription.toolDescriptionText.toolsリストに渡します。このモードは、クイック実験、アクティブに繰り返しているプロンプトをテストする場合、または設定がバンドルに保存されていない場合に役立ちます。

    推奨事項の種類 CLI フラグ API フィールド

    システムプロンプト

    --inline "prompt text"、または --prompt-file ./path.txt

    systemPrompt.text

    ツールの説明

    --tools "name:description, name:description"

    toolDescription.toolDescriptionText.tools: toolNameおよび を持つオブジェクトのリスト toolDescription

  • 設定バンドル: 既存の設定バンドルバージョンを参照します。サービスは、指定した JSON パスを使用してバンドルから現在の設定を読み取り、最適化されたバージョンを生成し、その結果を新しいバンドルバージョンに書き込みます。これにより、最適化履歴がバンドルとともにバージョン管理されます。このモードは、設定バンドルを使用して設定を一元管理し、最適化された出力を自動的にバンドルに書き戻す場合に便利です。

    推奨事項の種類 CLI フラグ API フィールド

    システムプロンプト

    --bundle-name <bundle-name> + --bundle-version <bundle-version> + --system-prompt-json-path <path>

    systemPrompt.configurationBundle 、bundleArnversionId、 systemPromptJsonPath

    ツールの説明

    --bundle-name <bundle-name> + --bundle-version <bundle-version> + --tool-desc-json-path "name:jsonpath" (ツールごとに繰り返す)

    toolDescription.configurationBundle と を含む bundleArn、versionId、および toolsリスト toolName toolDescriptionJsonPath

    設定バンドルを使用する場合、レコメンデーション結果には、 を含むconfigurationBundleフィールドbundleArnと、最適化された設定を含むバンドルバージョンversionIdを指す新しい が含まれます。

エージェントトレースソース

agentTraces パラメータは、次の 2 つのソースのいずれかを受け入れます。

  • CloudWatch Logs: エージェントランタイムがテレメトリを CloudWatch に書き込むときに使用します。サービスは、指定されたロググループから必要な時間範囲内でトレースを直接読み取ります。logGroupArns、serviceNames、startTime、および を指定する必要がありますendTime。オプションの ruleフィールドを使用すると、トレースをフィルタリングできます (たとえば、 goal_success_rate がしきい値を下回るセッションのみを選択）。

    注記

    レコメンデーション API は、ロググループ名ではなく、ロググループ ARNs (logGroupArns) を使用します。これは、 を使用するバッチ評価とは異なりますlogGroupNames。

    フィールド Type 必須 説明

    cloudwatchLogs.logGroupArns

    文字列のリスト

    はい

    エージェントテレメトリが保存されている CloudWatch Logs ロググループ ARNs。形式: arn:aws:logs:{region}:{account}:log-group:{log-group-name}。

    cloudwatchLogs.serviceNames

    文字列のリスト

    はい

    CloudWatch でエージェントのトレースを識別するサービス名。規則: {RuntimeName}.DEFAULT。

    cloudwatchLogs.startTime

    ISO 8601 日時

    はい

    トレース収集ウィンドウの開始。この時間以降のトレースのみが含まれます。

    cloudwatchLogs.endTime

    ISO 8601 日時

    はい

    トレース収集ウィンドウの終了。この時間より前のトレースのみが含まれます。

    cloudwatchLogs.rule

    オブジェクト

    いいえ

    トレース選択を絞り込むオプションのフィルタールール。各フィルターが 、 operator ( などLESS_THAN)key、および value ( など) を指定するfiltersリストが含まれます{"doubleValue": 0.5}。
    例
    AgentCore CLI
    agentcore run recommendation \
  --type system-prompt \
  --run my-prompt-rec \
  --runtime MyAgent \
  --evaluator Builtin.GoalSuccessRate \
  --inline "You are a helpful assistant..." \
  --lookback 7 \
  --wait
    AWS SDK (boto3)
    from datetime import datetime, timedelta, timezone

now = datetime.now(timezone.utc)

agent_traces = {
    "cloudwatchLogs": {
        "logGroupArns": [
            "<log-group-arn>"
        ],
        "serviceNames": ["<service-name>"],
        "startTime": now - timedelta(days=7),
        "endTime": now,
    }
}

    パフォーマンスの低いセッションのみを選択するオプションのルールフィルターを使用する場合:

    agent_traces = {
    "cloudwatchLogs": {
        "logGroupArns": [
            "<log-group-arn>"
        ],
        "serviceNames": ["<service-name>"],
        "startTime": now - timedelta(days=7),
        "endTime": now,
        "rule": {
            "filters": [
                {
                    "key": "goal_success_rate",
                    "operator": "LESS_THAN",
                    "value": {"doubleValue": 0.5}
                }
            ]
        },
    }
}

  • インラインセッションスパン: トレースがローカルで利用できる場合 (ローカルテストラン、CI/CD パイプライン、最適化する特定のセッションなど) に使用します。OpenTelemetry 互換スパンオブジェクトのリストとして、API リクエスト本文でスパンを直接指定します。

    フィールド Type 必須 説明

    sessionSpans

    オブジェクトのリスト

    はい

    OpenTelemetry 互換形式のエージェントトレーススパン。各スパンには、トレース ID、スパン ID、名前、タイムスタンプ、属性が含まれます。
    例
    AgentCore CLI

    スパンファイル (ローカル JSON ファイルからスパンを読み取り、インラインスパンとして渡します）。

    agentcore run recommendation \
  --type system-prompt \
  --run my-prompt-rec \
  --runtime MyAgent \
  --evaluator Builtin.GoalSuccessRate \
  --inline "You are a helpful assistant..." \
  --spans-file agent-traces.json

    特定のセッション IDs (CLI はクライアント側でスパンを収集し、インラインスパンとして渡します）。

    agentcore run recommendation \
  --type system-prompt \
  --run my-prompt-rec \
  --runtime MyAgent \
  --evaluator Builtin.GoalSuccessRate \
  --inline "You are a helpful assistant..." \
  --session-id <session-id-1> <session-id-2>
    AWS SDK (boto3)
    import json

with open("agent-traces.json") as f:
    spans = json.load(f)

agent_traces = {
    "sessionSpans": spans
}
注記

agentcore run recommendation は非同期です。がない場合--wait、 コマンドはレコメンデーションジョブを送信してすぐに を返します。ジョブは非終了状態 ( PENDINGや などIN_PROGRESS) で開始され、後で結果を取得します。レコメンデーションが終了状態になるまで をブロック--waitに渡します。送信されたジョブの結果をポーリングまたは取得するには、 を実行します。ここでagentcore view recommendation <id>、 idはレコメンデーションジョブ ID です。

AgentCore CLI には、基盤となる API トレースソースタイプにマッピングされる便利なフラグが用意されています。

CLI フラグ API マッピング 説明

--lookback <days>

cloudwatchLogs コンピューティングされた startTimeと endTime

CloudWatch Logs を介して過去 N 日間のトレースを収集します。CLI は、ランタイム設定からロググループ ARNsとサービス名を解決します。

--session-id <id>

sessionSpans (インライン)

指定されたセッションクライアント側のスパンを収集し、インラインセッションスパンとして渡します。レコメンデーション API 自体は、CloudWatch ソースでのセッション ID フィルタリングをサポートしていません。

--spans-file <path>

sessionSpans (インライン)

ローカル JSON ファイルからスパンを読み取り、インラインセッションスパンとして渡します。

--wait

n/a (クライアント側のポーリング)

レコメンデーションが終了状態になるまでブロックします。