You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/core/event_handler/api_gateway.md
+13-2Lines changed: 13 additions & 2 deletions
Original file line number
Diff line number
Diff line change
@@ -476,7 +476,15 @@ We provide pre-defined errors for the most popular ones such as HTTP 400, 401, 4
476
476
477
477
!!! note "This feature requires [data validation](#data-validation) feature to be enabled."
478
478
479
-
--8<-- "docs/core/event_handler/_swagger_ui.md"
479
+
Behind the scenes, the [data validation](api_gateway.md#data-validation) feature auto-generates an OpenAPI specification from your routes and type annotations. You can use [Swagger UI](https://swagger.io/tools/swagger-ui/){target="_blank" rel="nofollow"} to visualize and interact with your newly auto-documented API.
480
+
481
+
There are some important **caveats** that you should know before enabling it:
| Swagger UI is **publicly accessible by default**| When using `enable_swagger` method, you can [protect sensitive API endpoints by implementing a custom middleware](api_gateway.md#customizing-swagger-ui) using your preferred authorization mechanism. |
486
+
|**No micro-functions support** yet | Swagger UI is enabled on a per resolver instance which will limit its accuracy here. |
487
+
| You need to expose **new routes**| You'll need to expose the following paths to Lambda: `/swagger`, `/swagger.css`, `/swagger.js`; ignore if you're routing all paths already. |
The `enable_swagger` method accepts the same metadata as described at [Customizing OpenAPI metadata](api_gateway.md#customizing-openapi-metadata).
940
+
941
+
The Swagger UI appears by default at the `/swagger` path, but you can customize this to serve the documentation from another path and specify the source for Swagger UI assets.
931
942
932
943
Below is an example configuration for serving Swagger UI from a custom path or CDN, with assets like CSS and JavaScript loading from a chosen CDN base URL.
Copy file name to clipboardExpand all lines: docs/core/event_handler/bedrock_agents.md
+45-48Lines changed: 45 additions & 48 deletions
Original file line number
Diff line number
Diff line change
@@ -9,31 +9,41 @@ Event handler for Amazon Bedrock Agents, including auto generation of OpenAPI sc
9
9
10
10
* Same declarative syntax as the [other Powertools event handlers](api_gateway.md)
11
11
* Drastically reduce the boilerplate to build Agents for Amazon Bedrock
12
-
* Automatic generation of OpenAPI schemas from the API
12
+
* Automatic generation of OpenAPI schemas from your business logic code
13
13
* Built-in data validation for requests/responses
14
14
15
15
## Getting started
16
16
17
-
In order to build Bedrock Agents, you need:
17
+
```mermaid
18
+
flowchart LR
19
+
Bedrock <--> Agent
20
+
Agent -- invokes --> Lambda[Lambda function]
21
+
Agent -- consults --> OpenAPI{{OpenAPI schema}}
22
+
OpenAPI -. generated from .-> Lambda
23
+
```
24
+
25
+
To build Bedrock Agents, you need:
18
26
19
-
* Create the Lambda function that defines the business logic for the action that your agent will carry out
27
+
* Create the Lambda function that defines the business logic for the action that your agent carries out.
20
28
* Create an OpenAPI schema with the API description, structure, and parameters for the action group.
21
29
* Ensure that Bedrock and your Lambda functions have the [necessary permissions](https://docs.aws.amazon.com/bedrock/latest/userguide/agents-permissions.html).
22
30
23
-
AWS Lambda Powertools facilitates the process by providing support for the development of the Lambda function and the creation of the OpenAPI specification.
31
+
Powertools makes it easier to author the Lambda function and the creation of the OpenAPI schema.
24
32
25
-
!!! info "This is not necessary if you're installing Powertools for AWS Lambda (Python) via [Lambda Layer/SAR](../../index.md#lambda-layer){target="_blank"}."
33
+
!!! info "This is unnecessary if you're installing Powertools for AWS Lambda (Python) via [Lambda Layer/SAR](../../index.md#lambda-layer){target="_blank"}."
26
34
27
35
You need to add `pydantic` as a dependency in your preferred tool _e.g., requirements.txt, pyproject.toml_.
28
36
29
-
As of now, both Pydantic V1 and V2 are supported. For a future major version, we will only support Pydantic V2.
37
+
At this time, we support both Pydantic V1 and V2. For a future major version, we will only support Pydantic V2.
30
38
31
39
### Your first Agent
32
40
33
-
To create a Bedrock Agent, use the `BedrockAgentResolver` to annotate your actions. This is
34
-
similar to the way [all the other Powertools](api_gateway.md) resolvers work.
41
+
To create a Bedrock Agent, use the `BedrockAgentResolver` to annotate your actions.
42
+
This is similar to the way [all the other Powertools](api_gateway.md) resolvers work.
35
43
36
-
Be aware that it's important to include a description for each API endpoint. The description is essential because it provides Bedrock Agents with an understanding of the primary function of your API action.
44
+
???+ note
45
+
It's important to include a description for each API endpoint.
46
+
This provides Bedrock Agents with an understanding of your API action.
37
47
38
48
=== "Lambda handler"
39
49
@@ -42,6 +52,7 @@ Be aware that it's important to include a description for each API endpoint. The
42
52
```
43
53
44
54
1. `description` is a required field in order for Bedrock Agents to work.
55
+
2. Powertools take care of parsing, validate, routing and responding to the request.
45
56
46
57
=== "Input payload"
47
58
@@ -55,47 +66,51 @@ Be aware that it's important to include a description for each API endpoint. The
The resolvers utilized by Bedrock Agents are also compatible with the full suite of Powertools utilities. This ensures seamless integration and functionality across the different tools provided by Powertools when working with Bedrock Agents.
69
+
The resolvers used by Bedrock Agents are compatible with the full suite of Powertools utilities.
70
+
This includes [Logger](../logger.md), [Metrics](../metrics.md) and [Tracer](../tracer.md).
59
71
60
72
### Generating OpenAPI schemas
61
73
62
-
To create a schema for your API, use the `get_openapi_json_schema` function provided by the Bedrock Agent resolver. This function will produce a JSON-serialized string that represents your schema. You have the option to either display this string output or save it to a file for future reference.
74
+
Use the `get_openapi_json_schema` function provided by the Bedrock Agent resolver.
75
+
This function will produce a JSON-serialized string that represents your OpenAPI schema.
76
+
You can print this string or save it to a file for future reference.
To obtain the OpenAPI schema, execute the Python script from the command line interface (CLI). Upon execution, the script will generate the schema, which will be output directly to the console.
77
-
78
-
### Creating your Agent in the AWS Console
93
+
To get the OpenAPI schema, run the Python script from your terminal.
94
+
The script will generate the schema directly to standard output, which you can redirect to a file.
79
95
80
-
To create a Bedrock Agent, you should refer to the [official documentation](https://docs.aws.amazon.com/bedrock/latest/userguide/agents-create.html) provided by AWS.
81
-
82
-
During the creation process, when the user interface (UI) prompts you for an OpenAPI specification, you should input the specification that was generated in the previous step. This is the spec that you obtained by running your Python script, which produced the OpenAPI schema as output.
96
+
```sh
97
+
python app.py > schema.json
98
+
```
83
99
84
-
### Enabling the Swagger UI
100
+
### Creating your Agent on the AWS Console
85
101
86
-
--8<-- "docs/core/event_handler/_swagger_ui.md"
102
+
To create an Agent for Bedrock, refer to the [official documentation](https://docs.aws.amazon.com/bedrock/latest/userguide/agents-create.html) provided by AWS.
The following video demonstrates the end-to-end process:
91
105
92
-
1.`enable_swagger` creates a route to serve Swagger UI and allows quick customizations. <br><br> You can also include middlewares to protect or enhance the overall experience.
106
+
During the creation process, you can use the schema generated in the previous step when prompted for an OpenAPI specification.
93
107
94
108
## Advanced
95
109
96
110
### Additional metadata
97
111
98
-
To enrich the view that Bedrock Agents has of your Lambda functions, we use a combination of Pydantic Models and [OpenAPI](https://www.openapis.org/){target="_blank"} type annotations to add constraints to your API's parameters.
112
+
To enrich the view that Agents for Bedrock has of your Lambda functions,
113
+
use a combination of [Pydantic Models](https://docs.pydantic.dev/latest/concepts/models/){target="_blank"} and [OpenAPI](https://www.openapis.org/){target="_blank"} type annotations to add constraints to your APIs parameters.
Below is an example configuration for serving Swagger UI from a custom path or CDN, with assets like CSS and JavaScript loading from a chosen CDN base URL.
@@ -147,16 +142,18 @@ Include extra parameters when exporting your OpenAPI specification to apply thes
147
142
148
143
### Data validation
149
144
150
-
The Bedrock Agents Resolver allows for the clear definition of the expected format for incoming data and responses. By delegating data validation tasks to the Event Handler resolvers, you can significantly reduce the amount of repetitive code in your project.
145
+
The Bedrock Agents Resolver allows for the clear definition of the expected format for incoming data and responses.
146
+
By delegating data validation tasks to Powertools, you can significantly reduce the amount of repetitive code in your project.
151
147
152
-
For detailed guidance on implementing this feature, please consult the [REST API validation documentationi](api_gateway.md#data-validation). There, you'll find step-by-step instructions on how to apply data validation when using the resolver.
148
+
For detailed guidance on implementing this feature, see the [REST API validation documentation](api_gateway.md#data-validation).
149
+
There, you'll find step-by-step instructions on how to apply data validation when using the resolver.
153
150
154
151
???+ note
155
152
When using the Bedrock Agent resolver, there's no need to add the `enable_validation` parameter, as it's enabled by default.
156
153
157
154
## Testing your code
158
155
159
-
You can test your routes by passing a proxy event request with required params.
156
+
Test your routes by passing a Bedrock Agents proxy event request:
0 commit comments