docs(event_handler): add bedrock agent resolver documentation

[rubenfonseca]

Issue number: #3326

Summary

Changes

Please provide a summary of what's being changed

This PR adds documentation to the Bedrock Agent resolver feature.

Note: to allow sharing content between REST and Bedrock Agents resolvers, some content was moved to shared files and imported in both sides.

User experience

Please share what the user experience looks like before and after this change

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.

[sonarcloud]

Quality Gate passed

The SonarCloud Quality Gate passed, but some issues were introduced.

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

See analysis details on SonarCloud

[leandrodamascena]

This new Resolver for Bedrock Agents is truly a game changer @rubenfonseca!

I left some comments and I think we need to make it more clear to the customers:

1 - Create a diagram explaining how the Bedrock Agent works with Lambda.
2 - Add the video you are creating to make clear the amazing value-added of this utility.
3 - We need to rethink some sections of this documentation. I think we are investing a lot of documentation in SwaggerUI and not enough in Bedrock Agent, and the problems that this new Resolver solves.

Thanks brother ❤️

[sonarcloud]

Please retry analysis of this Pull-Request directly on SonarCloud

[heitorlessa]

Bedrock review

I love the user-experience. It makes authoring Agents as easy as writing an API - straight to the point, readable by anyone.

For documentation, these are key areas we discussed during docs review that can take the current documentation to the next level:

Tip

Mental model
We treat documentation as a product. Customers come to solve a known problem but stay to learn how to solve other problems they didn't know they had (or could have).

• From zero to hero. Make use of the Terminology section, diagrams, and progressive examples that go from trivial to non-trivial. The Data Masking is a good reference to borrow ideas on how to make an incredibly complex subject more approachable to many personas. [Problem] As of now, the docs work great for an expert who is looking to turn this task more productive. They may or may not know about how to use Pydantic integration to make data validation a breeze here. For the non-expert, non-developer, we risk losing them from even trying as it will feel foreign to them - they may or may not be coming from official docs, social media, or from our own docs hoping to squeeze more from the project's feature set.

• Expand on setup needed. Make use of the Required resources and IAM permissions sections, and a table to split up what needs to happen before-hand. We can lower the bar for entry by being upfront of steps they need to do with Bedrock Agents vs AWS Lambda vs code they will need to author with Powertools - we can link them too. [Problem] The mental model you laid down is great on the steps that are needed to get this working, it just needs more details, anchors, and prevent a "tab hell" by exploring multiple locations to get to the first "wow" moment.

• Explain the mechanics. Use Sequence diagrams to help customers go from a high level diagram to understanding what's the complexity we're abstracting to make their lives easier. This will help demystify Bedrock Agents, who is responsible for what, and create a better picture in their heads (information turned knowledge). [Problem] The first diagram is great! We can however take this opportunity to feed customers hungry for knowledge in this difficult field, since we know it takes a humongous effort to understand the pieces of the puzzle.

Items

• Bedrock Agents trademark - do we have to use Agents for Amazon Bedrock or can we stay as-is
• Link to OpenAPI Schema definition
• Focus on non-developers too
• Explicit IAM permissions
• Decide on pydantic install extra group -- should we use data-validation (reuse), or bedrock?
• Be aware of the use of Powertools instead of Powertools for AWS; sometimes you can use simply Event Handler resolvers
• Correct Input/Output payload
• Create a new section with an use case you use information available in the input payload
• Move data validation to Getting Started, and provide a less trivial example
• Create an example on additional metadata and/or OpenAPI params to demonstrate the value with an use case
• Change implementation to make "description" field being derived automatically
• Include Agents for Bedrock video

PS: @hjgraca please chime in if I missed anything from today's session.

[am29d]

Minor changers

[sthulb]

There's a few places where you're using a singular agent as "Agent" (cap 'A') where it should be lower case. "Agent" refers to the feature not the concept (if that makes sense)

[leandrodamascena]

Hello @rubenfonseca! We have some wrong characters that are breaking the links. I made suggestions to correct it.

[leandrodamascena]

Hello @rubenfonseca! Another batch of small suggestions! Thanks.

[sonarcloud]

Quality Gate passed

Issues
1 New issue
0 Accepted issues

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

See analysis details on SonarCloud

[rubenfonseca]

@leandrodamascena sorry for the mess, everything should be fixed now

[leandrodamascena]

Congrats to everyone who contributed to this PR. We always make a difference in the lives of our customers when we provide very clear and concise documentation.

APPROVED!