View a markdown version of this page

取得建議 - Amazon Bedrock AgentCore
程式碼範例請求參數回應回應範例錯誤

取得建議

擷取建議的狀態和結果。輪詢此操作，直到建議達到結束狀態 (COMPLETED 或 FAILED)。

程式碼範例

範例
AgentCore CLI

agentcore run recommendation 提交fire-and-forget任務。傳遞 --wait 以封鎖，直到達到結束狀態，或稍後依 ID 檢查：

agentcore view recommendation <recommendation-id>

列出所有建議任務，或以 JSON 檢視：

agentcore view recommendation
agentcore view recommendation <recommendation-id> --json
AWS SDK (boto3)

輪詢直到完成並擷取結果：

import time
import boto3

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

# Poll until terminal state
while True:
    result = client.get_recommendation(recommendationId=recommendation_id)
    status = result["status"]
    print(f"Status: {status}")

    if status in ("COMPLETED", "FAILED"):
        break
    time.sleep(15)

# Extract system prompt result
if status == "COMPLETED":
    rec_result = result.get("recommendationResult", {})

    if "systemPromptRecommendationResult" in rec_result:
        sys_result = rec_result["systemPromptRecommendationResult"]
        print(f"Recommended prompt:\n{sys_result['recommendedSystemPrompt']}")

        if "explanation" in sys_result:
            print(f"Explanation:\n{sys_result['explanation']}")

        if "configurationBundle" in sys_result:
            bundle = sys_result["configurationBundle"]
            print(f"New bundle version: {bundle['versionId']}")

    elif "toolDescriptionRecommendationResult" in rec_result:
        tool_result = rec_result["toolDescriptionRecommendationResult"]
        for tool in tool_result.get("tools", []):
            print(f"{tool['toolName']}: {tool['recommendedToolDescription']}")
            if "explanation" in tool:
                print(f"  Explanation: {tool['explanation']}")

elif status == "FAILED":
    rec_result = result.get("recommendationResult", {})
    r = rec_result.get("systemPromptRecommendationResult") or rec_result.get("toolDescriptionRecommendationResult")
    print(f"Error: [{r['errorCode']}] {r['errorMessage']}")

擷取組態套件參考以用於 A/B 測試：

result = client.get_recommendation(recommendationId=recommendation_id)

if result["status"] == "COMPLETED":
    rec_result = result["recommendationResult"]
    sys_result = rec_result.get("systemPromptRecommendationResult", {})

    if "configurationBundle" in sys_result:
        bundle_arn = sys_result["configurationBundle"]["bundleArn"]
        version_id = sys_result["configurationBundle"]["versionId"]
        print(f"Use in A/B test: bundle={bundle_arn}, version={version_id}")

請求參數

參數 Type 必要 描述

recommendationId

String

是

傳回的建議 IDStartRecommendation。以路徑參數傳遞。

回應

欄位 Type Description

recommendationId

String

建議內容的唯一識別碼。

recommendationArn

String

建議的 ARN。

name

String

建議名稱。

type

String

SYSTEM_PROMPT_RECOMMENDATION 或 TOOL_DESCRIPTION_RECOMMENDATION

status

String

目前狀態：PENDING、IN_PROGRESS、FAILED、 COMPLETED或 DELETING。

recommendationConfig

物件

您提交的組態。

recommendationResult

物件

當狀態為 時出現COMPLETED。包含最佳化組態。形狀取決於建議類型。

createdAt

時間戳記

建立建議時。

updatedAt

時間戳記

上次更新建議的時間。

系統提示結果欄位

當類型為 recommendationResult.systemPromptRecommendationResult時，出現在 中SYSTEM_PROMPT_RECOMMENDATION：

欄位 Type Description

recommendedSystemPrompt

String

最佳化系統提示文字。

configurationBundle

物件

當輸入為組態套件時出現。包含新套件版本的 versionId bundleArn和 。

explanation

String

說明產生建議的原因，以及建議變更背後的原因。

errorCode

String

失敗時出現。錯誤代碼。

errorMessage

String

失敗時出現。人類可讀的描述。

工具描述結果欄位

當類型為 recommendationResult.toolDescriptionRecommendationResult時，出現在 中TOOL_DESCRIPTION_RECOMMENDATION：

欄位 Type 說明

tools

清單

每個工具的結果。每個項目都包含 toolName、 recommendedToolDescription和 explanation。

configurationBundle

物件

當輸入為組態套件時出現。包含新套件版本的 versionId bundleArn和 。

errorCode

String

失敗時出現。錯誤代碼。

errorMessage

String

失敗時出現。人類可讀的描述。

回應範例

已完成的系統提示建議 （內嵌輸入）：

{
    "recommendationId": "MyPromptRec-Ab1Cd2Ef3G",
    "recommendationArn": "arn:aws:bedrock-agentcore:us-west-2:123456789012:recommendation/MyPromptRec-Ab1Cd2Ef3G",
    "name": "my-prompt-rec",
    "type": "SYSTEM_PROMPT_RECOMMENDATION",
    "status": "COMPLETED",
    "recommendationConfig": { ... },
    "recommendationResult": {
        "systemPromptRecommendationResult": {
            "recommendedSystemPrompt": "<optimized system prompt text>",
            "explanation": "<explanation of why the recommendation was generated>"
        }
    },
    "createdAt": "2025-03-15T10:00:00Z",
    "updatedAt": "2025-03-15T10:05:30Z"
}

已完成的系統提示建議 （組態套件輸入）：

{
    "recommendationId": "MyBundleRec-Xy9Zw8Vq1R",
    "recommendationArn": "arn:aws:bedrock-agentcore:us-west-2:123456789012:recommendation/MyBundleRec-Xy9Zw8Vq1R",
    "name": "my-bundle-prompt-rec",
    "type": "SYSTEM_PROMPT_RECOMMENDATION",
    "status": "COMPLETED",
    "recommendationConfig": { ... },
    "recommendationResult": {
        "systemPromptRecommendationResult": {
            "recommendedSystemPrompt": "<optimized system prompt text>",
            "configurationBundle": {
                "bundleArn": "arn:aws:bedrock-agentcore:us-west-2:123456789012:configuration-bundle/myBundle-Ab1Cd2Ef3G",
                "versionId": "12345678-1234-1234-1234-123456789012"
            },
            "explanation": "<explanation of why the recommendation was generated>"
        }
    },
    "createdAt": "2025-03-15T10:00:00Z",
    "updatedAt": "2025-03-15T10:06:12Z"
}

已完成的工具描述建議：

{
    "recommendationId": "MyToolRec-Qr5St6Uv7W",
    "recommendationArn": "arn:aws:bedrock-agentcore:us-west-2:123456789012:recommendation/MyToolRec-Qr5St6Uv7W",
    "name": "my-tool-rec",
    "type": "TOOL_DESCRIPTION_RECOMMENDATION",
    "status": "COMPLETED",
    "recommendationConfig": { ... },
    "recommendationResult": {
        "toolDescriptionRecommendationResult": {
            "tools": [
                {
                    "toolName": "<tool-name-1>",
                    "recommendedToolDescription": "<optimized description for tool 1>",
                    "explanation": "<explanation of why this tool description was changed>"
                },
                {
                    "toolName": "<tool-name-2>",
                    "recommendedToolDescription": "<optimized description for tool 2>",
                    "explanation": "<explanation of why this tool description was changed>"
                }
            ]
        }
    },
    "createdAt": "2025-03-15T11:00:00Z",
    "updatedAt": "2025-03-15T11:04:45Z"
}

失敗的建議：

{
    "recommendationId": "MyFailedRec-Mn3Op4Qr5S",
    "recommendationArn": "arn:aws:bedrock-agentcore:us-west-2:123456789012:recommendation/MyFailedRec-Mn3Op4Qr5S",
    "name": "my-failed-rec",
    "type": "SYSTEM_PROMPT_RECOMMENDATION",
    "status": "FAILED",
    "recommendationConfig": { ... },
    "recommendationResult": {
        "systemPromptRecommendationResult": {
            "errorCode": "<error-code>",
            "errorMessage": "<human-readable error description>"
        }
    },
    "createdAt": "2025-03-15T12:00:00Z",
    "updatedAt": "2025-03-15T12:01:10Z"
}

錯誤

錯誤 HTTP 狀態 說明

ResourceNotFoundException

404

找不到具有指定 ID 的建議。

ValidationException

400

無效的建議 ID 格式。

AccessDeniedException

403

許可不足。

ThrottlingException

429

超過請求率。

InternalServerException

500

服務端錯誤。