docs: clarify BedrockResponse.is_json() always returns True (#7748)

Addresses #7692

- Added comprehensive docstring to BedrockResponse.is_json() explaining
  why it always returns True regardless of content_type parameter
- Updated BedrockResponse class docstring with note about Bedrock Agents
  only supporting TEXT content type
- Added tip in bedrock_agents.md documentation to clarify content_type
  behavior for users
- Included AWS documentation reference for context

The content_type parameter is maintained for API consistency but does not
affect the actual response format sent to Bedrock Agents, as they only
support TEXT content type per AWS Lambda integration docs.

Co-authored-by: Leandro Damascena <lcdama@amazon.pt>

Author: oyiz-michael

aws_lambda_powertools/event_handler/api_gateway.py

@@ -261,6 +261,15 @@ class BedrockResponse(Generic[ResponseT]):
     """
     Contains the response body, status code, content type, and optional attributes
     for session management and knowledge base configuration.
+
+    Note
+    ----
+    Amazon Bedrock Agents only support TEXT content type in the responseBody according to the
+    Lambda integration documentation. As a result, all response bodies are automatically serialized
+    as JSON strings regardless of the content_type parameter. The content_type parameter is maintained
+    for API consistency but does not affect the actual format sent to Bedrock Agents.
+
+    See: https://docs.aws.amazon.com/bedrock/latest/userguide/agents-lambda.html
     """
 
     def __init__(
@@ -282,6 +291,18 @@ def __init__(
     def is_json(self) -> bool:
         """
         Returns True if the response is JSON, based on the Content-Type.
+
+        Note
+        ----
+        This method always returns True for BedrockResponse regardless of the content_type parameter.
+        This is because Amazon Bedrock Agents only support TEXT content type in the responseBody,
+        and the event handler automatically serializes all response bodies as JSON strings when
+        sending to Bedrock Agents.
+
+        See: https://docs.aws.amazon.com/bedrock/latest/userguide/agents-lambda.html
+
+        The content_type parameter in BedrockResponse is maintained for API consistency but does not
+        affect the actual response format sent to Bedrock Agents.
         """
         return True
 

docs/core/event_handler/bedrock_agents.md

@@ -333,6 +333,11 @@ You can enable user confirmation with Bedrock Agents to have your application as
 
 You can use `BedrockResponse` class to add additional fields as needed, such as [session attributes, prompt session attributes, and knowledge base configurations](https://docs.aws.amazon.com/bedrock/latest/userguide/agents-lambda.html#agents-lambda-response){target="_blank"}.
 
+???+ tip "Content Type Behavior"
+	Amazon Bedrock Agents only support TEXT content type in the responseBody. All response bodies are automatically serialized as JSON strings regardless of the `content_type` parameter you provide. The `content_type` parameter exists for API consistency but does not affect the actual format sent to Bedrock Agents.
+	
+	Learn more: [AWS Bedrock Lambda Integration](https://docs.aws.amazon.com/bedrock/latest/userguide/agents-lambda.html){target="_blank"}
+
 ```python title="working_with_bedrockresponse.py" title="Customzing your Bedrock Response" hl_lines="5 16"
 --8<-- "examples/event_handler_bedrock_agents/src/working_with_bedrockresponse.py"
 ```