启动系统提示建议

启动建议，为您的代理生成经过优化的系统提示。该服务分析代理跟踪，识别故障模式，并生成修订后的系统提示，以提高目标评估者的性能。

注意

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

代码示例

例

AgentCore CLI

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添加到区块中，直到建议达到终止状态。要稍后检索已完成的结果，请参阅检索结果。

来自带有 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

检索结果：

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


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-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()),
)

请求参数

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

系统PromptRecommendationConfig 字段

字段	类型	必需	说明
`systemPrompt`	Union	是	当前系统提示进行优化。提供`text`（行内字符串，最多 20,000 个字符）或`configurationBundle`（捆绑包引用）。
`agentTraces`	Union	是	追踪来源进行分析。有关建议，请参阅追踪来源。
`evaluationConfig`	对象	是	指定目标评估者的评估配置。包含一个只有一个赋值器参考的`evaluators`列表。

选择评估者

选择与您想要改进的方向对齐的赋值器。您选择的赋值器决定了建议的优化方向；无论评估者得分很高，优化器都会将提示推向什么。

您可以使用内置评估器或提供自定义评估器 ARN。使用以下准则进行选择：

如果您的代理有明确的任务要完成（预订、取回、多步骤工作流程），那么Builtin.GoalSuccessRate这是正确的信号。
如果你的代理人更具开放性，并且你关心互动本身的质量，那Builtin.Helpfulness就更合适了。
如果您关心的质量是特定领域的，或者不是由内置评估器捕获的，请使用自定义评估器来最好地表示测量结果。

注意

推荐支持内置 LLM-as-judge、自定义和基于代码的赋值器，但要求评估器返回一个数值作为优化信号。对于自定义 LLM-as-judge 赋值器，请ratingScale使用numerical比例（不是categorical）进行配置。对于基于代码的赋值器，请在响应架构中包含value字段。

在 API 中，在evaluationConfig.evaluators列表中指定仅包含一个赋值器参考的赋值器：


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

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


--evaluator Builtin.GoalSuccessRate

系统提示输入模式

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`

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

响应

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

字段	Type	说明
`recommendedSystemPrompt`	字符串	优化的系统提示文本。
`configurationBundle`	对象	当输入为配置包时出现。包含`bundleArn`并`versionId`指向已应用优化提示的新捆绑包版本。
`explanation`	字符串	解释产生该建议的原因以及建议的修改背后的原因。
`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。请参阅浏览器的帮助页面以了解相关说明。

文档惯例

建议

刀具描述推荐