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

# 启动系统提示推荐
<a name="recommendations-system-prompt"></a>

开始提出建议，为您的代理生成优化的系统提示。该服务分析代理跟踪，确定故障模式，并生成修订后的系统提示音，以提高目标评估器的性能。

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

## 代码示例
<a name="start-sysprompt-rec-examples"></a>

**Example**  
CLI 接受多个跟踪源和三种系统提示输入模式。根据需要将它们组合在一起：  
+  **追踪来源：** CloudWatch 日志 (`--lookback`)、行内跨度 (`--spans-file`)、本地洞察运行（`--from-insights <id>`— 使用本地见解作为跟踪源；解析批量评估 ARN）或直接批量评估 ARN（`--batch-evaluation-arn <arn>`— 直接使用批量评估 ARN 作为跟踪源）
+  **系统提示输入：**行内文本 (`--inline`)、提示文件 (`--prompt-file`) 或配置包 (`--bundle-name`)
+  **可选过滤器：用于缩小分析跟踪范围的**特定会话 ID (`--session-id`)
+  **可选加密：**KMS 密钥（`--kms-key <arn>`— 用于加密推荐结果的 KMS 密钥 ARN）

  

   **带有 CloudWatch 跟踪的内联系统提示符：**

  ```
  agentcore run recommendation \
    --type system-prompt \
    --run my-prompt-rec \
    --runtime MyAgent \
    --evaluator Builtin.GoalSuccessRate \
    --inline "You are a helpful customer support assistant. Help users with their orders and returns." \
    --lookback 7 \
    --wait
  ```

   `run recommendation`启动异步任务并仅返回 a `recommendationId` 和初始`PENDING`或`IN_PROGRESS`状态。`--wait`添加到区块中，直到推荐达到终端状态。要稍后检索已完成的结果，请参阅[检索结果](#start-sysprompt-rec-retrieve)。

   **来自带有 CloudWatch 跟踪的文件的内联系统提示：**

  ```
  agentcore run recommendation \
    --type system-prompt \
    --run my-prompt-rec \
    --runtime MyAgent \
    --evaluator Builtin.GoalSuccessRate \
    --prompt-file ./system-prompt.txt \
    --lookback 7
  ```

   **带有 spans 文件的内联系统提示符：**

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

   **带有 CloudWatch 跟踪的配置包：**

  CLI 自动解析代理运行时 ARN 父对象的完整 JSON 路径。`configuration`您只需要提供包含系统提示符的密钥名称。

  ```
  agentcore run recommendation \
    --type system-prompt \
    --run my-prompt-rec \
    --runtime MyAgent \
    --evaluator Builtin.GoalSuccessRate \
    --bundle-name <bundle-name> \
    --bundle-version <bundle-version> \
    --system-prompt-json-path "system_prompt" \
    --lookback 7
  ```

  <a name="start-sysprompt-rec-retrieve"></a> **检索结果：**

  `view recommendation`与推荐任务 ID 一起使用以获取完成的结果。添加包含`recommendedSystemPrompt`和`--json``explanation`的机器可读输出。

  ```
  agentcore view recommendation <recommendation-id> --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-prompt-rec",
    type="SYSTEM_PROMPT_RECOMMENDATION",
    recommendationConfig={
        "systemPromptRecommendationConfig": {
            "systemPrompt": {
                "text": "You are a helpful customer support assistant. Help users with their orders and returns."
            },
            "agentTraces": {
                "cloudwatchLogs": {
                    "logGroupArns": [
                        "<log-group-arn>"
                    ],
                    "serviceNames": ["<service-name>"],
                    "startTime": now - timedelta(days=7),
                    "endTime": now,
                }
            },
            "evaluationConfig": {
                "evaluators": [
                    {"evaluatorArn": "arn:aws:bedrock-agentcore:::evaluator/Builtin.GoalSuccessRate"}
                ]
            },
        }
    },
    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-prompt-rec-spans",
    type="SYSTEM_PROMPT_RECOMMENDATION",
    recommendationConfig={
        "systemPromptRecommendationConfig": {
            "systemPrompt": {
                "text": "You are a helpful customer support assistant."
            },
            "agentTraces": {
                "sessionSpans": spans
            },
            "evaluationConfig": {
                "evaluators": [
                    {"evaluatorArn": "arn:aws:bedrock-agentcore:::evaluator/Builtin.GoalSuccessRate"}
                ]
            },
        }
    },
    clientToken=str(uuid.uuid4()),
)
```
带有 CloudWatch 跟踪的配置包：  

```
response = client.start_recommendation(
    name="my-bundle-prompt-rec",
    type="SYSTEM_PROMPT_RECOMMENDATION",
    recommendationConfig={
        "systemPromptRecommendationConfig": {
            "systemPrompt": {
                "configurationBundle": {
                    "bundleArn": "<bundle-arn>",
                    "versionId": "<bundle-version>",
                    "systemPromptJsonPath": "$.configuration.system_prompt",
                }
            },
            "agentTraces": {
                "cloudwatchLogs": {
                    "logGroupArns": [
                        "<log-group-arn>"
                    ],
                    "serviceNames": ["<service-name>"],
                    "startTime": now - timedelta(days=7),
                    "endTime": now,
                }
            },
            "evaluationConfig": {
                "evaluators": [
                    {"evaluatorArn": "arn:aws:bedrock-agentcore:::evaluator/Builtin.GoalSuccessRate"}
                ]
            },
        }
    },
    clientToken=str(uuid.uuid4()),
)
```
包含内联跨度的配置包：  

```
response = client.start_recommendation(
    name="my-bundle-prompt-rec-spans",
    type="SYSTEM_PROMPT_RECOMMENDATION",
    recommendationConfig={
        "systemPromptRecommendationConfig": {
            "systemPrompt": {
                "configurationBundle": {
                    "bundleArn": "<bundle-arn>",
                    "versionId": "<bundle-version>",
                    "systemPromptJsonPath": "$.configuration.system_prompt",
                }
            },
            "agentTraces": {
                "sessionSpans": spans
            },
            "evaluationConfig": {
                "evaluators": [
                    {"evaluatorArn": "arn:aws:bedrock-agentcore:::evaluator/Builtin.GoalSuccessRate"}
                ]
            },
        }
    },
    clientToken=str(uuid.uuid4()),
)
```

## 请求参数
<a name="start-sysprompt-rec-params"></a>


| 参数 | Type | 必需 | 描述 | 
| --- | --- | --- | --- | 
|  `name`  | 字符串 | 是 | 推荐的名称。最多 48 个字符。图案：`[a-zA-Z][a-zA-Z0-9_-]{0,47}`。 | 
|  `type`  | 字符串 | 是 | 必须是 `SYSTEM_PROMPT_RECOMMENDATION`。 | 
|  `recommendationConfig`  | 对象 | 是 | `systemPromptRecommendationConfig`包含建议的配置。 | 
|  `description`  | 字符串 | 否 | 可选描述。最多 4096 个字符。 | 
|  `clientToken`  | 字符串 | 否 | 等效性标记。如果您使用相同的客户端令牌重试请求，该服务将返回现有建议，而不是创建新的建议。 | 

### 系统PromptRecommendationConfig 字段
<a name="start-sysprompt-rec-config"></a>


| 字段 | 类型 | 必需 | 说明 | 
| --- | --- | --- | --- | 
|  `systemPrompt`  | Union | 是 | 当前系统提示要优化。提供`text`（行内字符串，最多 20,000 个字符）或`configurationBundle`（捆绑引用）。 | 
|  `agentTraces`  | Union | 是 | 用于分析的追踪来源。有关建议，请参阅[追踪来源](optimization-recommendations.md#recommendations-trace-sources)。 | 
|  `evaluationConfig`  | 对象 | 是 | 指定目标评估者的评估配置。包含一个仅包含一个评估者参考的`evaluators`列表。 | 

## 选择评估员
<a name="start-sysprompt-rec-evaluator"></a>

选择与要改进的方向对齐的评估器。您选择的评估器决定建议的优化方向；无论评估者的得分高如何，都是优化器将提示推送到的方向。

您可以使用[内置评估器](built-in-evaluators-overview.md)或提供自定义评估器 ARN。使用以下准则进行选择：
+ 如果您的代理有明确的任务要完成（预订、检索、多步工作流程），`Builtin.GoalSuccessRate`这是正确的信号。
+ 如果你的代理更开放，而且你关心互动本身的质量，`Builtin.Helpfulness`那就更合适了。
+ 如果您关心的质量是特定领域的，或者不是由内置评估器捕获的，请使用自定义评估器来最好地表示测量结果。

**注意**  
推荐支持内置 LLM-as-judge、自定义和基于代码的评估器，但要求评估器返回数值作为优化信号。对于自定义 LLM-as-judge 评估器，使用`numerical`比例`ratingScale`进行配置（不是`categorical`）。对于基于代码的评估器，请在[响应架构中包含该`value`字段。](code-based-evaluators.md#code-based-response-schema)

在 API 中，仅使用一个评估器参考来指定`evaluationConfig.evaluators`列表中的评估者：

```
"evaluationConfig": {
    "evaluators": [
        {"evaluatorArn": "arn:aws:bedrock-agentcore:::evaluator/Builtin.GoalSuccessRate"}
    ]
}
```

在 CLI 中，使用以下`--evaluator`标志：

```
--evaluator Builtin.GoalSuccessRate
```

## 系统提示输入模式
<a name="start-sysprompt-rec-input-modes"></a>


| Mode | CLI 标志 | API 字段 | 
| --- | --- | --- | 
| 行内文本 |  `--inline "prompt text"` 或 `--prompt-file ./path.txt`  |  `systemPrompt.text`  | 
| 配置包 |  `--bundle-name <bundle-name>` \+ `--bundle-version <bundle-version>` \+ `--system-prompt-json-path <path>`  |  `systemPrompt.configurationBundle`用`bundleArn`，`versionId`，`systemPromptJsonPath` | 

使用配置包时，结果包括应用了优化系统提示的新捆绑包版本。

## 响应
<a name="start-sysprompt-rec-response"></a>


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

## 推荐结果
<a name="start-sysprompt-rec-result"></a>

当推荐达到`COMPLETED`状态（通过 “[获取推荐” 检索](recommendations-get.md)）时，结果包含：


| 字段 | Type | 说明 | 
| --- | --- | --- | 
|  `recommendedSystemPrompt`  | 字符串 | 优化的系统提示文本。 | 
|  `configurationBundle`  | 对象 | 当输入是配置包时出现。包含`bundleArn`并`versionId`指向应用了优化提示的新捆绑包版本。 | 
|  `explanation`  | 字符串 | 解释提出该建议的原因以及修改建议背后的理由。 | 
|  `errorCode`  | 字符串 | 如果建议失败，则出现。描述故障的错误代码。 | 
|  `errorMessage`  | 字符串 | 如果建议失败，则出现。 Human-readable 错误描述。 | 

## 错误
<a name="start-sysprompt-rec-errors"></a>


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