View a markdown version of this page

Start a system prompt recommendation - Amazon Bedrock AgentCore
Code samplesRequest parametersChoosing an evaluatorSystem prompt input modesResponseRecommendation resultErrors

Start a system prompt recommendation

Start a recommendation to generate an optimized system prompt for your agent. The service analyzes agent traces, identifies failure patterns, and produces a revised system prompt that improves performance on the target evaluator.

Note

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

Code samples

Example
AgentCore CLI

The CLI accepts two trace sources and three system prompt input modes. Combine them as needed:

  • Trace sources: CloudWatch Logs (--lookback) or inline spans (--spans-file)

  • System prompt input: inline text (--inline), prompt file (--prompt-file), or configuration bundle (--bundle-name)

  • Optional filter: specific session IDs (--session-id) to narrow which traces are analyzed

    Inline system prompt with CloudWatch traces: 

    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

    Inline system prompt from a file with CloudWatch traces: 

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

    Inline system prompt with a spans file: 

    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

    Inline system prompt with specific session IDs:

    The CLI collects spans for the specified session 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 customer support assistant." \
  --session-id <session-id-1> <session-id-2>

    Configuration bundle with CloudWatch traces:

    The CLI auto-resolves the full JSON path from the agent runtime ARN’s configuration parent object. You only need to provide the key name that contains the system prompt.

    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
AWS SDK (boto3)

Inline text with CloudWatch traces:

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']}")

Inline text with inline spans:

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

Configuration bundle with CloudWatch traces:

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

Configuration bundle with inline spans:

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

Request parameters

Parameter Type Required Description

name

String

Yes

A name for the recommendation. Maximum 48 characters. Pattern: [a-zA-Z][a-zA-Z0-9_-]{0,47}.

type

String

Yes

Must be SYSTEM_PROMPT_RECOMMENDATION.

recommendationConfig

Object

Yes

Contains systemPromptRecommendationConfig with the configuration for the recommendation.

description

String

No

Optional description. Maximum 4096 characters.

clientToken

String

No

Idempotency token. If you retry a request with the same client token, the service returns the existing recommendation instead of creating a new one.

systemPromptRecommendationConfig fields

Field Type Required Description

systemPrompt

Union

Yes

The current system prompt to optimize. Provide either text (inline string, maximum 20,000 characters) or configurationBundle (bundle reference).

agentTraces

Union

Yes

Trace source for analysis. See Trace sources for recommendations.

evaluationConfig

Object

Yes

Evaluation configuration specifying the target evaluator. Contains an evaluators list with exactly one evaluator reference.

Choosing an evaluator

Select an evaluator aligned with the direction you want to improve. The evaluator you select determines what the recommendation optimizes toward; whatever the evaluator scores highly is what the optimizer pushes the prompt toward.

You can use a built-in evaluator or provide a custom evaluator ARN. Use the following guidelines to choose:

  • If your agent has a clear task to complete (booking, retrieval, a multi-step workflow), Builtin.GoalSuccessRate is the right signal.

  • If your agent is more open-ended and you care about the quality of the interaction itself, Builtin.Helpfulness is a better fit.

  • If the quality you care about is domain-specific or not captured by a built-in evaluator, use a custom evaluator to best represent the measurement.

In the API, specify the evaluator in the evaluationConfig.evaluators list with exactly one evaluator reference:

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

In the CLI, use the --evaluator flag:

--evaluator Builtin.GoalSuccessRate

System prompt input modes

Mode CLI flags API field

Inline text

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

systemPrompt.text

Configuration bundle

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

systemPrompt.configurationBundle with bundleArn, versionId, systemPromptJsonPath

When using a configuration bundle, the result includes a new bundle version with the optimized system prompt applied.

Response

Field Type Description

recommendationId

String

Unique identifier for the recommendation.

recommendationArn

String

ARN of the recommendation.

name

String

The name you specified.

type

String

SYSTEM_PROMPT_RECOMMENDATION.

status

String

Initial status: PENDING or IN_PROGRESS.

createdAt

Timestamp

When the recommendation was created.

updatedAt

Timestamp

When the recommendation was last updated.

Recommendation result

When the recommendation reaches COMPLETED status (retrieved via Get a recommendation), the result contains:

Field Type Description

recommendedSystemPrompt

String

The optimized system prompt text.

configurationBundle

Object

Present when the input was a configuration bundle. Contains bundleArn and versionId pointing to a new bundle version with the optimized prompt applied.

errorCode

String

Present if the recommendation failed. Error code describing the failure.

errorMessage

String

Present if the recommendation failed. Human-readable error description.

Errors

Error HTTP status Description

ValidationException

400

Invalid request parameters. Check field constraints and required fields.

AccessDeniedException

403

Insufficient permissions. Verify IAM policies.

ConflictException

409

A recommendation with the same client token already exists with different parameters.

ServiceQuotaExceededException

402

You have exceeded the maximum number of concurrent recommendations.

ThrottlingException

429

Request rate exceeded. Retry with exponential backoff.

InternalServerException

500

Service-side error. Retry the request.