# Recommendations
<a name="optimization-recommendations"></a>

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](#recommendations-input-modes)
+ [Agent trace sources](#recommendations-trace-sources)
+ [Start a system prompt recommendation](recommendations-system-prompt.md)
+ [Start a tool description recommendation](recommendations-tool-description.md)
+ [Get recommendation](recommendations-get.md)
+ [List recommendations](recommendations-list.md)
+ [Delete recommendation](recommendations-delete.md)

## Configuration input modes
<a name="recommendations-input-modes"></a>

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.    
[See the AWS documentation website for more details](http://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/optimization-recommendations.html)
+  **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.    
[See the AWS documentation website for more details](http://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/optimization-recommendations.html)

  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
<a name="recommendations-trace-sources"></a>

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`.    
[See the AWS documentation website for more details](http://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/optimization-recommendations.html)  
**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.    
[See the AWS documentation website for more details](http://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/optimization-recommendations.html)  
**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. |