# Start a system prompt recommendation
<a name="recommendations-system-prompt"></a>

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
<a name="start-sysprompt-rec-examples"></a>

**Example**  
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
  ```
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
<a name="start-sysprompt-rec-params"></a>


| 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
<a name="start-sysprompt-rec-config"></a>


| 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](optimization-recommendations.md#recommendations-trace-sources). | 
|  `evaluationConfig`  | Object | Yes | Evaluation configuration specifying the target evaluator. Contains an `evaluators` list with exactly one evaluator reference. | 

## Choosing an evaluator
<a name="start-sysprompt-rec-evaluator"></a>

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](built-in-evaluators-overview.md) 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
<a name="start-sysprompt-rec-input-modes"></a>


| 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
<a name="start-sysprompt-rec-response"></a>


| 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
<a name="start-sysprompt-rec-result"></a>

When the recommendation reaches `COMPLETED` status (retrieved via [Get a recommendation](recommendations-get.md)), 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
<a name="start-sysprompt-rec-errors"></a>


| 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. |