啟動系統提示建議

啟動建議，為您的代理程式產生最佳化系統提示。服務會分析代理程式追蹤、識別故障模式，並產生修訂後的系統提示，以改善目標評估器的效能。

注意

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

程式碼範例

範例

AgentCore CLI

CLI 接受多種追蹤來源和三種系統提示輸入模式。視需要合併它們：

追蹤來源：CloudWatch Logs (--lookback)、內嵌範圍 (--spans-file)、本機洞察執行 (--from-insights <id> — 使用本機洞察執行作為追蹤來源；解析批次評估 ARN) 或直接批次評估 ARN (--batch-evaluation-arn <arn> — 直接使用批次評估 ARN 作為追蹤來源）
系統提示輸入：內嵌文字 (--inline)、提示檔案 (--prompt-file) 或組態套件 (--bundle-name)
選用篩選條件：特定工作階段 IDs(--session-id) 以縮小要分析的追蹤範圍

選用加密：KMS 金鑰 (--kms-key <arn> — 用於加密建議結果的 KMS 金鑰 ARN)

具有 CloudWatch 追蹤的內嵌系統提示：


agentcore run recommendation \
  --type system-prompt \
  --run my-prompt-rec \
  --runtime MyAgent \
  --evaluator Builtin.GoalSuccessRate \
  --inline "You are a helpful customer support assistant. Help users with their orders and returns." \
  --lookback 7 \
  --wait

run recommendation 會啟動非同步任務，並僅傳回 recommendationId和初始 PENDING或 IN_PROGRESS 狀態。新增 --wait至區塊，直到建議達到結束狀態。若要稍後擷取已完成的結果，請參閱擷取結果。

來自具有 CloudWatch 追蹤之檔案的內嵌系統提示：


agentcore run recommendation \
  --type system-prompt \
  --run my-prompt-rec \
  --runtime MyAgent \
  --evaluator Builtin.GoalSuccessRate \
  --prompt-file ./system-prompt.txt \
  --lookback 7

包含跨檔案的內嵌系統提示：


agentcore run recommendation \
  --type system-prompt \
  --run my-prompt-rec \
  --runtime MyAgent \
  --evaluator Builtin.GoalSuccessRate \
  --inline "You are a helpful customer support 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 customer support assistant." \
  --session-id <session-id-1> <session-id-2>

搭配 CloudWatch 追蹤的組態套件：

CLI 會自動從代理程式執行時間 ARN 的configuration父物件解析完整的 JSON 路徑。您只需要提供包含系統提示的金鑰名稱。


agentcore run recommendation \
  --type system-prompt \
  --run my-prompt-rec \
  --runtime MyAgent \
  --evaluator Builtin.GoalSuccessRate \
  --bundle-name <bundle-name> \
  --bundle-version <bundle-version> \
  --system-prompt-json-path "system_prompt" \
  --lookback 7

擷取結果：

使用 view recommendation搭配建議任務 ID 來擷取已完成的結果。針對包含 recommendedSystemPrompt和 --json的機器可讀取輸出新增 explanation。


agentcore view recommendation <recommendation-id> --json

AWS SDK (boto3)

具有 CloudWatch 追蹤的內嵌文字：


import boto3
import json
import uuid
from datetime import datetime, timedelta, timezone

client = boto3.client("bedrock-agentcore", region_name="us-west-2")

now = datetime.now(timezone.utc)

response = client.start_recommendation(
    name="my-prompt-rec",
    type="SYSTEM_PROMPT_RECOMMENDATION",
    recommendationConfig={
        "systemPromptRecommendationConfig": {
            "systemPrompt": {
                "text": "You are a helpful customer support assistant. Help users with their orders and returns."
            },
            "agentTraces": {
                "cloudwatchLogs": {
                    "logGroupArns": [
                        "<log-group-arn>"
                    ],
                    "serviceNames": ["<service-name>"],
                    "startTime": now - timedelta(days=7),
                    "endTime": now,
                }
            },
            "evaluationConfig": {
                "evaluators": [
                    {"evaluatorArn": "arn:aws:bedrock-agentcore:::evaluator/Builtin.GoalSuccessRate"}
                ]
            },
        }
    },
    clientToken=str(uuid.uuid4()),
)

recommendation_id = response["recommendationId"]
print(f"Started recommendation: {recommendation_id}")
print(f"Status: {response['status']}")

具有內嵌跨度的內嵌文字：


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

response = client.start_recommendation(
    name="my-prompt-rec-spans",
    type="SYSTEM_PROMPT_RECOMMENDATION",
    recommendationConfig={
        "systemPromptRecommendationConfig": {
            "systemPrompt": {
                "text": "You are a helpful customer support assistant."
            },
            "agentTraces": {
                "sessionSpans": spans
            },
            "evaluationConfig": {
                "evaluators": [
                    {"evaluatorArn": "arn:aws:bedrock-agentcore:::evaluator/Builtin.GoalSuccessRate"}
                ]
            },
        }
    },
    clientToken=str(uuid.uuid4()),
)

搭配 CloudWatch 追蹤的組態套件：


response = client.start_recommendation(
    name="my-bundle-prompt-rec",
    type="SYSTEM_PROMPT_RECOMMENDATION",
    recommendationConfig={
        "systemPromptRecommendationConfig": {
            "systemPrompt": {
                "configurationBundle": {
                    "bundleArn": "<bundle-arn>",
                    "versionId": "<bundle-version>",
                    "systemPromptJsonPath": "$.configuration.system_prompt",
                }
            },
            "agentTraces": {
                "cloudwatchLogs": {
                    "logGroupArns": [
                        "<log-group-arn>"
                    ],
                    "serviceNames": ["<service-name>"],
                    "startTime": now - timedelta(days=7),
                    "endTime": now,
                }
            },
            "evaluationConfig": {
                "evaluators": [
                    {"evaluatorArn": "arn:aws:bedrock-agentcore:::evaluator/Builtin.GoalSuccessRate"}
                ]
            },
        }
    },
    clientToken=str(uuid.uuid4()),
)

具有內嵌跨度的組態套件：


response = client.start_recommendation(
    name="my-bundle-prompt-rec-spans",
    type="SYSTEM_PROMPT_RECOMMENDATION",
    recommendationConfig={
        "systemPromptRecommendationConfig": {
            "systemPrompt": {
                "configurationBundle": {
                    "bundleArn": "<bundle-arn>",
                    "versionId": "<bundle-version>",
                    "systemPromptJsonPath": "$.configuration.system_prompt",
                }
            },
            "agentTraces": {
                "sessionSpans": spans
            },
            "evaluationConfig": {
                "evaluators": [
                    {"evaluatorArn": "arn:aws:bedrock-agentcore:::evaluator/Builtin.GoalSuccessRate"}
                ]
            },
        }
    },
    clientToken=str(uuid.uuid4()),
)

請求參數

參數	Type	必要	描述
`name`	String	是	建議的名稱。最多 48 個字元。模式：`[a-zA-Z][a-zA-Z0-9_-]{0,47}`。
`type`	String	是	必須為 `SYSTEM_PROMPT_RECOMMENDATION`。
`recommendationConfig`	物件	是	包含建議的`systemPromptRecommendationConfig`組態。
`description`	String	否	選用的描述。最多 4096 個字元。
`clientToken`	String	否	等冪性字符。如果您使用相同的用戶端字符重試請求，服務會傳回現有的建議，而不是建立新的建議。

systemPromptRecommendationConfig 欄位

欄位	類型	必要	說明
`systemPrompt`	UNION	是	要最佳化的目前系統提示。提供 `text`（內嵌字串，最多 20，000 個字元）或 `configurationBundle`（組合參考）。
`agentTraces`	UNION	是	追蹤來源進行分析。如需建議，請參閱追蹤來源。
`evaluationConfig`	物件	是	指定目標評估器的評估組態。包含僅包含一個評估者參考的`evaluators`清單。

選擇評估者

選取與您要改進的方向一致的評估器。您選取的評估器會決定建議最佳化的目標；無論評估器分數高多少，最佳化器都會推送提示的目標。

您可以使用內建評估器或提供自訂評估器 ARN。使用下列準則來選擇：

如果您的客服人員有明確的任務要完成（預訂、擷取、多步驟工作流程）， Builtin.GoalSuccessRate就是正確的訊號。
如果您的客服人員較開放，且您關心互動本身的品質，Builtin.Helpfulness則更適合。
如果您關注的品質是特定網域或未由內建評估器擷取，請使用自訂評估器以最佳方式代表測量。

注意

建議支援內建、自訂 LLM-as-judge 和程式碼型評估器，但需要評估器傳回數值作為最佳化訊號。對於自訂 LLM-as-judge 評估器，ratingScale使用numerical比例設定（而非 categorical)。對於程式碼型評估器，請在回應結構描述中包含 value 欄位。

在 API 中，使用剛好一個評估器參考在evaluationConfig.evaluators清單中指定評估器：


"evaluationConfig": {
    "evaluators": [
        {"evaluatorArn": "arn:aws:bedrock-agentcore:::evaluator/Builtin.GoalSuccessRate"}
    ]
}

在 CLI 中，使用 --evaluator旗標：


--evaluator Builtin.GoalSuccessRate

系統提示輸入模式

Mode	CLI 旗標	API 欄位
內嵌文字	`--inline "prompt text"` 或 `--prompt-file ./path.txt`	`systemPrompt.text`
組態套件	`--bundle-name <bundle-name>` + `--bundle-version <bundle-version>` + `--system-prompt-json-path <path>`	`systemPrompt.configurationBundle` 使用 `bundleArn`、`versionId`、 `systemPromptJsonPath`

使用組態套件時，結果會包含套用最佳化系統提示的新套件版本。

回應

欄位	Type	Description
`recommendationId`	String	建議內容的唯一識別碼。
`recommendationArn`	String	建議的 ARN。
`name`	String	您指定的名稱。
`type`	String	`SYSTEM_PROMPT_RECOMMENDATION`.
`status`	String	初始狀態： `PENDING`或 `IN_PROGRESS`。
`createdAt`	時間戳記	建立建議時。
`updatedAt`	時間戳記	上次更新建議的時間。

建議結果

當建議達到COMPLETED狀態（透過取得建議擷取) 時，結果會包含：

欄位	Type	Description
`recommendedSystemPrompt`	String	最佳化系統提示文字。
`configurationBundle`	物件	當輸入為組態套件時出現。包含`bundleArn`並`versionId`指向套用最佳化提示的新套件版本。
`explanation`	String	說明產生建議的原因，以及建議變更背後的原因。
`errorCode`	String	如果建議失敗，則會顯示。描述失敗的錯誤代碼。
`errorMessage`	String	如果建議失敗，則會顯示。人類可讀取的錯誤描述。

錯誤

錯誤	HTTP 狀態	說明
`ValidationException`	400	無效的請求參數。檢查欄位限制條件和必要欄位。
`AccessDeniedException`	403	許可不足。驗證 IAM 政策。
`ConflictException`	409	具有相同用戶端字符的建議已存在，且具有不同的參數。
`ServiceQuotaExceededException`	402	您已超過並行建議的數量上限。
`ThrottlingException`	429	超過請求率。以指數退避重試。
`InternalServerException`	500	服務端錯誤。重試請求。

您的瀏覽器已停用或無法使用 Javascript。

您必須啟用 Javascript，才能使用 AWS 文件。請參閱您的瀏覽器說明頁以取得說明。

文件慣用形式

建議

工具描述建議