本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。
# 开始推荐工具描述
开始推荐为您的代理生成优化的工具描述。该服务会分析代理跟踪以识别工具选择方面的混乱情况，并生成更清晰的描述，从而减少代理在工具之间进行选择时的歧义。
**注意**
建议由 LLM 生成。在应用它们之前进行审查和测试。
## 代码示例
**Example**
与只需要一个提示建议的系统提示符不同`-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-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-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 `（使用运行的本地见解作为跟踪源；CLI 解析批量评估 ARN）和`--batch-evaluation-arn `（直接使用批量评估 ARN）。有关所有追踪来源的概述，请参阅[追踪来源以获取建议](optimization-recommendations.md#recommendations-trace-sources)。您还可以使用客户管理的 KMS 密钥添加`--kms-key `以加密推荐结果。
要在推荐达到终端状态之前阻止，请添加`--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 --json
```
带有 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": "",
"versionId": "",
"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": "",
"versionId": "",
"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 | 是 | 用于分析的追踪来源。有关建议，请参阅[追踪来源](optimization-recommendations.md#recommendations-trace-sources)。 |
**注意**
工具描述建议不需要`evaluationConfig`. 与使用评估器作为优化信号的系统提示建议不同，工具描述建议直接从代理跟踪中分析工具选择模式，以识别工具之间的歧义并生成更清晰的描述。
## 工具描述输入模式
| Mode | CLI 标志 | API 字段 |
| --- | --- | --- |
| 行内文本 | `--tools "name:description"`（对每个工具重复此操作） | `toolDescription.toolDescriptionText.tools`。带有`toolName`和的对象列表 `toolDescription` |
| 配置包 | `--bundle-name `\+ `--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 | 上次更新建议的时间。 |
## 推荐结果
当推荐达到`COMPLETED`状态（通过 “[获取推荐” 检索](recommendations-get.md)）时，结果包含：
| 字段 | Type | 说明 |
| --- | --- | --- |
| `tools` | 列表 | Per-tool 结果。每个条目都包含`toolName``recommendedToolDescription`、和`explanation`。 |
| `configurationBundle` | 对象 | 当输入是配置包时出现。包含`bundleArn`并`versionId`指向应用了优化描述的新捆绑包版本。 |
| `errorCode` | 字符串 | 如果建议失败，则出现。描述故障的错误代码。 |
| `errorMessage` | 字符串 | 如果建议失败，则出现。 Human-readable 错误描述。 |
## 错误
| 错误 | HTTP 状态 | 说明 |
| --- | --- | --- |
| `ValidationException` | 400 | 请求参数无效。检查字段限制和必填字段。 |
| `AccessDeniedException` | 403 | 权限不足。验证 IAM 策略。 |
| `ConflictException` | 409 | 已经存在具有相同客户令牌且具有不同参数的推荐。 |
| `ServiceQuotaExceededException` | 402 | 您已超过并发建议的最大数量。 |
| `ThrottlingException` | 429 | 超出请求速率。使用指数回退进行重试。 |
| `InternalServerException` | 500 | Service-side 错误。重试请求。 |