doc event handler, parser and data class

anafalcao · anafalcao · commit fdde207fa9ce · 2025-05-15T15:27:27.000-03:00
diff --git a/docs/core/event_handler/bedrock_agents.md b/docs/core/event_handler/bedrock_agents.md
diff --git a/docs/core/event_handler/bedrock_agents.mermaid b/docs/core/event_handler/bedrock_agents.mermaid
@@ -2,12 +2,17 @@ flowchart LR
     Bedrock[LLM] <-- uses --> Agent
     You[User input] --> Agent
     Agent -- consults --> OpenAPI
-    Agent[Agents for Amazon Bedrock] -- invokes --> Lambda
+    Agent -- consults --> Functions
+    Agent[Amazon Bedrock Agents] -- invokes --> Lambda
 
     subgraph OpenAPI
         Schema
     end
 
+    subgraph Functions
+        ToolDescriptions[Tool Descriptions]
+    end
+
     subgraph Lambda[Lambda Function]
         direction TB
         Parsing[Parameter Parsing] --> Validation
@@ -19,10 +24,8 @@ flowchart LR
 
     subgraph ActionGroup[Action Group]
         OpenAPI -. generated from .-> Lambda
+        Functions -. defined in .-> Lambda
     end
 
     style Code fill:#ffa500,color:black,font-weight:bold,stroke-width:3px
-    style You stroke:#0F0,stroke-width:2px
-
-
-
+    style You stroke:#0F0,stroke-width:2px
diff --git a/docs/core/event_handler/bedrock_agents_getting_started.mermaid b/docs/core/event_handler/bedrock_agents_getting_started.mermaid
@@ -14,7 +14,10 @@ sequenceDiagram
         participant Your Code
     end
 
-    Agent->>Lambda: GET /current_time
+    alt Function-based
+        Agent->>Lambda: {function: "current_time", parameters: [], ...}
+    end
+
     activate Lambda
     Lambda->>Parsing: parses parameters
     Parsing->>Validation: validates input
@@ -26,8 +29,11 @@ sequenceDiagram
     Routing->>Validation: returns output
     Validation->>Parsing: validates output
     Parsing->>Lambda: formats response
-    Lambda->>Agent: 1709215709
+
+    alt Function-based
+        Lambda->>Agent: {response: {functionResponse: {responseBody: {...}}}}
+    end
     deactivate Lambda
 
     Agent-->>Agent: LLM interaction
-    Agent->>User: "The current time is 14:08:29 GMT"
+    Agent->>User: "The current time is 14:08:29 GMT"
diff --git a/docs/utilities/data_classes.md b/docs/utilities/data_classes.md
@@ -75,7 +75,8 @@ Each event source is linked to its corresponding GitHub file with the full set o
 | [AppSync Authorizer](#appsync-authorizer) | `AppSyncAuthorizerEvent` | [Github](https://github.com/aws-powertools/powertools-lambda-python/blob/develop/aws_lambda_powertools/utilities/data_classes/appsync_authorizer_event.py) |
 | [AppSync Resolver](#appsync-resolver) | `AppSyncResolverEvent` | [Github](https://github.com/aws-powertools/powertools-lambda-python/blob/develop/aws_lambda_powertools/utilities/data_classes/appsync_resolver_event.py) |
 | [AWS Config Rule](#aws-config-rule) | `AWSConfigRuleEvent` | [Github](https://github.com/aws-powertools/powertools-lambda-python/blob/develop/aws_lambda_powertools/utilities/data_classes/aws_config_rule_event.py) |
-| [Bedrock Agent](#bedrock-agent) | `BedrockAgent` | [Github](https://github.com/aws-powertools/powertools-lambda-python/blob/develop/aws_lambda_powertools/utilities/data_classes/bedrock_agent_event.py) |
+| [Bedrock Agent - OpenAPI](#bedrock-agent) | `BedrockAgentEvent` | [Github](https://github.com/aws-powertools/powertools-lambda-python/blob/develop/aws_lambda_powertools/utilities/data_classes/bedrock_agent_event.py) |
+| [Bedrock Agent - Function](#bedrock-agent) | `BedrockAgentFunctionEvent` | [Github](https://github.com/aws-powertools/powertools-lambda-python/blob/develop/aws_lambda_powertools/utilities/data_classes/bedrock_agent_function_event.py) |
 | [CloudFormation Custom Resource](#cloudformation-custom-resource) | `CloudFormationCustomResourceEvent` | [Github](https://github.com/aws-powertools/powertools-lambda-python/blob/develop/aws_lambda_powertools/utilities/data_classes/cloudformation_custom_resource_event.py) |
 | [CloudWatch Alarm State Change Action](#cloudwatch-alarm-state-change-action) | `CloudWatchAlarmEvent` | [Github](https://github.com/aws-powertools/powertools-lambda-python/blob/develop/aws_lambda_powertools/utilities/data_classes/cloud_watch_alarm_event.py) |
 | [CloudWatch Dashboard Custom Widget](#cloudwatch-dashboard-custom-widget) | `CloudWatchDashboardCustomWidgetEvent` | [Github](https://github.com/aws-powertools/powertools-lambda-python/blob/develop/aws_lambda_powertools/utilities/data_classes/cloud_watch_custom_widget_event.py) |
diff --git a/docs/utilities/parser.md b/docs/utilities/parser.md
@@ -112,7 +112,8 @@ The example above uses `SqsModel`. Other built-in models can be found below.
 | **APIGatewayWebSocketConnectEventModel**    | Lambda Event Source payload for Amazon API Gateway WebSocket API $connect message             |
 | **APIGatewayWebSocketDisconnectEventModel** | Lambda Event Source payload for Amazon API Gateway WebSocket API $disconnect message          |
 | **AppSyncResolverEventModel**               | Lambda Event Source payload for AWS AppSync Resolver                                          |
-| **BedrockAgentEventModel**                  | Lambda Event Source payload for Bedrock Agents                                                |
+| **BedrockAgentEventModel**                  | Lambda Event Source payload for Bedrock Agents - OpenAPI-based                                |
+| **BedrockAgentFunctionEventModel**          | Lambda Event Source payload for Bedrock Agents - Function-based                               |
 | **CloudFormationCustomResourceCreateModel** | Lambda Event Source payload for AWS CloudFormation `CREATE` operation                         |
 | **CloudFormationCustomResourceUpdateModel** | Lambda Event Source payload for AWS CloudFormation `UPDATE` operation                         |
 | **CloudFormationCustomResourceDeleteModel** | Lambda Event Source payload for AWS CloudFormation `DELETE` operation                         |
diff --git a/examples/event_handler_bedrock_agents/src/accessing_request_fields.py b/examples/event_handler_bedrock_agents/src/accessing_request_fields.py
@@ -8,7 +8,7 @@
 app = BedrockAgentResolver()
 
 
-@app.get("/current_time", description="Gets the current time in seconds")  # (1)!
+@app.get("/current_time", description="Gets the current time in seconds")
 def current_time() -> int:
     logger.append_keys(
         session_id=app.current_event.session_id,
diff --git a/examples/event_handler_bedrock_agents/src/getting_started_functions.py b/examples/event_handler_bedrock_agents/src/getting_started_functions.py
@@ -0,0 +1,21 @@
+from time import time
+
+from aws_lambda_powertools import Logger, Tracer
+from aws_lambda_powertools.event_handler import BedrockAgentFunctionResolver
+from aws_lambda_powertools.utilities.typing import LambdaContext
+
+tracer = Tracer()
+logger = Logger()
+app = BedrockAgentFunctionResolver()
+
+
+@app.tool(name="currentTime", description="Gets the current time in seconds")  # (1)!
+@tracer.capture_method
+def current_time() -> int:
+    return int(time())
+
+
+@logger.inject_lambda_context
+@tracer.capture_lambda_handler
+def lambda_handler(event: dict, context: LambdaContext):
+    return app.resolve(event, context)  # (2)!
diff --git a/examples/event_handler_bedrock_agents/src/getting_started_output_func.json b/examples/event_handler_bedrock_agents/src/getting_started_output_func.json
@@ -0,0 +1,14 @@
+{
+    "messageVersion": "1.0",
+    "response": {
+        "actionGroup": "CurrentTime",
+        "function": "CurrentTime",
+        "functionResponse": {
+            "responseBody": {
+                "application/json": {
+                    "body": "1704708165"
+                }
+            }
+        }
+    }
+}
diff --git a/examples/event_handler_bedrock_agents/src/input_getting_started_func.json b/examples/event_handler_bedrock_agents/src/input_getting_started_func.json
@@ -0,0 +1,16 @@
+{
+  "messageVersion": "1.0",
+  "agent": {
+    "name": "TimeAgent",
+    "id": "XLHH72XNF2",
+    "alias": "TSTALIASID",
+    "version": "DRAFT"
+  },
+  "inputText": "What is the current time?",
+  "sessionId": "123456789012345",
+  "actionGroup": "CurrentTime",
+  "function": "CurrentTime",
+  "parameters": [],
+  "sessionAttributes": {},
+  "promptSessionAttributes": {}
+}
diff --git a/examples/event_handler_bedrock_agents/src/input_validation_schema_func.json b/examples/event_handler_bedrock_agents/src/input_validation_schema_func.json
@@ -0,0 +1,19 @@
+{
+    "messageVersion": "1.0",
+    "agent": {
+        "name": "TestAgent",
+        "id": "XXXXX",
+        "alias": "LATEST",
+        "version": "DRAFT"
+    },
+    "inputText": "Schedule a meeting with john@example.com",
+    "sessionId": "session-id",
+    "actionGroup": "TestActionGroup",
+    "function": "schedule_meeting",
+    "parameters": [
+        {
+            "name": "email",
+            "value": "john@example.com"
+        }
+    ]
+}
diff --git a/examples/event_handler_bedrock_agents/src/output_validation_schema_func.json b/examples/event_handler_bedrock_agents/src/output_validation_schema_func.json
@@ -0,0 +1,17 @@
+{
+    "messageVersion": "1.0",
+    "response": {
+        "actionGroup": "TestActionGroup",
+        "function": "schedule_meeting",
+        "functionResponse": {
+            "responseBody": {
+                "TEXT": {
+                    "body": "true"
+                }
+            }
+        }
+    },
+    "sessionAttributes": {
+        "last_email": "john@example.com"
+    }
+}
diff --git a/examples/event_handler_bedrock_agents/src/validation_failure_input_func.json b/examples/event_handler_bedrock_agents/src/validation_failure_input_func.json
@@ -0,0 +1,16 @@
+{
+    "messageVersion": "1.0",
+    "agent": {
+        "name": "TestAgent",
+        "id": "XXXXX",
+        "alias": "LATEST",
+        "version": "DRAFT"
+    },
+    "parameters": [
+        {
+            "name": "email",
+            "value": "not-an-email"
+        }
+    ],
+    "function": "schedule_meeting"
+}
diff --git a/examples/event_handler_bedrock_agents/src/validation_failure_output_func.json b/examples/event_handler_bedrock_agents/src/validation_failure_output_func.json
@@ -0,0 +1,14 @@
+{
+    "messageVersion": "1.0",
+    "response": {
+        "actionGroup": "TestActionGroup",
+        "function": "schedule_meeting",
+        "functionResponse": {
+            "responseBody": {
+                "TEXT": {
+                    "body": "Error: Invalid value for parameter 'email': value is not a valid email address"
+                }
+            }
+        }
+    }
+}
diff --git a/examples/event_handler_bedrock_agents/src/validation_schema_func.py b/examples/event_handler_bedrock_agents/src/validation_schema_func.py
@@ -0,0 +1,22 @@
+from pydantic import EmailStr
+
+from aws_lambda_powertools import Logger, Tracer
+from aws_lambda_powertools.event_handler import BedrockAgentFunctionResolver
+from aws_lambda_powertools.event_handler.bedrock_agent_function import BedrockFunctionResponse
+
+tracer = Tracer()
+logger = Logger()
+app = BedrockAgentFunctionResolver()
+
+
+@app.tool(description="Schedules a meeting with the team")
+@tracer.capture_method
+def schedule_meeting(email: EmailStr) -> BedrockFunctionResponse:
+    logger.info("Scheduling a meeting", email=email)
+    return BedrockFunctionResponse(body=True, session_attributes={"last_email": str(email)})
+
+
+@logger.inject_lambda_context
+@tracer.capture_lambda_handler
+def lambda_handler(event: dict, context):
+    return app.resolve(event, context)
diff --git a/examples/event_handler_bedrock_agents/src/working_bedrock_functions_response.py b/examples/event_handler_bedrock_agents/src/working_bedrock_functions_response.py
@@ -0,0 +1,15 @@
+from aws_lambda_powertools.event_handler import BedrockFunctionAgentResolver
+from aws_lambda_powertools.event_handler.api_gateway import BedrockFunctionResponse
+
+app = BedrockFunctionAgentResolver()
+
+
+@app.tool(description="Function that demonstrates response customization")
+def custom_response():
+    return BedrockFunctionResponse(
+        body="Hello World",
+        session_attributes={"user_id": "123"},
+        prompt_session_attributes={"last_action": "greeting"},
+        response_state="REPROMPT",
+        knowledge_bases=[{"name": "kb1", "enabled": True}],
+    )
diff --git a/tests/functional/event_handler/required_dependencies/test_bedrock_agent_functions.py b/tests/functional/event_handler/required_dependencies/test_bedrock_agent_functions.py
@@ -12,7 +12,7 @@ def test_bedrock_agent_function_with_string_response():
     # GIVEN a Bedrock Agent Function resolver
     app = BedrockAgentFunctionResolver()
 
-    @app.tool(description="Returns a string")
+    @app.tool()
     def test_function():
         assert isinstance(app.current_event, BedrockAgentFunctionEvent)
         return "Hello from string"
