Feature request: Amazon Bedrock Agents Functions

[anafalcao]

Use case

RFC: #6081
Issue in TS: aws-powertools/powertools-lambda-typescript/issues/3710

Bedrock Agents allows you to define action groups for your agents in two ways: OpenAPI schemas, and direct function integration. This issue focuses on the latter.

As a customer I can create Bedrock Agents that have tools at their disposal. These tools, or functions, can be defined as AWS Lambda functions. One Lambda function can hold one or more tools and when looked at together, they are what makes an action group.

When I build a Lambda function with multiple tools in it, I am responsible for parsing the payload sent by Bedrock and, based on certain fields, call the corresponding tool in my code (aka the tool use). The response of this tool use is then returned by my Lambda function handler according to a specific format that Bedrock expects.

This can result in some degree of boilerplate code that I have to repeat for each action group, specifically:

• parsing/validating the incoming Bedrock Agent request payload
• handling the event using the correct tool/function
• building the response according to the response Bedrock Agent payload schema

Example

def get_current_time():
    ...

def greet_user(name):
    ...

def simple_calculator(a, b, operation):
    ...

def lambda_handler(event, context):
    agent = event['agent']
    actionGroup = event['actionGroup']
    function = event['function']
    parameters = event.get('parameters', [])

    # Execute the appropriate function based on the 'function' parameter
    if function == 'get_current_time':
        result = get_current_time()
    elif function == 'greet_user':
        name = parameters[0]['value'] if parameters else "User"
        result = greet_user(name)
    elif function == 'simple_calculator':
        if len(parameters) >= 3:
            a = float(parameters[0]['value'])
            b = float(parameters[1]['value'])
            operation = parameters[2]['value']
            result = simple_calculator(a, b, operation)
        else:
            result = "Error: Insufficient parameters for simple_calculator"
    else:
        result = f"Unknown function: {function}"

    responseBody = {
        "TEXT": {
            "body": str(result)
        }
    }

    action_response = {
        'actionGroup': actionGroup,
        'function': function,
        'functionResponse': {
            'responseBody': responseBody
        }
    }

    function_response = {'response': action_response, 'messageVersion': event['messageVersion']}
    print("Response: {}".format(function_response))

    return function_response

As a customer I would like to abstract all of that and instead focus primarily on building the tools for my agents, which are the only part of this that is specific to my business.

Solution/User Experience

When paired with a Lambda function via action group, Bedrock sends and expects payloads of known shapes.

Payload example

{
    "messageVersion": "1.0",
    "agent": {
        "alias": "PROD",
        "name": "hr-assistant-function-def",
        "version": "1",
        "id": "1234abcd-56ef-78gh-90ij-klmn12345678"
    },
    "sessionId": "87654321-abcd-efgh-ijkl-mnop12345678",
    "sessionAttributes": {
        "employeeId": "EMP123",
        "department": "Engineering"
    },
    "promptSessionAttributes": {
        "lastInteraction": "2024-02-01T15:30:00Z",
        "requestType": "vacation"
    },
    "inputText": "I want to request vacation from March 15 to March 20",
    "actionGroup": "VacationsActionGroup",
    "function": "submitVacationRequest",
    "parameters": [{
        "employeeId": "EMP123",
        "startDate": "2024-03-15",
        "endDate": "2024-03-20",
        "vacationType": "annual"
    }]
}

Documentation

Response payload example

{
   "response":{
      "actionGroup":"SmarterAgentActionGroup",
      "function":"submitVacationRequest",
      "functionResponse":{
         "responseBody":{
            "TEXT":{
               "body":"Your vacation was scheduled!"
            }
         }
      }
   },
   "messageVersion":"1.0"
}

Documentation

Since the input event includes both the function and parameters fields, we can abstract most/all the boilerplate and provide a more streamlined experience.

We could implement a BedrockAgentFunctionResolver resolver that provides a structured way to register functions, resolve function calls, and handle requests within Lambda.

from aws_lambda_powertools.event_handler import BedrockAgentFunctionResolver
from aws_lambda_powertools.utilities.typing import LambdaContext

app = BedrockAgentFunctionResolver()

@app.tool(name="currentTime", description="Gets the current UTC time")
def get_current_time():
    ... 
@app.tool(description="Greets the user using name")
def greet_user(name):
...
@app.tool(description="Add two numbers")
def simple_calculator(a, b, operation):
...
def lambda_handler(event: dict, context: LambdaContext) → dict:
    return app.resolve(event, context)

Similar to the experience for Bedrock Agents with OpenAPI, we need a decorator tool that have name parameter as Optional. If customers want to make this more resilient to refactoring or want to have special naming conventions they can optionally specify a name parameter and in that case that takes precedence over the actual function name.

The implementation above allows customers to focus on defining and implementing the tools within the action group rather than the undifferentiated boilerplate required to parse an event, resolve which tool to use, call it, and build the response payload.

Finally, customers can also access the current request event in the tool definitions, as app.current_event, ang get information like session_id or prompt_session_attributes similar to Bedrock Agents OpenAPI - accessing custom request fields

Alternative solutions

See this discussion for considerations on alternative solutions: #6081

Acknowledgment

• This feature request meets Powertools for AWS Lambda (Python) Tenets
• Should this be considered in other Powertools for AWS Lambda languages? i.e. Java, TypeScript, and .NET