Skip to content

Commit 5d98bed

Browse files
authored
Python: feat(bedrock): implement native structured output support via Converse API (#6052)
* feat(bedrock): add structured output support via Converse API (Fixes #5966) * fix(bedrock): improve unsupported model exception handling and schema parsing * refactor(bedrock): use generic traversal for strict schema enforcement * address Copilot review comments on structured output * refine bedrock structured output: guard additionalProperties, TypeError check, docs + test * fix(bedrock): widen response_format to Mapping and add missing test coverage
1 parent e0d0ad1 commit 5d98bed

2 files changed

Lines changed: 526 additions & 12 deletions

File tree

‎python/packages/bedrock/agent_framework_bedrock/_chat_client.py‎

Lines changed: 144 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@
44
from __future__ import annotations
55

66
import asyncio
7+
import copy
78
import json
89
import logging
910
import sys
@@ -36,6 +37,7 @@
3637
from boto3.session import Session as Boto3Session
3738
from botocore.client import BaseClient
3839
from botocore.config import Config as BotoConfig
40+
from botocore.exceptions import ClientError
3941
from pydantic import BaseModel
4042

4143
if sys.version_info >= (3, 13):
@@ -115,13 +117,20 @@ class BedrockChatOptions(ChatOptions[ResponseModelT], Generic[ResponseModelT], t
115117
translates to ``toolConfig.tools``.
116118
tool_choice: How the model should use tools,
117119
translates to ``toolConfig.toolChoice``.
120+
response_format: Structured output format. Accepts a Pydantic BaseModel
121+
subclass or an OpenAI-style dict schema
122+
(``{"json_schema": {"name": ..., "schema": ...}}``).
123+
When provided, the Converse API request includes
124+
``outputConfig.textFormat`` with the schema serialized as a JSON
125+
string. ``ChatResponse.value`` will be populated with the parsed
126+
model instance. Only supported on models that support
127+
``outputConfig.textFormat``. Unsupported models raise a ValueError.
118128
119129
# Options not supported in Bedrock Converse API:
120130
seed: Not supported.
121131
frequency_penalty: Not supported.
122132
presence_penalty: Not supported.
123133
allow_multiple_tool_calls: Not supported (models handle parallel calls automatically).
124-
response_format: Not directly supported (use model-specific prompting).
125134
user: Not supported.
126135
store: Not supported.
127136
logit_bias: Not supported.
@@ -161,9 +170,6 @@ class BedrockChatOptions(ChatOptions[ResponseModelT], Generic[ResponseModelT], t
161170
allow_multiple_tool_calls: None # type: ignore[misc]
162171
"""Not supported. Bedrock models handle parallel tool calls automatically."""
163172

164-
response_format: None # type: ignore[misc]
165-
"""Not directly supported. Use model-specific prompting for JSON output."""
166-
167173
user: None # type: ignore[misc]
168174
"""Not supported in Bedrock Converse API."""
169175

@@ -324,10 +330,28 @@ def _create_session(settings: BedrockSettings) -> Boto3Session:
324330
return Boto3Session(**session_kwargs)
325331

326332
def _invoke_converse(self, request: Mapping[str, Any]) -> dict[str, Any]:
327-
response = self._bedrock_client.converse(**request)
328-
if not isinstance(response, Mapping):
329-
raise ChatClientInvalidResponseException("Bedrock converse response must be a mapping.")
330-
return response
333+
try:
334+
response = self._bedrock_client.converse(**request)
335+
if not isinstance(response, Mapping):
336+
raise ChatClientInvalidResponseException("Bedrock converse response must be a mapping.")
337+
return response
338+
except ClientError as e:
339+
error_details = e.response.get("Error", {})
340+
error_code = error_details.get("Code", "")
341+
error_message = error_details.get("Message", "")
342+
# "outputConfig" in error_message catches cases where Bedrock explicitly
343+
# rejects the outputConfig field (unsupported model). Other ValidationExceptions
344+
# (e.g. malformed schema shape, invalid property values) will not mention
345+
# "outputConfig" and will bubble up as raw ClientError without being misdiagnosed.
346+
if error_code == "ValidationException" and (
347+
"outputconfig" in error_message.lower() or "outputconfig" in str(e).lower()
348+
):
349+
raise ValueError(
350+
f"Model '{self.model}' does not support structured output via outputConfig.textFormat. "
351+
"Check the model's Bedrock Converse outputConfig/textFormat support. "
352+
f"AWS error Code: {error_code}. AWS error Message: {error_message}"
353+
) from e
354+
raise
331355

332356
@override
333357
def _inner_get_response(
@@ -344,7 +368,7 @@ def _inner_get_response(
344368
# Streaming mode - simulate streaming by yielding a single update
345369
async def _stream() -> AsyncIterable[ChatResponseUpdate]:
346370
response = await asyncio.to_thread(self._invoke_converse, request)
347-
parsed_response = self._process_converse_response(response)
371+
parsed_response = self._process_converse_response(response, options)
348372
contents = list(parsed_response.messages[0].contents if parsed_response.messages else [])
349373
if parsed_response.usage_details:
350374
contents.append(Content.from_usage(usage_details=parsed_response.usage_details)) # type: ignore[arg-type]
@@ -360,12 +384,12 @@ async def _stream() -> AsyncIterable[ChatResponseUpdate]:
360384
raw_representation=parsed_response.raw_representation,
361385
)
362386

363-
return self._build_response_stream(_stream())
387+
return self._build_response_stream(_stream(), response_format=options.get("response_format"))
364388

365389
# Non-streaming mode
366390
async def _get_response() -> ChatResponse:
367391
raw_response = await asyncio.to_thread(self._invoke_converse, request)
368-
return self._process_converse_response(raw_response)
392+
return self._process_converse_response(raw_response, options)
369393

370394
return _get_response()
371395

@@ -430,6 +454,9 @@ def _prepare_options(
430454
if tool_config:
431455
run_options["toolConfig"] = tool_config
432456

457+
if output_config := self._prepare_output_config(options.get("response_format")):
458+
run_options["outputConfig"] = output_config
459+
433460
return run_options
434461

435462
def _prepare_bedrock_messages(
@@ -628,7 +655,9 @@ def _prepare_tools(self, tools: list[FunctionTool | MutableMapping[str, Any]] |
628655
def _generate_tool_call_id() -> str:
629656
return f"tool-call-{uuid4().hex}"
630657

631-
def _process_converse_response(self, response: dict[str, Any]) -> ChatResponse:
658+
def _process_converse_response(
659+
self, response: dict[str, Any], options: Mapping[str, Any] | None = None
660+
) -> ChatResponse:
632661
"""Convert Bedrock Converse API response to ChatResponse."""
633662
output = response.get("output") or {}
634663
message = output.get("message") or {}
@@ -646,6 +675,7 @@ def _process_converse_response(self, response: dict[str, Any]) -> ChatResponse:
646675
usage_details=usage_details,
647676
model=model,
648677
finish_reason=finish_reason,
678+
response_format=options.get("response_format") if options else None,
649679
raw_representation=response,
650680
)
651681

@@ -728,6 +758,108 @@ def _map_finish_reason(self, reason: str | None) -> FinishReasonLiteral | None:
728758
return None
729759
return FINISH_REASON_MAP.get(reason.lower())
730760

761+
def _prepare_output_config(self, response_format: Any | None) -> dict[str, Any] | None:
762+
"""Convert response_format into the AWS Bedrock outputConfig wire format.
763+
764+
Args:
765+
response_format: A Pydantic model class or a dict schema, or None.
766+
767+
Returns:
768+
A dict for the Converse API ``outputConfig`` parameter, or None if
769+
response_format is not set.
770+
"""
771+
if response_format is None:
772+
return None
773+
774+
if isinstance(response_format, Mapping):
775+
if "json_schema" in response_format:
776+
# Shape A — OpenAI-style wrapper
777+
json_schema_config = response_format["json_schema"]
778+
schema_src = json_schema_config.get("schema", {})
779+
name = json_schema_config.get("name", "output_schema")
780+
elif "schema" in response_format:
781+
# Shape B — inner shape directly {"name": ..., "schema": ...}
782+
schema_src = response_format["schema"]
783+
name = response_format.get("name", "output_schema")
784+
else:
785+
# Shape C — assume entire dict is the raw schema
786+
logger.warning(
787+
"response_format dict has no 'json_schema' or 'schema' key; "
788+
"treating entire dict as raw JSON schema."
789+
)
790+
schema_src = dict(response_format)
791+
name = "output_schema"
792+
793+
if isinstance(schema_src, str):
794+
schema_src = json.loads(schema_src)
795+
schema = copy.deepcopy(schema_src)
796+
else:
797+
if not isinstance(response_format, type) or not issubclass(response_format, BaseModel):
798+
raise TypeError(
799+
"response_format must be None, a dict JSON schema, "
800+
"or a Pydantic BaseModel subclass."
801+
)
802+
# response_format is a Pydantic model class
803+
schema = response_format.model_json_schema()
804+
name = response_format.__name__
805+
806+
self._set_additional_properties_false(schema)
807+
808+
json_schema: dict[str, Any] = {
809+
"name": name,
810+
"schema": json.dumps(schema),
811+
}
812+
813+
description = getattr(response_format, "__doc__", None) if not isinstance(response_format, Mapping) else None
814+
if description and isinstance(description, str) and description.strip():
815+
json_schema["description"] = description.strip()
816+
817+
return {
818+
"textFormat": {
819+
"type": "json_schema",
820+
"structure": {
821+
"jsonSchema": json_schema
822+
},
823+
}
824+
}
825+
826+
def _set_additional_properties_false(self, schema: dict[str, Any]) -> None:
827+
"""Recursively set additionalProperties: false on all object types in a JSON schema.
828+
829+
AWS requires strict schema enforcement. This mirrors the approach used by
830+
AnthropicChatClient._prepare_response_format().
831+
832+
Args:
833+
schema: The JSON schema dict to modify in-place.
834+
"""
835+
visited: set[int] = set()
836+
837+
def walk(node: Any) -> None:
838+
if isinstance(node, dict):
839+
node_id = id(node)
840+
if node_id in visited:
841+
return
842+
visited.add(node_id)
843+
if node.get("type") == "object" or (
844+
"properties" in node and "type" not in node
845+
):
846+
existing = node.get("additionalProperties")
847+
if existing is None or existing is True:
848+
node["additionalProperties"] = False
849+
for value in node.values():
850+
if isinstance(value, (dict, list)):
851+
walk(value)
852+
elif isinstance(node, list):
853+
node_id = id(node)
854+
if node_id in visited:
855+
return
856+
visited.add(node_id)
857+
for item in node:
858+
if isinstance(item, (dict, list)):
859+
walk(item)
860+
861+
walk(schema)
862+
731863
def service_url(self) -> str:
732864
"""Returns the service URL for the Bedrock runtime in the configured AWS region.
733865

0 commit comments

Comments
 (0)