RFC: Amazon Bedrock agents with action groups using Function details

[anafalcao]

Summary

---

The Powertools for AWS Lambda (Python) currently provides an event handler for Bedrock Agents, allowing users to build AI-driven applications with OpenAPI schemas. However, since adding support for it Bedrock has added support for function calling rather than structured API definitions.

This proposal introduces BedrockAgentFunctionsResolver, a new Event Handler resolver designed to seamlessly build Bedrock Agents functions within AWS Lambda. This new resolver simplifies function-based interactions, allowing users to build modular AI assistants and task automation systems with optimized effort.

Use Case

---

Developers often need to build AI-powered applications that can dynamically invoke functions based on user input or AI model reasoning. Examples include:

• Chatbots & Assistants: AI agents that can call functions like get_weather, book_appointment, or fetch_order_status.
• Automation Workflows: Function orchestration for tasks like process_payment, generate_report, or send_email.
• Data Processing Pipelines: Dynamic execution of transformation functions based on real-time data needs.

How it is today

---

Lambda handler

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

Action group - function details

agent_functions = [
    {
        'name': 'get_current_time',
        'description': 'Retrieve the current UTC time.',
        'parameters': {}
    },
    {
        'name': 'greet_user',
        'description': 'Greet the user by name.',
        'parameters': {
            "name": {
                "description": "The name of the user to greet.",
                "required": True,
                "type": "string"
            }
        }
    },
    {
        'name': 'simple_calculator',
        'description': 'Perform basic math operations (add, subtract, multiply, divide).',
        'parameters': {
            "a": {
                "description": "The first number.",
                "required": True,
                "type": "number"
            },
            "b": {
                "description": "The second number.",
                "required": True,
                "type": "number"
            },
            "operation": {
                "description": "The operation to perform: add, subtract, multiply, divide.",
                "required": True,
                "type": "string"
            }
        }
    }
]

Lambda payload

---

Example Input

{
    "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"
    }]
}

Example output

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

Proposal

---

BedrockAgentFunctionsResolver
This utility will provide a structured way to register functions, resolve function calls, and handle execution within AWS Lambda. Keeps a similar experience as using BedrockAgentResolver .

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

app = BedrockAgentFunctionResolver()

@app.function(description="Gets the current UTC time")
def get_current_time():
    ... 

@app.function(description="Greets the user using name")
def greet_user(name):

@app.function(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 OpenAPI implementation, Functions can return the Action Groups:

__name__ == "__main__": 
  print(app.get_agent_functions_schema())

Proposed Implementation Details

Function Registration

1. A decorator (@app.function) to register functions' descriptions.
2. Automatic extraction of input parameters and types.
3. Support for injecting parameters in the function signature.

Invocation Handling

1. The resolve(event, context) method will process incoming requests and invoke the corresponding function.
2. Support for structured error handling if the function is missing or has incorrect parameters.

Error Handling & Logging

1. Standardized error responses for unregistered functions or invalid arguments.

Alternatives Considered

• Using OpenAPI-based Agents: While OpenAPI provides strong schema validation, it adds complexity for simple function calls.
• Manually Mapping Functions: Developers can manually map function names to handlers, but this approach is error-prone and lacks automation

[dreamorosi]

Hi @anafalcao - thank you so much for posting this!

I'm going to take some time on Monday to go through it more in details and leave a comment, but from a first read it's looking already good!

[dreamorosi]

Finally got around to reading and form some thoughts.

The first one is, how do customers access the event and context in a function handler? If we follow the REST-based event handler we would do app.current_event and app.current_context.

That would be good for consistency, but in hindsight I think it's a design flaw. Customers have called this out during the RFC for Event Handler in TypeScript and I agree with that sentiment.

Having both event and context passed directly to the function handler makes the implementation future proof in my opinion.

The second point is related to validation. Since LLMs are non-deterministic by design, I think customers should be able to set Pydantic schemas for inputs (& possibly outputs) in their function resolvers. Having those, would also help us generate the right schema for the action group, if I understand correctly the feature.

What do you think?

[leandrodamascena]

Hello @anafalcao! Thank you so much for working on your first public RFC, this is an incredible achievement! 🚀. I have a few questions and I'll break them down to make it easier to follow and answer.

Resolver decorator

Let's take this code as example:

@app.function(description="Greets the user using name")
def greet_user(name):
  ...

If I understand correctly, this @app.function decorator will try to find in the payload the key function with value greet_user and will inject the parameter name of the parameters key, right? If this is correctly, I don't think we should go in this way because some reasons:

1 - The experience is not deterministic, I mean, someone looks at this code and tries to understand what it is doing. After reading the documentation and maybe the implementation, they will find that we are mapping the value of the function key from the payload to the function defined in your code.
2 - We are diverging from the general experience in our Event Handler, where you need to make it deterministic by explicitly naming the route.
3 - We are forcing customers to have names that map exactly to Bedrock Agents, which may break some Python naming conventions and start throwing errors in type checking tools.
4 - If BedrockAgents allows you to define the function with special characters, like -, it will break the whole mechanism because Python (and other languages) does not allow those characters when defining the function name.
5 - function might be a reserved word in some language and I don't know if we should use this.
6 - This will make tests hards because customers will not be able to mock this decorator with different routes.

Why don't we keep the same experience as other resolvers? I think make sense we discuss a little bit more if @app.route or @app.agent or any other name, but I'd like to preserve the same experience.

Functions can return the Action Groups

Can you elaborate a little bit more on what you expect from this experience? Are we proposing to reverse engineer and create the payload?

__name__ == "__main__": 
  print(app.get_agent_functions_schema())

Again, thank you so much for working on this. It will be a great feature for our customers.

[phipag]

Thank you @anafalcao for writing up this RFC! I would like to give my opinion on a few points as well.

Regarding @leandrodamascena's points:

• (1) I agree, we should not derive the function name from the actual name of the Python function since they are easily changed in the code by the developer and it is easy to forget that it is mapped to the Bedrock action group function names. Similar to @dreamorosi, I also think this should be optional. It would be consistent, for example, with Pydantic's serialization_alias kwarg which is also optional.
• (5) In Java, for instance, "Function" is not a reserved keyword but a commonly used object (https://docs.oracle.com/javase/8/docs/api/java/util/function/Function.html).
  • If we translate this annotation similar to logger = Logger() from Python to Java we would end up annotating Bedrock action group functions with @Function which would force developers to re-import either our @Function annotation under a different name or the Java Function class under a different name. I am wondering if others have an opinion on this? Of course, we could name the annotation in Java @BedrockFunction or something similar.

[anafalcao]

Hey! Thank you all for the time invested here.
I really like the ideia of making the name parameter as Optional, @dreamorosi !
Also, @leandrodamascena I agree in letting the app.get_agent_functions_schema() for v1, and start v0 without it.

So we still need to decide if we keep app.function or another name here. I agree that it may cause problems as a reserved word, and @phipag gave us another example of where this might be an issue.
So, I a few options would be app.agent as Leo suggested, app.action or app.agent_function.
I personally like app.agent_function.

[dreamorosi]

I've been writing the spec for the TypeScript implementation and I had a thought: we could call these tools which is a widely accepted term in the GenAI ecosystem. This way the annotation/decotator/method would become @app.tool or @tool/@Tool based on the implementation.

This will bypass any issue related to reserved keywords or other kinds of ambiguity.

[anafalcao]

I like this idea @dreamorosi !
I believe we went through all the details, and now have a path forward.
Thank you all for the amazing suggestions and feedbacks!