开始推荐工具描述

开始提出建议，为您的代理生成经过优化的工具描述。该服务会分析代理跟踪以识别工具选择混乱，并生成更清晰的描述，从而减少代理在工具之间进行选择时的歧义。

注意

推荐由法学硕士生成。在应用之前，请先进行审查和测试。

代码示例

例

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

带有 spans 文件的内联工具描述：


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

带有特定会话 ID 的内联工具描述：


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

带有 spans 文件的配置包：


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`	字符串	是	推荐的名称。最多 48 个字符。图案：`[a-zA-Z][a-zA-Z0-9_-]{0,47}`。
`type`	字符串	是	必须是 `TOOL_DESCRIPTION_RECOMMENDATION`。
`recommendationConfig`	对象	是	`toolDescriptionRecommendationConfig`包含建议的配置。
`description`	字符串	否	可选描述。最多 4096 个字符。
`clientToken`	字符串	否	等能令牌。如果您使用相同的客户端令牌重试请求，则该服务将返回现有建议，而不是创建新建议。

工具DescriptionRecommendationConfig 字段

字段	类型	必需	说明
`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`、`versionId`、和包含`toolName`和的`tools`列表 `toolDescriptionJsonPath`

使用配置包时，结果包括应用了经过优化的工具描述的新捆绑包版本。

响应

字段	Type	说明
`recommendationId`	字符串	建议的唯一标识符。
`recommendationArn`	字符串	该建议的 ARN。
`name`	字符串	您指定的名称。
`type`	字符串	`TOOL_DESCRIPTION_RECOMMENDATION`.
`status`	字符串	初始状态：`PENDING`或`IN_PROGRESS`。
`createdAt`	Timestamp	建议的创建时间。
`updatedAt`	Timestamp	上次更新建议的时间。

字段	Type	说明
`tools`	列表	Per-tool 结果。每个条目都包含`toolNamerecommendedToolDescription`、和`explanation`。
`configurationBundle`	对象	当输入为配置包时出现。包含`bundleArn`并`versionId`指向应用了优化描述的新捆绑包版本。
`errorCode`	字符串	如果建议失败，则在场。描述失败的错误代码。
`errorMessage`	字符串	如果建议失败，则在场。 Human-readable 错误描述。

错误

错误	HTTP 状态	说明
`ValidationException`	400	请求参数无效。检查字段限制和必填字段。
`AccessDeniedException`	403	权限不足。验证 IAM 策略。
`ConflictException`	409	已经存在具有相同客户端令牌且参数不同的推荐。
`ServiceQuotaExceededException`	402	您已超过并发推荐的最大数量。
`ThrottlingException`	429	超出请求速率。使用指数回退进行重试。
`InternalServerException`	500	Service-side 错误。重试请求。

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

文档惯例

系统提示建议

获取推荐