View a markdown version of this page

Recommendations - Amazon Bedrock AgentCore
Configuration input modesAgent trace sources

Recommendations

Recommendations use AI to generate optimized agent configurations from real session traces. Instead of manually rewriting prompts or tool descriptions, you point the service at your agent’s traces, specify a target evaluator as the reward signal, and receive an optimized configuration.

Note

Recommendations are generated by LLMs. Review and test before applying them.

Amazon Bedrock AgentCore supports two recommendation types:

  • System prompt recommendation: Analyzes agent traces and generates an optimized system prompt that improves performance on the target evaluator. The service identifies failure patterns and adds specific behavioral instructions.

  • Tool description recommendation: Analyzes agent traces and generates sharpened tool descriptions that reduce tool selection confusion. This is useful when agents select the wrong tool for ambiguous requests.

Each recommendation requires two inputs: the current agent configuration to optimize, and agent traces to analyze.

Topics

Configuration input modes

You provide the current configuration in one of two ways:

  • Inline text: Provide the configuration directly as a string in the API request. For system prompt recommendations, pass the prompt text in the systemPrompt.text field. For tool description recommendations, pass each tool’s name and description in the toolDescription.toolDescriptionText.tools list. This mode is useful for quick experimentation, when you want to test a prompt you are actively iterating on, or when your configuration is not stored in a bundle.

    Recommendation type CLI flags API field

    System prompt

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

    systemPrompt.text

    Tool description

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

    toolDescription.toolDescriptionText.tools: list of objects with toolName and toolDescription

  • Configuration bundle: Reference an existing configuration bundle version. The service reads the current configuration from the bundle using the JSON path you specify, generates the optimized version, and writes the result back to a new bundle version. This keeps your optimization history versioned alongside your bundle. This mode is useful when you manage configurations centrally with configuration bundles and want the optimized output written back to the bundle automatically.

    Recommendation type CLI flags API field

    System prompt

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

    systemPrompt.configurationBundle with bundleArn, versionId, systemPromptJsonPath

    Tool description

    --bundle-name <bundle-name> + --bundle-version <bundle-version> + --tool-desc-json-path "name:jsonpath" (repeat for each tool)

    toolDescription.configurationBundle with bundleArn, versionId, and tools list containing toolName and toolDescriptionJsonPath

    When using a configuration bundle, the recommendation result includes a configurationBundle field with the bundleArn and a new versionId pointing to the bundle version that contains the optimized configuration.

Agent trace sources

The agentTraces parameter accepts one of two sources:

  • CloudWatch Logs: Use when your agent runtime writes telemetry to CloudWatch. The service reads traces directly from the specified log groups within a required time range. You must provide logGroupArns, serviceNames, startTime, and endTime. An optional rule field allows you to filter traces (for example, selecting only sessions where goal_success_rate is below a threshold).

    Note

    The recommendations API uses log group ARNs (logGroupArns), not log group names. This differs from batch evaluations, which use logGroupNames.

    Field Type Required Description

    cloudwatchLogs.logGroupArns

    List of strings

    Yes

    CloudWatch Logs log group ARNs where agent telemetry is stored. Format: arn:aws:logs:{region}:{account}:log-group:{log-group-name}.

    cloudwatchLogs.serviceNames

    List of strings

    Yes

    Service names that identify your agent’s traces in CloudWatch. Convention: {RuntimeName}.DEFAULT.

    cloudwatchLogs.startTime

    ISO 8601 datetime

    Yes

    Start of the trace collection window. Only traces after this time are included.

    cloudwatchLogs.endTime

    ISO 8601 datetime

    Yes

    End of the trace collection window. Only traces before this time are included.

    cloudwatchLogs.rule

    Object

    No

    Optional filter rule to narrow trace selection. Contains a filters list where each filter specifies a key, operator (such as LESS_THAN), and value (such as {"doubleValue": 0.5}).
    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
    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,
    }
}

    With an optional rule filter to select only low-performing sessions:

    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}
                }
            ]
        },
    }
}

  • Inline session spans: Use when you have traces available locally (for example, from a local test run, a CI/CD pipeline, or a specific session you want to optimize against). You provide the spans directly in the API request body as a list of OpenTelemetry-compatible span objects.

    Field Type Required Description

    sessionSpans

    List of objects

    Yes

    Agent trace spans in OpenTelemetry-compatible format. Each span includes trace ID, span ID, name, timestamps, and attributes.
    Example
    AgentCore CLI

    Spans file (reads spans from a local JSON file and passes them as inline spans):

    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

    Specific session IDs (the CLI collects spans client-side and passes them as inline spans):

    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
}

The AgentCore CLI provides convenience flags that map to the underlying API trace source types:

CLI flag API mapping Description

--lookback <days>

cloudwatchLogs with computed startTime and endTime

Collects traces from the last N days via CloudWatch Logs. The CLI resolves log group ARNs and service names from the runtime configuration.

--session-id <id>

sessionSpans (inline)

Collects spans for the specified session client-side and passes them as inline session spans. The recommendation API itself does not support session ID filtering on CloudWatch sources.

--spans-file <path>

sessionSpans (inline)

Reads spans from a local JSON file and passes them as inline session spans.