本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 建议
<a name="optimization-recommendations"></a>

建议使用 AI 根据实际会话跟踪生成优化的代理配置。您可以将服务指向代理的踪迹，指定目标评估器作为奖励信号，然后获得优化的配置，而不是手动重写提示或工具描述。

**注意**  
建议由 LLM 生成。在应用它们之前进行审查和测试。

亚马逊 Bedrock AgentCore 支持两种推荐类型：
+  **系统提示建议：**分析代理跟踪并生成优化的系统提示，以提高目标评估器的性能。该服务识别故障模式并添加特定的行为指令。
+  **工具描述推荐：**分析代理痕迹并生成更清晰的工具描述，以减少工具选择的混乱。当代理为模糊的请求选择了错误的工具时，这很有用。

每项建议都需要两个输入：要优化的当前代理配置和要分析的代理跟踪。

**Topics**
+ [配置输入模式](#recommendations-input-modes)
+ [代理追踪来源](#recommendations-trace-sources)
+ [启动系统提示推荐](recommendations-system-prompt.md)
+ [开始推荐工具描述](recommendations-tool-description.md)
+ [获取推荐](recommendations-get.md)
+ [列出建议](recommendations-list.md)
+ [删除推荐](recommendations-delete.md)
+ [推荐加密](recommendations-encryption.md)

## 配置输入模式
<a name="recommendations-input-modes"></a>

您可以通过以下两种方式之一提供当前配置：
+  **行内文本：在 API 请求中直接以字符串形式**提供配置。要获得系统提示建议，请在`systemPrompt.text`字段中传递提示文本。要获得工具描述建议，请在`toolDescription.toolDescriptionText.tools`列表中传递每个工具的名称和描述。当你想测试正在迭代的提示时，或者当你的配置未存储在包中时，这种模式对于快速实验很有用。


<table>
<thead>
  <tr><th>获取建议</th><th>CLI 标志</th><th>API 字段</th></tr>
</thead>
<tbody>
  <tr><td>系统提示</td><td> <code>--inline "prompt text"</code> 或 <code>--prompt-file ./path.txt</code> </td><td> <code>systemPrompt.text</code> </td></tr>
  <tr><td>工具描述</td><td> <code>--tools "name:description, name:description"</code> </td><td> <code>toolDescription.toolDescriptionText.tools</code>: 带有<code>toolName</code>和的对象列表 <code>toolDescription</code> </td></tr>
</tbody>
</table>

+  **配置包：**引用现有的配置包版本。该服务使用您指定的 JSON 路径从包中读取当前配置，生成优化版本，并将结果写回**新的**包版本。这样可以将您的优化历史记录与套装一起进行版本控制。当您使用配置包集中管理配置并希望将优化的输出自动写回捆绑包时，此模式非常有用。


<table>
<thead>
  <tr><th>获取建议</th><th>CLI 标志</th><th>API 字段</th></tr>
</thead>
<tbody>
  <tr><td>系统提示</td><td> <code>--bundle-name &lt;bundle-name&gt;</code> + <code>--bundle-version &lt;bundle-version&gt;</code> + <code>--system-prompt-json-path &lt;path&gt;</code> </td><td> <code>systemPrompt.configurationBundle</code>用<code>bundleArn</code>，<code>versionId</code>，<code>systemPromptJsonPath</code></td></tr>
  <tr><td>工具描述</td><td> <code>--bundle-name &lt;bundle-name&gt;</code>+ <code>--bundle-version &lt;bundle-version&gt;</code> +<code>--tool-desc-json-path "name:jsonpath"</code>（对每个工具重复此操作）</td><td> <code>toolDescription.configurationBundle</code>包含<code>bundleArn</code><code>versionId</code>、和包含<code>toolName</code>和的<code>tools</code>列表 <code>toolDescriptionJsonPath</code> </td></tr>
</tbody>
</table>


  使用配置包时，建议结果包括一个带有的`configurationBundle`字段`bundleArn`和一个`versionId`指向包含优化配置的包版本的新字段。

## 代理追踪来源
<a name="recommendations-trace-sources"></a>

该`agentTraces`参数接受以下四个来源之一：
+  **CloudWatch 日志：在代理运行时将遥测数据写入时**使用。 CloudWatch该服务在要求的时间范围内直接从指定的日志组读取跟踪。您必须提供`logGroupArns`、`serviceNames``startTime`、和`endTime`。可选`rule`字段允许您筛选跟踪（例如，仅选择低于阈值的会话）。`goal_success_rate`
**注意**  
建议 API 使用日志组 ** ARN ** (`logGroupArns`)，而不是日志组**名称**。这与批量评估不同，批量评估使用`logGroupNames`。


<table>
<thead>
  <tr><th>字段</th><th>类型</th><th>必需</th><th>说明</th></tr>
</thead>
<tbody>
  <tr><td> <code>cloudwatchLogs.logGroupArns</code> </td><td>字符串列表</td><td>是</td><td>CloudWatch 记录存储代理遥测数据的 ARN 日志组。格式：<code>arn:aws:logs:{region}:{account}:log-group:{log-group-name}</code>。</td></tr>
  <tr><td> <code>cloudwatchLogs.serviceNames</code> </td><td>字符串列表</td><td>是</td><td>用于识别您的代理在中的痕迹的服务名称 CloudWatch。公约：<code>{RuntimeName}.DEFAULT</code>。</td></tr>
  <tr><td> <code>cloudwatchLogs.startTime</code> </td><td>ISO 8601 日期时间</td><td>是</td><td>跟踪收集窗口的启动。仅包括此时间之后的痕迹。</td></tr>
  <tr><td> <code>cloudwatchLogs.endTime</code> </td><td>ISO 8601 日期时间</td><td>是</td><td>跟踪收集窗口结束。仅包括此时间之前的痕迹。</td></tr>
  <tr><td> <code>cloudwatchLogs.rule</code> </td><td>对象</td><td>否</td><td>用于缩小追踪选择范围的可选筛选规则。包含一个<code>filters</code>列表，其中每个过滤器指定<code>key</code>、<code>operator</code>（例如<code>LESS_THAN</code>）和<code>value</code>（例如<code>{"doubleValue": 0.5}</code>）。</td></tr>
</tbody>
</table>
  
**Example**  

------
#### [ AgentCore CLI ]

  ```
  agentcore run recommendation \
    --type system-prompt \
    --run my-prompt-rec \
    --runtime MyAgent \
    --evaluator Builtin.GoalSuccessRate \
    --inline "You are a helpful assistant..." \
    --lookback 7 \
    --wait
  ```

------
#### [  Amazon SDK (boto3) ]

  ```
  from datetime import datetime, timedelta, timezone
  
  now = datetime.now(timezone.utc)
  
  agent_traces = {
      "cloudwatchLogs": {
          "logGroupArns": [
              "<log-group-arn>"
          ],
          "serviceNames": ["<service-name>"],
          "startTime": now - timedelta(days=7),
          "endTime": now,
      }
  }
  ```

  使用可选的规则筛选器仅选择性能低下的会话：

  ```
  agent_traces = {
      "cloudwatchLogs": {
          "logGroupArns": [
              "<log-group-arn>"
          ],
          "serviceNames": ["<service-name>"],
          "startTime": now - timedelta(days=7),
          "endTime": now,
          "rule": {
              "filters": [
                  {
                      "key": "goal_success_rate",
                      "operator": "LESS_THAN",
                      "value": {"doubleValue": 0.5}
                  }
              ]
          },
      }
  }
  ```

------
+  **内联会话跨度：在本地有可用的跟踪记录（例如，来自本地测试运行、 CI/CD 管道或要优化的特定会话）时**使用。您可以直接在 API 请求正文中以 OpenTelemetry-compatible 跨度对象列表的形式提供跨度。


<table>
<thead>
  <tr><th>字段</th><th>类型</th><th>必需</th><th>说明</th></tr>
</thead>
<tbody>
  <tr><td> <code>sessionSpans</code> </td><td>对象列表</td><td>是</td><td>代理跟踪跨度 OpenTelemetry-compatible 采用格式。每个跨度都包括跟踪 ID、跨度 ID、名称、时间戳和属性。</td></tr>
</tbody>
</table>
  
**Example**  

------
#### [ AgentCore CLI ]

  跨度文件（从本地 JSON 文件读取跨度并将其作为行内跨度传递）：

  ```
  agentcore run recommendation \
    --type system-prompt \
    --run my-prompt-rec \
    --runtime MyAgent \
    --evaluator Builtin.GoalSuccessRate \
    --inline "You are a helpful assistant..." \
    --spans-file agent-traces.json
  ```

  特定的会话 ID（CLI 收集客户端跨度并将其作为内联跨度传递）：

  ```
  agentcore run recommendation \
    --type system-prompt \
    --run my-prompt-rec \
    --runtime MyAgent \
    --evaluator Builtin.GoalSuccessRate \
    --inline "You are a helpful assistant..." \
    --session-id <session-id-1> <session-id-2>
  ```

------
#### [  Amazon SDK (boto3) ]

  ```
  import json
  
  with open("agent-traces.json") as f:
      spans = json.load(f)
  
  agent_traces = {
      "sessionSpans": spans
  }
  ```

------

**注意**  
批量评估和在线评估跟踪源仅适用于系统即时推荐。
+  **批量评估：当您完成了批量评估作业，要重复**使用其会话进行优化时使用。您可以直接通过其 ARN 引用批次评估，而不是从中重新收集跟踪 CloudWatch 或提供行内跨度。此来源仅适用于系统提示推荐。
  + 如果批量评估作业中使用的评估器与推荐请求中指定的评估者相匹配，则该服务会重复使用现有分数。
  + 如果评估者不匹配，则该服务会根据批量评估会话为请求的评估者运行新的评估。


<table>
<thead>
  <tr><th>字段</th><th>类型</th><th>必需</th><th>描述</th></tr>
</thead>
<tbody>
  <tr><td> <code>batchEvaluation.batchEvaluationArn</code> </td><td>字符串</td><td>是</td><td>已完成的批量评估作业的 ARN。该服务重复使用此任务中的会话作为跟踪输入。格式：<code>arn:aws:bedrock-agentcore:{region}:{account}:batch-evaluation/{id}</code>。</td></tr>
</tbody>
</table>
  
**Example**  

------
#### [  Amazon SDK (boto3) ]

    ```
    agent_traces = {
        "batchEvaluation": {
            "batchEvaluationArn": "<batch-evaluation-arn>"
        }
    }
    ```

------
+  **在线评估：当您的在线评估配置可以持续评估实时代理会话时**使用。由于在线评估是一个连续的过程，因此您必须指定一个时间窗口（`startTime`和`endTime`）限制该建议来自哪个评估会话。该服务在指定窗口内重复使用在线评估会话中的评估分数。此来源仅适用于系统提示推荐。


<table>
<thead>
  <tr><th>字段</th><th>类型</th><th>必需</th><th>描述</th></tr>
</thead>
<tbody>
  <tr><td> <code>onlineEvaluation.onlineEvaluationConfigArn</code> </td><td>字符串</td><td>是</td><td>在线评估配置的 ARN。该服务使用来自此配置的评估会话作为跟踪输入。格式：<code>arn:aws:bedrock-agentcore:{region}:{account}:online-evaluation-config/{id}</code>。</td></tr>
  <tr><td> <code>onlineEvaluation.startTime</code> </td><td>ISO 8601 日期时间</td><td>是</td><td>评估窗口的开始。仅包括在此时间之后评估的会话。</td></tr>
  <tr><td> <code>onlineEvaluation.endTime</code> </td><td>ISO 8601 日期时间</td><td>是</td><td>评估窗口结束。仅包括在此时间之前评估的会话。</td></tr>
</tbody>
</table>
  
**Example**  

------
#### [  Amazon SDK (boto3) ]

  ```
  from datetime import datetime, timedelta, timezone
  
  now = datetime.now(timezone.utc)
  
  agent_traces = {
      "onlineEvaluation": {
          "onlineEvaluationConfigArn": "<online-evaluation-config-arn>",
          "startTime": now - timedelta(days=7),
          "endTime": now,
      }
  }
  ```

------

**注意**  
 `agentcore run recommendation`是异步的。如果没有`--wait`，该命令将提交推荐任务并立即返回；该任务以非终端状态（例如`PENDING`或`IN_PROGRESS`）启动，您稍后再检索结果。传递`--wait`到区块，直到推荐达到终端状态。要轮询或检索已提交作业的结果，请运行`agentcore view recommendation <id>`，其中`id`是推荐任务 ID。

 AgentCore CLI 提供了映射到底层 API 跟踪源类型的便捷标志：


| CLI 标志 | API 映射 | 说明 | 
| --- | --- | --- | 
|  `--lookback <days>`  |  `cloudwatchLogs`使用计算`startTime`和 `endTime`  | 通过 CloudWatch 日志收集过去 N 天的跟踪。CLI 从运行时配置中解析日志组 ARN 和服务名称。 | 
|  `--session-id <id>`  |  `sessionSpans`（内联） | 收集客户端指定会话的跨度并将其作为内联会话跨度传递。推荐 API 本身不支持对 CloudWatch 源进行会话 ID 过滤。 | 
|  `--spans-file <path>`  |  `sessionSpans`（内联） | 从本地 JSON 文件读取跨度并将其作为内联会话跨度传递。 | 
|  `--wait`  | n/a （客户端投票） | 屏蔽直到推荐达到终端状态。 |