feat(bedrock_agent): add new Amazon Bedrock Agents Functions Resolver #6564

anafalcao · 2025-04-25T15:40:03Z

Issue number: #6300

Summary

This PR introduces support for Bedrock Agents Functions, providing the user a similar experience from the current Bedrock Agents with OpenAPI Resolver.

Changes

Bedrock Agent Functions data class
BedrockFunctionsResponseBuilder
BedrockAgentFunctionResolver
Optional response fields - sessionAttributes, promptSessionAttributes, knowledgeBasesConfiguration
Parser
Additional validations
name on Tool decorator
Documentation with examples

User experience

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)

Checklist

If your change doesn't seem to apply, please leave them unchecked.

Meet tenets criteria
I have performed a self-review of this change
Changes have been tested
Changes are documented
PR title follows conventional commit semantics

Is this a breaking change?

RFC issue number:

Checklist:

Migration process documented
Implement warnings (if it can live side by side)

Acknowledgment

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

Disclaimer: We value your time and bandwidth. As such, any pull requests created on non-triaged issues might not be successful.

codecov · 2025-04-25T15:47:10Z

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 96.15%. Comparing base (d89f1f9) to head (9914ab5).
Report is 8 commits behind head on develop.

Additional details and impacted files

@@             Coverage Diff             @@
##           develop    #6564      +/-   ##
===========================================
+ Coverage    96.09%   96.15%   +0.05%     
===========================================
  Files          254      256       +2     
  Lines        12179    12350     +171     
  Branches       905      916      +11     
===========================================
+ Hits         11704    11875     +171     
  Misses         373      373              
  Partials       102      102

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

aws_lambda_powertools/event_handler/bedrock_agent_function.py

Signed-off-by: Ana Falcão <[email protected]>

…tools/powertools-lambda-python into feat/bedrock_functions

github-actions · 2025-05-26T21:50:45Z

⚠️Large PR detected⚠️

Please consider breaking into smaller PRs to avoid significant review delays. Ignore if this PR has naturally grown to this size after reviews.

github-actions · 2025-05-26T21:54:36Z

⚠️Large PR detected⚠️

Please consider breaking into smaller PRs to avoid significant review delays. Ignore if this PR has naturally grown to this size after reviews.

github-actions · 2025-05-26T21:58:22Z

⚠️Large PR detected⚠️

Please consider breaking into smaller PRs to avoid significant review delays. Ignore if this PR has naturally grown to this size after reviews.

dreamorosi

Left a few comments/questions

dreamorosi · 2025-05-27T06:43:46Z

aws_lambda_powertools/event_handler/bedrock_agent_function.py

+            error_response = BedrockFunctionResponse(body=f"Error: {str(error)}", response_state="FAILURE")
+            return BedrockFunctionsResponseBuilder(error_response).build(self.current_event)
+
+    def append_context(self, **additional_context):


Are we ever calling this method to append the context?

This is a function to allow customer to inject additional data - like dependency injection - to access this within the route (tool in this case).

Ok, but are we ever passing the context to the tool handler?

dreamorosi · 2025-05-27T06:47:45Z

aws_lambda_powertools/event_handler/bedrock_agent_function.py

+            func = self._tools[function_name]["function"]
+            # Filter parameters to only include those expected by the function
+            sig = inspect.signature(func)
+            valid_params = {name: value for name, value in parameters.items() if name in sig.parameters}


We can't parse array types, but we can "trust" number, integer, boolean and string types and potentially cast them to the correct type before passing them to the handler.

Otherwise customers will always get strings.

Hmm make sense, I see your point. Ok, I'll cast them before passing to the function.

dreamorosi · 2025-05-27T06:49:02Z

docs/core/event_handler/bedrock_agents.md

@@ -26,72 +30,53 @@ Create [Agents for Amazon Bedrock](https://docs.aws.amazon.com/bedrock/latest/us

 **[OpenAPI schema](https://www.openapis.org/){target="_blank"}** is an industry standard JSON-serialized string that represents the structure and parameters of your API.

+**Function details** consist of a list of parameters, defined by their name, [data type](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_ParameterDetail.html), and whether they are required. The agent uses these configurations to determine what information it needs to elicit from the user.
+
 **Action group** is a collection of two resources where you define the actions that the agent should carry out: an OpenAPI schema to define the APIs that the agent can invoke to carry out its tasks, and a Lambda function to execute those actions.


This could be confusing, with the new feature an action group is only a function and its tool definitions, without OpenAPI schema

docs/core/event_handler/bedrock_agents.md

dreamorosi · 2025-05-27T06:51:25Z

docs/core/event_handler/bedrock_agents.md

+|----------------------|------------------------------------------------------------------|----------------------------------------------------------------|
+| Definition Style      | `@app.get("/path", description="")`<br>`@app.post("/path", description="")` | `@app.tool(name="")`                                            |
+| Parameter Handling    | Path, query, and body parameters                                 | Function parameters                                             |
+| Use Case              | REST-like APIs, complex request/response structures              | Direct function calls, simpler input/output                     |


I think simpler input is probably the most correct.

Based on tests Bedrock is able to work with complex outputs just fine even with the function-based resolver, there's just not a schema but it does fine.

dreamorosi · 2025-05-27T06:52:29Z

docs/core/event_handler/bedrock_agents.md

+| Parameter Handling    | Path, query, and body parameters                                 | Function parameters                                             |
+| Use Case              | REST-like APIs, complex request/response structures              | Direct function calls, simpler input/output                     |
+| Response object       | Via `BedrockResponse`                                            | Via `BedrockFunctionResponse`                                   |
+| Best For              | - Complex APIs with multiple endpoints<br>- When OpenAPI spec is required<br>- Integration with existing REST APIs | - Simple function-based actions<br>- Direct LLM-to-function mapping<br>- When function descriptions are sufficient |


I'd remove this When function descriptions are sufficient.

In practice, you still need to configure Bedrock and specify the tools, parameters, and description - it just happens in the Agent config rather than in the function's code.

dreamorosi · 2025-05-27T07:08:50Z

docs/core/event_handler/bedrock_agents.md

 	```

-#### When validation fails
+??? note "What happens under the hood?"


Based on the content of the mermaid diagram, this should probably be under the OpenAPI section since it mentions both the OpenAPI schema and validation, which don't happen in this new implementation.

docs/core/event_handler/bedrock_agents.md

github-actions · 2025-05-27T10:17:07Z

⚠️Large PR detected⚠️

Please consider breaking into smaller PRs to avoid significant review delays. Ignore if this PR has naturally grown to this size after reviews.

github-actions · 2025-05-28T17:07:07Z

⚠️Large PR detected⚠️

Please consider breaking into smaller PRs to avoid significant review delays. Ignore if this PR has naturally grown to this size after reviews.

github-actions · 2025-05-28T17:08:02Z

⚠️Large PR detected⚠️

Please consider breaking into smaller PRs to avoid significant review delays. Ignore if this PR has naturally grown to this size after reviews.

github-actions · 2025-05-28T17:37:19Z

⚠️Large PR detected⚠️

Please consider breaking into smaller PRs to avoid significant review delays. Ignore if this PR has naturally grown to this size after reviews.

sonarqubecloud · 2025-05-28T17:38:08Z

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
No data about Coverage
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

feat(bedrock_agent): create bedrock agents functions data class

41bc401

boring-cyborg bot added the tests label Apr 25, 2025

pull-request-size bot added the size/L Denotes a PR that changes 100-499 lines, ignoring generated files. label Apr 25, 2025

github-actions bot added the feature New feature or functionality label Apr 25, 2025

anafalcao self-assigned this Apr 25, 2025

anafalcao linked an issue Apr 25, 2025 that may be closed by this pull request

Feature request: Amazon Bedrock Agents Functions #6300

Open

2 tasks

anafalcao added 3 commits April 25, 2025 16:21

create resolver

bed8f3f

mypy

a3765f0

add response

44d80f8

boring-cyborg bot added the event_handlers label Apr 25, 2025

pull-request-size bot added size/XL Denotes a PR that changes 500-999 lines, ignoring generated files. and removed size/L Denotes a PR that changes 100-499 lines, ignoring generated files. labels Apr 25, 2025

anafalcao changed the title ~~feat(bedrock_agent): create bedrock agents functions data class~~ feat(bedrock_agent): Add new Amazon Bedrock Agents Functions Apr 25, 2025

anafalcao changed the title ~~feat(bedrock_agent): Add new Amazon Bedrock Agents Functions~~ feat(bedrock_agent): WIP - Add new Amazon Bedrock Agents Functions Apr 25, 2025

anafalcao added 2 commits April 28, 2025 16:35

add name param to tool

abbc100

add response optional fields

e42ceff

leandrodamascena reviewed Apr 29, 2025

View reviewed changes

aws_lambda_powertools/event_handler/bedrock_agent_function.py Outdated Show resolved Hide resolved

bedrockfunctionresponse and response state

86c7ab7

pull-request-size bot added size/L Denotes a PR that changes 100-499 lines, ignoring generated files. and removed size/XL Denotes a PR that changes 500-999 lines, ignoring generated files. labels May 1, 2025

anafalcao added 2 commits May 1, 2025 15:54

remove body message

34948d7

add parser

24978cb

pull-request-size bot added size/XL Denotes a PR that changes 500-999 lines, ignoring generated files. and removed size/L Denotes a PR that changes 100-499 lines, ignoring generated files. labels May 2, 2025

anafalcao and others added 5 commits May 5, 2025 18:14

add test for required fields

45f85f6

Merge branch 'develop' into feat/bedrock_functions

b420a90

Signed-off-by: Ana Falcão <[email protected]>

add more tests for parser and resolver

84bb6b0

Merge branch 'feat/bedrock_functions' of https://github.com/aws-power…

20bbe9f

…tools/powertools-lambda-python into feat/bedrock_functions

add validation response state

d463304

boring-cyborg bot added the documentation Improvements or additions to documentation label May 26, 2025

github-actions bot removed the documentation Improvements or additions to documentation label May 26, 2025

Small refactor + documentation

c200a3a

boring-cyborg bot added the documentation Improvements or additions to documentation label May 26, 2025

github-actions bot removed the documentation Improvements or additions to documentation label May 26, 2025

Small refactor + documentation

ca700c8

boring-cyborg bot added the documentation Improvements or additions to documentation label May 26, 2025

github-actions bot removed the documentation Improvements or additions to documentation label May 26, 2025

dreamorosi reviewed May 27, 2025

View reviewed changes

Aligning Python implementation with TS

c992463

boring-cyborg bot added the documentation Improvements or additions to documentation label May 27, 2025

github-actions bot removed the documentation Improvements or additions to documentation label May 27, 2025

Adding custom serializer

214d061

boring-cyborg bot added the documentation Improvements or additions to documentation label May 28, 2025

github-actions bot removed the documentation Improvements or additions to documentation label May 28, 2025

boring-cyborg bot added the documentation Improvements or additions to documentation label May 28, 2025

github-actions bot removed the documentation Improvements or additions to documentation label May 28, 2025

Adding custom serializer

9914ab5

boring-cyborg bot added the documentation Improvements or additions to documentation label May 28, 2025

github-actions bot removed the documentation Improvements or additions to documentation label May 28, 2025

dreamorosi mentioned this pull request May 28, 2025

docs(event-handler): add docs page for Bedrock Agent Function aws-powertools/powertools-lambda-typescript#3991

Open

dreamorosi approved these changes May 28, 2025

View reviewed changes

feat(bedrock_agent): add new Amazon Bedrock Agents Functions Resolver #6564

Are you sure you want to change the base?

feat(bedrock_agent): add new Amazon Bedrock Agents Functions Resolver #6564

Conversation

anafalcao commented Apr 25, 2025 • edited by leandrodamascena Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

User experience

Checklist

Acknowledgment

Uh oh!

codecov bot commented Apr 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Uh oh!

github-actions bot commented May 26, 2025

⚠️Large PR detected⚠️

Uh oh!

github-actions bot commented May 26, 2025

⚠️Large PR detected⚠️

Uh oh!

github-actions bot commented May 26, 2025

⚠️Large PR detected⚠️

Uh oh!

dreamorosi left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

github-actions bot commented May 27, 2025

⚠️Large PR detected⚠️

Uh oh!

github-actions bot commented May 28, 2025

⚠️Large PR detected⚠️

Uh oh!

github-actions bot commented May 28, 2025

⚠️Large PR detected⚠️

Uh oh!

github-actions bot commented May 28, 2025

⚠️Large PR detected⚠️

Uh oh!

sonarqubecloud bot commented May 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Quality Gate passed

Uh oh!

Uh oh!

anafalcao commented Apr 25, 2025 •

edited by leandrodamascena

Loading

codecov bot commented Apr 25, 2025 •

edited

Loading

sonarqubecloud bot commented May 28, 2025 •

edited

Loading