BedrockAgentCore / Client / start_recommendation

start_recommendation¶

BedrockAgentCore.Client.start_recommendation(**kwargs)¶

Starts a recommendation job that analyzes agent traces and generates optimization suggestions for system prompts or tool descriptions to improve agent performance.

Request Syntax

response = client.start_recommendation(
    name='string',
    description='string',
    type='SYSTEM_PROMPT_RECOMMENDATION'|'TOOL_DESCRIPTION_RECOMMENDATION',
    recommendationConfig={
        'systemPromptRecommendationConfig': {
            'systemPrompt': {
                'text': 'string',
                'configurationBundle': {
                    'bundleArn': 'string',
                    'versionId': 'string',
                    'systemPromptJsonPath': 'string'
                }
            },
            'agentTraces': {
                'sessionSpans': [
                    {...}|[...]|123|123.4|'string'|True|None,
                ],
                'cloudwatchLogs': {
                    'logGroupArns': [
                        'string',
                    ],
                    'serviceNames': [
                        'string',
                    ],
                    'startTime': datetime(2015, 1, 1),
                    'endTime': datetime(2015, 1, 1),
                    'rule': {
                        'filters': [
                            {
                                'key': 'string',
                                'operator': 'Equals'|'NotEquals'|'GreaterThan'|'LessThan'|'GreaterThanOrEqual'|'LessThanOrEqual'|'Contains'|'NotContains',
                                'value': {
                                    'stringValue': 'string',
                                    'doubleValue': 123.0,
                                    'booleanValue': True|False
                                }
                            },
                        ]
                    }
                }
            },
            'evaluationConfig': {
                'evaluators': [
                    {
                        'evaluatorArn': 'string'
                    },
                ]
            }
        },
        'toolDescriptionRecommendationConfig': {
            'toolDescription': {
                'toolDescriptionText': {
                    'tools': [
                        {
                            'toolName': 'string',
                            'toolDescription': {
                                'text': 'string'
                            }
                        },
                    ]
                },
                'configurationBundle': {
                    'bundleArn': 'string',
                    'versionId': 'string',
                    'tools': [
                        {
                            'toolName': 'string',
                            'toolDescriptionJsonPath': 'string'
                        },
                    ]
                }
            },
            'agentTraces': {
                'sessionSpans': [
                    {...}|[...]|123|123.4|'string'|True|None,
                ],
                'cloudwatchLogs': {
                    'logGroupArns': [
                        'string',
                    ],
                    'serviceNames': [
                        'string',
                    ],
                    'startTime': datetime(2015, 1, 1),
                    'endTime': datetime(2015, 1, 1),
                    'rule': {
                        'filters': [
                            {
                                'key': 'string',
                                'operator': 'Equals'|'NotEquals'|'GreaterThan'|'LessThan'|'GreaterThanOrEqual'|'LessThanOrEqual'|'Contains'|'NotContains',
                                'value': {
                                    'stringValue': 'string',
                                    'doubleValue': 123.0,
                                    'booleanValue': True|False
                                }
                            },
                        ]
                    }
                }
            }
        }
    },
    clientToken='string'
)

Parameters:

name (string) –
[REQUIRED]

The name of the recommendation. Must be unique within your account.
description (string) – The description of the recommendation.
type (string) –
[REQUIRED]

The type of recommendation to generate. Valid values are SYSTEM_PROMPT_RECOMMENDATION for system prompt optimization or TOOL_DESCRIPTION_RECOMMENDATION for tool description optimization.
recommendationConfig (dict) –
[REQUIRED]

The configuration for the recommendation, including the input to optimize, agent traces to analyze, and evaluation settings.

Note
This is a Tagged Union structure. Only one of the following top level keys can be set: systemPromptRecommendationConfig, toolDescriptionRecommendationConfig.
- systemPromptRecommendationConfig (dict) –
  
  The configuration for a system prompt recommendation.
  - systemPrompt (dict) – [REQUIRED]
    
    The current system prompt to optimize.
    
    Note
    This is a Tagged Union structure. Only one of the following top level keys can be set: text, configurationBundle.
    - text (string) –
      
      The system prompt text provided inline.
    - configurationBundle (dict) –
      
      The system prompt sourced from a configuration bundle version.
      - bundleArn (string) – [REQUIRED]
        
        The Amazon Resource Name (ARN) of the configuration bundle.
      - versionId (string) – [REQUIRED]
        
        The version identifier of the configuration bundle.
      - systemPromptJsonPath (string) – [REQUIRED]
        
        The JSON path within the configuration bundle that contains the system prompt.
  - agentTraces (dict) – [REQUIRED]
    
    The agent traces to analyze for generating recommendations.
    
    Note
    This is a Tagged Union structure. Only one of the following top level keys can be set: sessionSpans, cloudwatchLogs.
    - sessionSpans (list) –
      
      Agent traces provided as inline session spans in OpenTelemetry format.
      - (document) –
    - cloudwatchLogs (dict) –
      
      Agent traces read from CloudWatch Logs.
      - logGroupArns (list) – [REQUIRED]
        
        The list of CloudWatch log group ARNs to read agent traces from.
        
        (string) –
      - serviceNames (list) – [REQUIRED]
        
        The list of service names to filter traces within the specified log groups.
        
        (string) –
      - startTime (datetime) – [REQUIRED]
        
        The start time of the time range to read traces from.
      - endTime (datetime) – [REQUIRED]
        
        The end time of the time range to read traces from.
      - rule (dict) –
        
        Optional rule configuration for filtering traces.
        
        filters (list) –
        
        The list of filters to apply when reading agent traces.
        
        (dict) –
        
        A filter for narrowing down agent traces from CloudWatch Logs based on key-value comparisons.
        
        key (string) – [REQUIRED]
        
        The key or field name to filter on within the agent trace data.
        
        operator (string) – [REQUIRED]
        
        The comparison operator to use for filtering.
        
        value (dict) – [REQUIRED]
        
        The value to compare against using the specified operator.
        
        Note
        This is a Tagged Union structure. Only one of the following top level keys can be set: stringValue, doubleValue, booleanValue.
        
        stringValue (string) –
        
        A string value for text-based filtering.
        
        doubleValue (float) –
        
        A numeric value for numerical filtering and comparisons.
        
        booleanValue (boolean) –
        
        A boolean value for true/false filtering conditions.
  - evaluationConfig (dict) – [REQUIRED]
    
    The evaluation configuration specifying which evaluator to use for assessing recommendation quality.
    - evaluators (list) – [REQUIRED]
      
      The list of evaluators to use for assessing recommendation quality.
      - (dict) –
        
        A reference to an evaluator used for recommendation assessment.
        
        evaluatorArn (string) – [REQUIRED]
        
        The Amazon Resource Name (ARN) of the evaluator.
- toolDescriptionRecommendationConfig (dict) –
  
  The configuration for a tool description recommendation.
  - toolDescription (dict) – [REQUIRED]
    
    The current tool descriptions to optimize.
    
    Note
    This is a Tagged Union structure. Only one of the following top level keys can be set: toolDescriptionText, configurationBundle.
    - toolDescriptionText (dict) –
      
      Tool descriptions provided as inline text.
      - tools (list) – [REQUIRED]
        
        The list of tool descriptions to optimize.
        
        (dict) –
        
        A tool description input containing the tool name and its current description.
        
        toolName (string) – [REQUIRED]
        
        The name of the tool.
        
        toolDescription (dict) – [REQUIRED]
        
        The current description of the tool to optimize.
        
        Note
        This is a Tagged Union structure. Only one of the following top level keys can be set: text.
        
        text (string) –
        
        The tool description as inline text.
    - configurationBundle (dict) –
      
      Tool descriptions sourced from a configuration bundle version.
      - bundleArn (string) – [REQUIRED]
        
        The Amazon Resource Name (ARN) of the configuration bundle.
      - versionId (string) – [REQUIRED]
        
        The version identifier of the configuration bundle.
      - tools (list) – [REQUIRED]
        
        The list of tool entries mapping tool names to their JSON paths within the bundle.
        
        (dict) –
        
        Maps a tool name to its JSON path within a configuration bundle.
        
        toolName (string) – [REQUIRED]
        
        The name of the tool.
        
        toolDescriptionJsonPath (string) – [REQUIRED]
        
        The JSON path within the configuration bundle’s components that contains the tool description.
  - agentTraces (dict) – [REQUIRED]
    
    The agent traces to analyze for generating tool description recommendations.
    
    Note
    This is a Tagged Union structure. Only one of the following top level keys can be set: sessionSpans, cloudwatchLogs.
    - sessionSpans (list) –
      
      Agent traces provided as inline session spans in OpenTelemetry format.
      - (document) –
    - cloudwatchLogs (dict) –
      
      Agent traces read from CloudWatch Logs.
      - logGroupArns (list) – [REQUIRED]
        
        The list of CloudWatch log group ARNs to read agent traces from.
        
        (string) –
      - serviceNames (list) – [REQUIRED]
        
        The list of service names to filter traces within the specified log groups.
        
        (string) –
      - startTime (datetime) – [REQUIRED]
        
        The start time of the time range to read traces from.
      - endTime (datetime) – [REQUIRED]
        
        The end time of the time range to read traces from.
      - rule (dict) –
        
        Optional rule configuration for filtering traces.
        
        filters (list) –
        
        The list of filters to apply when reading agent traces.
        
        (dict) –
        
        A filter for narrowing down agent traces from CloudWatch Logs based on key-value comparisons.
        
        key (string) – [REQUIRED]
        
        The key or field name to filter on within the agent trace data.
        
        operator (string) – [REQUIRED]
        
        The comparison operator to use for filtering.
        
        value (dict) – [REQUIRED]
        
        The value to compare against using the specified operator.
        
        Note
        This is a Tagged Union structure. Only one of the following top level keys can be set: stringValue, doubleValue, booleanValue.
        
        stringValue (string) –
        
        A string value for text-based filtering.
        
        doubleValue (float) –
        
        A numeric value for numerical filtering and comparisons.
        
        booleanValue (boolean) –
        
        A boolean value for true/false filtering conditions.
clientToken (string) –
A unique, case-sensitive identifier to ensure that the API request completes no more than one time. If this token matches a previous request, the service ignores the request, but does not return an error.

This field is autopopulated if not provided.

Return type:

dict

Returns:

Response Syntax

{
    'recommendationId': 'string',
    'recommendationArn': 'string',
    'name': 'string',
    'description': 'string',
    'type': 'SYSTEM_PROMPT_RECOMMENDATION'|'TOOL_DESCRIPTION_RECOMMENDATION',
    'recommendationConfig': {
        'systemPromptRecommendationConfig': {
            'systemPrompt': {
                'text': 'string',
                'configurationBundle': {
                    'bundleArn': 'string',
                    'versionId': 'string',
                    'systemPromptJsonPath': 'string'
                }
            },
            'agentTraces': {
                'sessionSpans': [
                    {...}|[...]|123|123.4|'string'|True|None,
                ],
                'cloudwatchLogs': {
                    'logGroupArns': [
                        'string',
                    ],
                    'serviceNames': [
                        'string',
                    ],
                    'startTime': datetime(2015, 1, 1),
                    'endTime': datetime(2015, 1, 1),
                    'rule': {
                        'filters': [
                            {
                                'key': 'string',
                                'operator': 'Equals'|'NotEquals'|'GreaterThan'|'LessThan'|'GreaterThanOrEqual'|'LessThanOrEqual'|'Contains'|'NotContains',
                                'value': {
                                    'stringValue': 'string',
                                    'doubleValue': 123.0,
                                    'booleanValue': True|False
                                }
                            },
                        ]
                    }
                }
            },
            'evaluationConfig': {
                'evaluators': [
                    {
                        'evaluatorArn': 'string'
                    },
                ]
            }
        },
        'toolDescriptionRecommendationConfig': {
            'toolDescription': {
                'toolDescriptionText': {
                    'tools': [
                        {
                            'toolName': 'string',
                            'toolDescription': {
                                'text': 'string'
                            }
                        },
                    ]
                },
                'configurationBundle': {
                    'bundleArn': 'string',
                    'versionId': 'string',
                    'tools': [
                        {
                            'toolName': 'string',
                            'toolDescriptionJsonPath': 'string'
                        },
                    ]
                }
            },
            'agentTraces': {
                'sessionSpans': [
                    {...}|[...]|123|123.4|'string'|True|None,
                ],
                'cloudwatchLogs': {
                    'logGroupArns': [
                        'string',
                    ],
                    'serviceNames': [
                        'string',
                    ],
                    'startTime': datetime(2015, 1, 1),
                    'endTime': datetime(2015, 1, 1),
                    'rule': {
                        'filters': [
                            {
                                'key': 'string',
                                'operator': 'Equals'|'NotEquals'|'GreaterThan'|'LessThan'|'GreaterThanOrEqual'|'LessThanOrEqual'|'Contains'|'NotContains',
                                'value': {
                                    'stringValue': 'string',
                                    'doubleValue': 123.0,
                                    'booleanValue': True|False
                                }
                            },
                        ]
                    }
                }
            }
        }
    },
    'status': 'PENDING'|'IN_PROGRESS'|'COMPLETED'|'FAILED'|'DELETING',
    'createdAt': datetime(2015, 1, 1),
    'updatedAt': datetime(2015, 1, 1)
}

Response Structure

(dict) –
- recommendationId (string) –
  
  The unique identifier of the created recommendation.
- recommendationArn (string) –
  
  The Amazon Resource Name (ARN) of the created recommendation.
- name (string) –
  
  The name of the recommendation.
- description (string) –
  
  The description of the recommendation.
- type (string) –
  
  The type of recommendation.
- recommendationConfig (dict) –
  
  The configuration for the recommendation.
  Note
  This is a Tagged Union structure. Only one of the following top level keys will be set: systemPromptRecommendationConfig, toolDescriptionRecommendationConfig. If a client receives an unknown member it will set SDK_UNKNOWN_MEMBER as the top level key, which maps to the name or tag of the unknown member. The structure of SDK_UNKNOWN_MEMBER is as follows:
  'SDK_UNKNOWN_MEMBER': {'name': 'UnknownMemberName'}
  - systemPromptRecommendationConfig (dict) –
    
    The configuration for a system prompt recommendation.
    - systemPrompt (dict) –
      
      The current system prompt to optimize.
      Note
      This is a Tagged Union structure. Only one of the following top level keys will be set: text, configurationBundle. If a client receives an unknown member it will set SDK_UNKNOWN_MEMBER as the top level key, which maps to the name or tag of the unknown member. The structure of SDK_UNKNOWN_MEMBER is as follows:
      
      'SDK_UNKNOWN_MEMBER': {'name': 'UnknownMemberName'}
      - text (string) –
        
        The system prompt text provided inline.
      - configurationBundle (dict) –
        
        The system prompt sourced from a configuration bundle version.
        
        bundleArn (string) –
        
        The Amazon Resource Name (ARN) of the configuration bundle.
        
        versionId (string) –
        
        The version identifier of the configuration bundle.
        
        systemPromptJsonPath (string) –
        
        The JSON path within the configuration bundle that contains the system prompt.
    - agentTraces (dict) –
      
      The agent traces to analyze for generating recommendations.
      Note
      This is a Tagged Union structure. Only one of the following top level keys will be set: sessionSpans, cloudwatchLogs. If a client receives an unknown member it will set SDK_UNKNOWN_MEMBER as the top level key, which maps to the name or tag of the unknown member. The structure of SDK_UNKNOWN_MEMBER is as follows:
      
      'SDK_UNKNOWN_MEMBER': {'name': 'UnknownMemberName'}
      - sessionSpans (list) –
        
        Agent traces provided as inline session spans in OpenTelemetry format.
        
        (document) –
      - cloudwatchLogs (dict) –
        
        Agent traces read from CloudWatch Logs.
        
        logGroupArns (list) –
        
        The list of CloudWatch log group ARNs to read agent traces from.
        
        (string) –
        
        serviceNames (list) –
        
        The list of service names to filter traces within the specified log groups.
        
        (string) –
        
        startTime (datetime) –
        
        The start time of the time range to read traces from.
        
        endTime (datetime) –
        
        The end time of the time range to read traces from.
        
        rule (dict) –
        
        Optional rule configuration for filtering traces.
        
        filters (list) –
        
        The list of filters to apply when reading agent traces.
        
        (dict) –
        
        A filter for narrowing down agent traces from CloudWatch Logs based on key-value comparisons.
        
        key (string) –
        
        The key or field name to filter on within the agent trace data.
        
        operator (string) –
        
        The comparison operator to use for filtering.
        
        value (dict) –
        
        The value to compare against using the specified operator.
        
        Note
        This is a Tagged Union structure. Only one of the following top level keys will be set: stringValue, doubleValue, booleanValue. If a client receives an unknown member it will set SDK_UNKNOWN_MEMBER as the top level key, which maps to the name or tag of the unknown member. The structure of SDK_UNKNOWN_MEMBER is as follows:
        
        'SDK_UNKNOWN_MEMBER': {'name': 'UnknownMemberName'}
        
        stringValue (string) –
        
        A string value for text-based filtering.
        
        doubleValue (float) –
        
        A numeric value for numerical filtering and comparisons.
        
        booleanValue (boolean) –
        
        A boolean value for true/false filtering conditions.
    - evaluationConfig (dict) –
      
      The evaluation configuration specifying which evaluator to use for assessing recommendation quality.
      - evaluators (list) –
        
        The list of evaluators to use for assessing recommendation quality.
        
        (dict) –
        
        A reference to an evaluator used for recommendation assessment.
        
        evaluatorArn (string) –
        
        The Amazon Resource Name (ARN) of the evaluator.
  - toolDescriptionRecommendationConfig (dict) –
    
    The configuration for a tool description recommendation.
    - toolDescription (dict) –
      
      The current tool descriptions to optimize.
      Note
      This is a Tagged Union structure. Only one of the following top level keys will be set: toolDescriptionText, configurationBundle. If a client receives an unknown member it will set SDK_UNKNOWN_MEMBER as the top level key, which maps to the name or tag of the unknown member. The structure of SDK_UNKNOWN_MEMBER is as follows:
      
      'SDK_UNKNOWN_MEMBER': {'name': 'UnknownMemberName'}
      - toolDescriptionText (dict) –
        
        Tool descriptions provided as inline text.
        
        tools (list) –
        
        The list of tool descriptions to optimize.
        
        (dict) –
        
        A tool description input containing the tool name and its current description.
        
        toolName (string) –
        
        The name of the tool.
        
        toolDescription (dict) –
        
        The current description of the tool to optimize.
        
        Note
        This is a Tagged Union structure. Only one of the following top level keys will be set: text. If a client receives an unknown member it will set SDK_UNKNOWN_MEMBER as the top level key, which maps to the name or tag of the unknown member. The structure of SDK_UNKNOWN_MEMBER is as follows:
        
        'SDK_UNKNOWN_MEMBER': {'name': 'UnknownMemberName'}
        
        text (string) –
        
        The tool description as inline text.
      - configurationBundle (dict) –
        
        Tool descriptions sourced from a configuration bundle version.
        
        bundleArn (string) –
        
        The Amazon Resource Name (ARN) of the configuration bundle.
        
        versionId (string) –
        
        The version identifier of the configuration bundle.
        
        tools (list) –
        
        The list of tool entries mapping tool names to their JSON paths within the bundle.
        
        (dict) –
        
        Maps a tool name to its JSON path within a configuration bundle.
        
        toolName (string) –
        
        The name of the tool.
        
        toolDescriptionJsonPath (string) –
        
        The JSON path within the configuration bundle’s components that contains the tool description.
    - agentTraces (dict) –
      
      The agent traces to analyze for generating tool description recommendations.
      Note
      This is a Tagged Union structure. Only one of the following top level keys will be set: sessionSpans, cloudwatchLogs. If a client receives an unknown member it will set SDK_UNKNOWN_MEMBER as the top level key, which maps to the name or tag of the unknown member. The structure of SDK_UNKNOWN_MEMBER is as follows:
      
      'SDK_UNKNOWN_MEMBER': {'name': 'UnknownMemberName'}
      - sessionSpans (list) –
        
        Agent traces provided as inline session spans in OpenTelemetry format.
        
        (document) –
      - cloudwatchLogs (dict) –
        
        Agent traces read from CloudWatch Logs.
        
        logGroupArns (list) –
        
        The list of CloudWatch log group ARNs to read agent traces from.
        
        (string) –
        
        serviceNames (list) –
        
        The list of service names to filter traces within the specified log groups.
        
        (string) –
        
        startTime (datetime) –
        
        The start time of the time range to read traces from.
        
        endTime (datetime) –
        
        The end time of the time range to read traces from.
        
        rule (dict) –
        
        Optional rule configuration for filtering traces.
        
        filters (list) –
        
        The list of filters to apply when reading agent traces.
        
        (dict) –
        
        A filter for narrowing down agent traces from CloudWatch Logs based on key-value comparisons.
        
        key (string) –
        
        The key or field name to filter on within the agent trace data.
        
        operator (string) –
        
        The comparison operator to use for filtering.
        
        value (dict) –
        
        The value to compare against using the specified operator.
        
        Note
        This is a Tagged Union structure. Only one of the following top level keys will be set: stringValue, doubleValue, booleanValue. If a client receives an unknown member it will set SDK_UNKNOWN_MEMBER as the top level key, which maps to the name or tag of the unknown member. The structure of SDK_UNKNOWN_MEMBER is as follows:
        
        'SDK_UNKNOWN_MEMBER': {'name': 'UnknownMemberName'}
        
        stringValue (string) –
        
        A string value for text-based filtering.
        
        doubleValue (float) –
        
        A numeric value for numerical filtering and comparisons.
        
        booleanValue (boolean) –
        
        A boolean value for true/false filtering conditions.
- status (string) –
  
  The status of the recommendation.
- createdAt (datetime) –
  
  The timestamp when the recommendation was created.
- updatedAt (datetime) –
  
  The timestamp when the recommendation was last updated.

Exceptions

BedrockAgentCore.Client.exceptions.ServiceQuotaExceededException
BedrockAgentCore.Client.exceptions.AccessDeniedException
BedrockAgentCore.Client.exceptions.ConflictException
BedrockAgentCore.Client.exceptions.ValidationException
BedrockAgentCore.Client.exceptions.ThrottlingException
BedrockAgentCore.Client.exceptions.InternalServerException