View a markdown version of this page

建议 - Amazon Bedrock AgentCore
配置输入模式代理追踪源

建议

建议使用 AI 从真实的会话跟踪中生成经过优化的代理配置。您无需手动重写提示或工具描述，而是将服务指向代理的踪迹，指定目标评估者作为奖励信号，然后获得优化的配置。

注意

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

Amazon Bedrock AgentCore 支持两种推荐类型：

  • 系统提示建议：分析代理跟踪并生成优化的系统提示，以提高目标评估者的性能。该服务可识别故障模式并添加特定的行为指令。

  • 工具描述建议：分析代理轨迹并生成更清晰的工具描述，从而减少工具选择的混乱。当代理为模棱两可的请求选择了错误的工具时，这很有用。

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

主题

配置输入模式

您可以通过以下两种方式之一提供当前配置：

  • 内联文本：在 API 请求中以字符串形式直接提供配置。要获得系统提示建议，请在systemPrompt.text字段中传递提示文本。要获得工具描述建议，请在toolDescription.toolDescriptionText.tools列表中传递每个工具的名称和描述。当你想测试正在积极迭代的提示时，或者当你的配置未存储在捆绑包中时，此模式对于快速实验非常有用。

    获取建议 CLI 标志 API 字段

    系统提示

    --inline "prompt text" 或 --prompt-file ./path.txt

    systemPrompt.text

    工具描述

    --tools "name:description, name:description"

    toolDescription.toolDescriptionText.tools: 带有toolName和的对象列表 toolDescription

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

    获取建议 CLI 标志 API 字段

    系统提示

    --bundle-name <bundle-name> + --bundle-version <bundle-version> + --system-prompt-json-path <path>

    systemPrompt.configurationBundle与bundleArn，versionId，systemPromptJsonPath

    工具描述

    --bundle-name <bundle-name>+ --bundle-version <bundle-version> +--tool-desc-json-path "name:jsonpath"（对每个工具重复此操作）

    toolDescription.configurationBundle带有bundleArn、versionId、和包含toolName和的tools列表 toolDescriptionJsonPath

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

代理追踪源

该agentTraces参数接受以下两个来源之一：

  • CloudWatch 日志：在代理运行时向 CloudWatch其写入遥测数据时使用。该服务在所需时间范围内直接从指定的日志组读取跟踪。您必须提供logGroupArnsserviceNames、startTime、和endTime。可选rule字段允许您筛选跟踪（例如，仅选择低于阈值的会话）。goal_success_rate

    注意

    推荐 API 使用日志组 ARN (logGroupArns)，而不是日志组名称。这不同于批量评估，后者使用logGroupNames。

    字段 类型 必需 说明

    cloudwatchLogs.logGroupArns

    字符串列表

    是

    CloudWatch 记录存储代理遥测数据的日志组 ARN。格式：arn:aws:logs:{region}:{account}:log-group:{log-group-name}。

    cloudwatchLogs.serviceNames

    字符串列表

    是

    用于识别您的代理跟踪的服务名称 CloudWatch。惯例：{RuntimeName}.DEFAULT。

    cloudwatchLogs.startTime

    ISO 8601 日期时间

    是

    追踪收集窗口的开始。仅包括此时间之后的痕迹。

    cloudwatchLogs.endTime

    ISO 8601 日期时间

    是

    追踪收集窗口的结束。仅包括此时间之前的痕迹。

    cloudwatchLogs.rule

    对象

    否

    用于缩小跟踪选择范围的可选过滤规则。包含一个filters列表，其中每个过滤器都指定key、operator（例如LESS_THAN）和value（例如{"doubleValue": 0.5}）。
    例
    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
    AWS 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 跨度对象列表的形式提供跨度。

    字段 类型 必需 说明

    sessionSpans

    对象列表

    是

    代理跟踪跨度 OpenTelemetry-compatible 采用格式。每个跨度都包括跟踪 ID、跨度 ID、名称、时间戳和属性。
    例
    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>
    AWS SDK (boto3)
    import json

with open("agent-traces.json") as f:
    spans = json.load(f)

agent_traces = {
    "sessionSpans": spans
}
注意

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 （客户端轮询）

封锁直到建议达到终止状态。