啟動工具描述建議

啟動建議，為您的代理程式產生最佳化工具描述。服務會分析代理程式追蹤，以識別工具選擇混淆，並產生更銳利的描述，以便在代理程式在工具之間選擇時減少模棱兩可的情況。

注意

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

程式碼範例

範例

AgentCore CLI

注意

與只需要一個的系統提示建議不同-e/--evaluator，工具描述會-e/--evaluator完全省略。

使用 CloudWatch 追蹤的內嵌工具描述：


agentcore run recommendation \
  --type tool-description \
  --run my-tool-rec \
  --runtime MyAgent \
  --tools "lookup_order:Look up an order by ID" \
  --tools "initiate_return:Initiate a return for an order" \
  --lookback 7

具有跨檔案的內嵌工具描述：


agentcore run recommendation \
  --type tool-description \
  --run my-tool-rec \
  --runtime MyAgent \
  --tools "lookup_order:Look up an order by ID" \
  --tools "initiate_return:Initiate a return for an order" \
  --spans-file agent-traces.json

具有特定工作階段 IDs內嵌工具描述：


agentcore run recommendation \
  --type tool-description \
  --run my-tool-rec \
  --runtime MyAgent \
  --tools "lookup_order:Look up an order by ID" \
  --tools "initiate_return:Initiate a return for an order" \
  --session-id 12345678-1234-1234-1234-123456789012

搭配 CloudWatch 追蹤的組態套件：


agentcore run recommendation \
  --type tool-description \
  --run my-tool-rec \
  --runtime MyAgent \
  --bundle-name <bundle-name> \
  --bundle-version <bundle-version> \
  --tool-desc-json-path "lookup_order:lookup_order" \
  --tool-desc-json-path "initiate_return:initiate_return" \
  --lookback 7

具有跨檔案的組態套件：


agentcore run recommendation \
  --type tool-description \
  --run my-tool-rec \
  --runtime MyAgent \
  --bundle-name <bundle-name> \
  --bundle-version <bundle-version> \
  --tool-desc-json-path "lookup_order:lookup_order" \
  --tool-desc-json-path "initiate_return:initiate_return" \
  --spans-file agent-traces.json

除了 --lookback、 --spans-file和之外--session-id， agentcore run recommendation接受另外兩個追蹤來源： --from-insights <id>（使用本機洞察作為追蹤來源執行；CLI 解析批次評估 ARN) 和 --batch-evaluation-arn <arn>（直接使用批次評估 ARN)。如需所有追蹤來源的概觀，請參閱追蹤來源以取得建議。您也可以新增 --kms-key <arn> ，以使用客戶受管 KMS 金鑰加密建議結果。

若要封鎖，直到建議達到結束狀態，請新增 --wait：


agentcore run recommendation \
  --type tool-description \
  --run my-tool-rec \
  --runtime MyAgent \
  --tools "lookup_order:Look up an order by ID" \
  --tools "initiate_return:Initiate a return for an order" \
  --lookback 7 \
  --wait

使用擷取完成的結果，包括最佳化工具描述agentcore view recommendation：


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-tool-rec",
    type="TOOL_DESCRIPTION_RECOMMENDATION",
    recommendationConfig={
        "toolDescriptionRecommendationConfig": {
            "toolDescription": {
                "toolDescriptionText": {
                    "tools": [
                        {
                            "toolName": "lookup_order",
                            "toolDescription": {"text": "Look up an order by ID"},
                        },
                        {
                            "toolName": "initiate_return",
                            "toolDescription": {"text": "Initiate a return for an order"},
                        },
                    ]
                }
            },
            "agentTraces": {
                "cloudwatchLogs": {
                    "logGroupArns": [
                        "arn:aws:logs:us-west-2:123456789012:log-group:/aws/bedrock-agentcore/runtimes/MyAgent-abc123-DEFAULT"
                    ],
                    "serviceNames": ["MyAgent.DEFAULT"],
                    "startTime": now - timedelta(days=7),
                    "endTime": now,
                }
            },
        }
    },
    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-tool-rec-spans",
    type="TOOL_DESCRIPTION_RECOMMENDATION",
    recommendationConfig={
        "toolDescriptionRecommendationConfig": {
            "toolDescription": {
                "toolDescriptionText": {
                    "tools": [
                        {
                            "toolName": "lookup_order",
                            "toolDescription": {"text": "Look up an order by ID"},
                        },
                        {
                            "toolName": "initiate_return",
                            "toolDescription": {"text": "Initiate a return for an order"},
                        },
                    ]
                }
            },
            "agentTraces": {
                "sessionSpans": spans
            },
        }
    },
    clientToken=str(uuid.uuid4()),
)

搭配 CloudWatch 追蹤的組態套件：


response = client.start_recommendation(
    name="my-bundle-tool-rec",
    type="TOOL_DESCRIPTION_RECOMMENDATION",
    recommendationConfig={
        "toolDescriptionRecommendationConfig": {
            "toolDescription": {
                "configurationBundle": {
                    "bundleArn": "<bundle-arn>",
                    "versionId": "<bundle-version>",
                    "tools": [
                        {
                            "toolName": "lookup_order",
                            "toolDescriptionJsonPath": "$.configuration.tools.lookup_order.description",
                        },
                        {
                            "toolName": "initiate_return",
                            "toolDescriptionJsonPath": "$.configuration.tools.initiate_return.description",
                        },
                    ],
                }
            },
            "agentTraces": {
                "cloudwatchLogs": {
                    "logGroupArns": [
                        "arn:aws:logs:us-west-2:123456789012:log-group:/aws/bedrock-agentcore/runtimes/MyAgent-abc123-DEFAULT"
                    ],
                    "serviceNames": ["MyAgent.DEFAULT"],
                    "startTime": now - timedelta(days=7),
                    "endTime": now,
                }
            },
        }
    },
    clientToken=str(uuid.uuid4()),
)

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


response = client.start_recommendation(
    name="my-bundle-tool-rec-spans",
    type="TOOL_DESCRIPTION_RECOMMENDATION",
    recommendationConfig={
        "toolDescriptionRecommendationConfig": {
            "toolDescription": {
                "configurationBundle": {
                    "bundleArn": "<bundle-arn>",
                    "versionId": "<bundle-version>",
                    "tools": [
                        {
                            "toolName": "lookup_order",
                            "toolDescriptionJsonPath": "$.configuration.tools.lookup_order.description",
                        },
                        {
                            "toolName": "initiate_return",
                            "toolDescriptionJsonPath": "$.configuration.tools.initiate_return.description",
                        },
                    ],
                }
            },
            "agentTraces": {
                "sessionSpans": spans
            },
        }
    },
    clientToken=str(uuid.uuid4()),
)

請求參數

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

toolDescriptionRecommendationConfig 欄位

欄位	類型	必要	說明
`toolDescription`	UNION	是	要最佳化的目前工具描述。提供 `toolDescriptionText`（工具名稱和描述對的內嵌清單）或 `configurationBundle`（每個工具描述的 JSON 路徑的組合參考）。
`agentTraces`	UNION	是	追蹤來源進行分析。如需建議，請參閱追蹤來源。

注意

工具描述建議不需要 evaluationConfig。與使用評估器做為最佳化訊號的系統提示建議不同，工具描述建議會直接從代理程式追蹤分析工具選擇模式，以識別工具之間的模棱兩可處並產生銳利的描述。

工具描述輸入模式

Mode	CLI 旗標	API 欄位
內嵌文字	`--tools "name:description"` （針對每個工具重複）	`toolDescription.toolDescriptionText.tools`。具有 `toolName`和的物件清單 `toolDescription`
組態套件	`--bundle-name <bundle-name>` + `--bundle-version <bundle-version>` + `--tool-desc-json-path "name:field"`（針對每個工具重複）	`toolDescription.configurationBundle` 包含和的 `bundleArn`、 `versionIdtoolName`和 `tools`清單 `toolDescriptionJsonPath`

使用組態套件時，結果會包含套用最佳化工具描述的新套件版本。

回應

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

建議結果

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

欄位	Type	說明
`tools`	清單	每個工具的結果。每個項目都包含 `toolName`、 `recommendedToolDescription`和 `explanation`。
`configurationBundle`	物件	當輸入為組態套件時出現。包含`bundleArn`並`versionId`指向套用最佳化描述的新套件版本。
`errorCode`	String	如果建議失敗，則會顯示。描述失敗的錯誤代碼。
`errorMessage`	String	如果建議失敗，則會顯示。人類可讀取的錯誤描述。

錯誤

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

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

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

文件慣用形式

系統提示建議

取得建議