View a markdown version of this page

建議 - Amazon Bedrock AgentCore
組態輸入模式客服人員追蹤來源

建議

建議使用 AI 從實際工作階段追蹤產生最佳化的代理程式組態。您不手動重寫提示或工具描述，而是將服務指向代理程式的追蹤，指定目標評估器做為獎勵訊號，並接收最佳化的組態。

注意

建議是由 LLMs產生。套用前先檢閱和測試。

Amazon Bedrock AgentCore 支援兩種建議類型：

  • 系統提示建議：分析代理程式追蹤並產生最佳化系統提示，以改善目標評估器的效能。服務可識別失敗模式並新增特定行為指示。

  • 工具描述建議：分析代理程式追蹤並產生強化的工具描述，以減少工具選擇混淆。當客服人員為模棱兩可的請求選取錯誤的工具時，這很有用。

每個建議都需要兩個輸入：要最佳化的目前代理程式組態，以及要分析的代理程式追蹤。

主題

組態輸入模式

您以下列兩種方式之一提供目前的組態：

  • 內嵌文字：直接提供組態做為 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 使用 bundleArn、versionId、 systemPromptJsonPath

    工具描述

    --bundle-name <bundle-name> + --bundle-version <bundle-version> + --tool-desc-json-path "name:jsonpath"（針對每個工具重複）

    toolDescription.configurationBundle 包含 和 的 bundleArn、 versionIdtoolName和 tools清單 toolDescriptionJsonPath

    使用組態套件時，建議結果包含具有 configurationBundle的欄位，bundleArn以及versionId新的指向包含最佳化組態的套件版本。

客服人員追蹤來源

agentTraces 參數接受兩個來源之一：

  • CloudWatch Logs：當您的代理程式執行時間將遙測寫入 CloudWatch 時使用 。服務會在所需的時間範圍內直接從指定的日誌群組讀取追蹤。您必須提供 logGroupArns、serviceNames、 startTime和 endTime。選用rule欄位可讓您篩選追蹤 （例如，僅選取goal_success_rate低於閾值的工作階段）。

    注意

    建議 API 使用日誌群組 ARNs(logGroupArns)，而不是日誌群組名稱。這與使用 的批次評估不同logGroupNames。

    欄位 類型 必要 說明

    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

    物件

    否

    用於縮小追蹤選擇的選用篩選條件規則。包含一個filters清單，其中每個篩選條件指定 key、 operator（例如 LESS_THAN) 和 value（例如 {"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 管道或您想要最佳化的特定工作階段），請使用 。您可以直接在 API 請求內文中提供跨度，做為 OpenTelemetry 相容跨度物件的清單。

    欄位 類型 必要 說明

    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 （用戶端輪詢）

封鎖 ，直到建議達到結束狀態。