From 1621a3631524e7da6453aa4e21c6ddeef1c343b0 Mon Sep 17 00:00:00 2001 From: Ben Clarke Date: Sat, 7 Nov 2026 23:58:07 +0000 Subject: [PATCH 1/4] fix(tools): include the response schema in RestApiTool declarations - Set response_json_schema on the function declaration from the operation's parsed 2xx response schema, as McpTool does with outputSchema. - Add OperationParser.get_response_json_schema(), which returns None when the operation declares no 2xx response schema. --- .../openapi_spec_parser/operation_parser.py | 7 ++++ .../openapi_spec_parser/rest_api_tool.py | 3 ++ .../test_operation_parser.py | 12 +++++++ .../openapi_spec_parser/test_rest_api_tool.py | 36 +++++++++++++++++++ 4 files changed, 58 insertions(+) diff --git a/src/google/adk/tools/openapi_tool/openapi_spec_parser/operation_parser.py b/src/google/adk/tools/openapi_tool/openapi_spec_parser/operation_parser.py index 127f0f8630d..db8cfa5112f 100644 --- a/src/google/adk/tools/openapi_tool/openapi_spec_parser/operation_parser.py +++ b/src/google/adk/tools/openapi_tool/openapi_spec_parser/operation_parser.py @@ -355,6 +355,13 @@ def get_json_schema(self) -> Dict[str, Any]: 'type': 'object', } + def get_response_json_schema(self) -> Dict[str, Any] | None: + """Returns the JSON schema of the 2xx response, or None if undeclared.""" + schema = jsonable_encoder( + self._require_return_value()._openapi_schema, exclude_none=True + ) + return schema or None + def get_signature_parameters(self) -> List[inspect.Parameter]: """Returns a list of inspect.Parameter objects for the function.""" return [ diff --git a/src/google/adk/tools/openapi_tool/openapi_spec_parser/rest_api_tool.py b/src/google/adk/tools/openapi_tool/openapi_spec_parser/rest_api_tool.py index 18dbb70b259..573bc469e39 100644 --- a/src/google/adk/tools/openapi_tool/openapi_spec_parser/rest_api_tool.py +++ b/src/google/adk/tools/openapi_tool/openapi_spec_parser/rest_api_tool.py @@ -372,6 +372,9 @@ def _get_declaration(self) -> FunctionDeclaration: name=self.name, description=self.description, parameters_json_schema=schema_dict, + response_json_schema=( + self._operation_parser.get_response_json_schema() + ), ) else: parameters = _to_gemini_schema(schema_dict) diff --git a/tests/unittests/tools/openapi_tool/openapi_spec_parser/test_operation_parser.py b/tests/unittests/tools/openapi_tool/openapi_spec_parser/test_operation_parser.py index 9dc0a428229..968e8361121 100644 --- a/tests/unittests/tools/openapi_tool/openapi_spec_parser/test_operation_parser.py +++ b/tests/unittests/tools/openapi_tool/openapi_spec_parser/test_operation_parser.py @@ -466,6 +466,18 @@ def test_get_json_schema(sample_operation): assert 'required' not in json_schema or json_schema['required'] == [] +def test_get_response_json_schema(sample_operation): + parser = OperationParser(sample_operation) + assert parser.get_response_json_schema() == {'type': 'string'} + + +def test_get_response_json_schema_without_2xx_schema(): + parser = OperationParser( + Operation(responses={'400': Response(description='Client Error')}) + ) + assert parser.get_response_json_schema() is None + + def test_get_signature_parameters(sample_operation): """Test get_signature_parameters method.""" parser = OperationParser(sample_operation) diff --git a/tests/unittests/tools/openapi_tool/openapi_spec_parser/test_rest_api_tool.py b/tests/unittests/tools/openapi_tool/openapi_spec_parser/test_rest_api_tool.py index 74d6cefd4f4..63a40e0cba8 100644 --- a/tests/unittests/tools/openapi_tool/openapi_spec_parser/test_rest_api_tool.py +++ b/tests/unittests/tools/openapi_tool/openapi_spec_parser/test_rest_api_tool.py @@ -30,6 +30,7 @@ from fastapi.openapi.models import Operation from fastapi.openapi.models import Parameter as OpenAPIParameter from fastapi.openapi.models import RequestBody +from fastapi.openapi.models import Response from fastapi.openapi.models import Schema as OpenAPISchema from google.adk.auth.auth_credential import AuthCredential from google.adk.auth.auth_credential import AuthCredentialTypes @@ -325,6 +326,41 @@ def test_get_declaration_with_json_schema_feature_enabled( "required": ["test_param"], } + def test_get_declaration_includes_response_json_schema(self): + operation = Operation( + operationId="getPet", + responses={ + "200": Response( + description="The pet.", + content={ + "application/json": MediaType( + schema=OpenAPISchema( + type="object", + properties={"name": OpenAPISchema(type="string")}, + ) + ) + }, + ) + }, + ) + tool = RestApiTool( + name="get_pet", + description="Get a pet.", + endpoint=OperationEndpoint( + base_url="https://petstore.example.com", + path="/pets/1", + method="GET", + ), + operation=operation, + ) + + declaration = tool._get_declaration() + + assert declaration.response_json_schema == { + "type": "object", + "properties": {"name": {"type": "string"}}, + } + class TestRestApiTool: From b1c193a1592cb2fd8136c35082a9686ef396aa88 Mon Sep 17 00:00:00 2001 From: Ben Clarke Date: Sun, 8 Nov 2026 12:26:57 +0000 Subject: [PATCH 2/4] fix(tools): make RestApiTool response schemas opt-in - Add include_response_schema to RestApiTool, from_parsed_operation and OpenAPIToolset, defaulting to False, so declarations only carry the 2xx response schema when asked and existing requests don't grow. - Test the option on RestApiTool and that OpenAPIToolset forwards it. --- .../openapi_spec_parser/openapi_toolset.py | 8 ++++++++ .../openapi_spec_parser/rest_api_tool.py | 12 +++++++++++ .../test_openapi_toolset.py | 17 ++++++++++++++++ .../openapi_spec_parser/test_rest_api_tool.py | 20 ++++++++++++++----- 4 files changed, 52 insertions(+), 5 deletions(-) diff --git a/src/google/adk/tools/openapi_tool/openapi_spec_parser/openapi_toolset.py b/src/google/adk/tools/openapi_tool/openapi_spec_parser/openapi_toolset.py index 417c35a0f59..58fdee1b74a 100644 --- a/src/google/adk/tools/openapi_tool/openapi_spec_parser/openapi_toolset.py +++ b/src/google/adk/tools/openapi_tool/openapi_spec_parser/openapi_toolset.py @@ -100,6 +100,7 @@ def __init__( httpx_client_factory: Optional[HttpxClientFactory] = None, preserve_property_names: bool = False, allow_private_network_access: bool = False, + include_response_schema: bool = False, ) -> None: """Initializes the OpenAPIToolset. @@ -172,6 +173,11 @@ def __init__( ``*.local`` targets and return an error response. Set this to ``True`` to allow requests to private networks, localhost, and custom non-DNS transports. + include_response_schema: If True, each generated tool's function + declaration includes the operation's 2xx response schema as + ``response_json_schema``, so the model can see what the tool returns. + This adds the schemas to every model request that includes the tools. + Defaults to False. """ super().__init__(tool_filter=tool_filter, tool_name_prefix=tool_name_prefix) self._header_provider = header_provider @@ -195,6 +201,7 @@ def __init__( self._ssl_verify = ssl_verify self._httpx_client_factory = httpx_client_factory self._allow_private_network_access = allow_private_network_access + self._include_response_schema = include_response_schema self._tools: Final[List[RestApiTool]] = list(self._parse(spec_dict)) if auth_scheme or auth_credential: self._configure_auth_all(auth_scheme, auth_credential) @@ -290,6 +297,7 @@ def _parse(self, openapi_spec_dict: Dict[str, Any]) -> List[RestApiTool]: header_provider=self._header_provider, httpx_client_factory=self._httpx_client_factory, allow_private_network_access=self._allow_private_network_access, + include_response_schema=self._include_response_schema, ) for o in operations ] diff --git a/src/google/adk/tools/openapi_tool/openapi_spec_parser/rest_api_tool.py b/src/google/adk/tools/openapi_tool/openapi_spec_parser/rest_api_tool.py index 573bc469e39..cc7237b9de2 100644 --- a/src/google/adk/tools/openapi_tool/openapi_spec_parser/rest_api_tool.py +++ b/src/google/adk/tools/openapi_tool/openapi_spec_parser/rest_api_tool.py @@ -205,6 +205,7 @@ def __init__( *, credential_key: Optional[str] = None, allow_private_network_access: bool = False, + include_response_schema: bool = False, ): """Initializes the RestApiTool with the given parameters. @@ -261,6 +262,10 @@ def __init__( ``*.local`` targets and return an error response. Set this to ``True`` to allow requests to private networks, localhost, and custom non-DNS transports. + include_response_schema: If True, the function declaration includes + the operation's 2xx response schema as ``response_json_schema``, so + the model can see what the tool returns. This adds the schema to + every model request that includes the tool. Defaults to False. """ # Gemini restrict the length of function name to be less than 64 characters self.name = name[:_MAX_TOOL_NAME_LENGTH] @@ -289,6 +294,7 @@ def __init__( self._httpx_client_factory = httpx_client_factory self._logger = logger self._allow_private_network_access = allow_private_network_access + self._include_response_schema = include_response_schema if should_parse_operation: self._operation_parser = OperationParser(self.operation) @@ -303,6 +309,7 @@ def from_parsed_operation( httpx_client_factory: Optional[HttpxClientFactory] = None, *, allow_private_network_access: bool = False, + include_response_schema: bool = False, ) -> "RestApiTool": """Initializes the RestApiTool from a ParsedOperation object. @@ -322,6 +329,8 @@ def from_parsed_operation( ``*.local`` targets and return an error response. Set this to ``True`` to allow requests to private networks, localhost, and custom non-DNS transports. + include_response_schema: Whether the function declaration includes the + operation's 2xx response schema. See ``RestApiTool.__init__``. Returns: A RestApiTool object. @@ -344,6 +353,7 @@ def from_parsed_operation( header_provider=header_provider, httpx_client_factory=httpx_client_factory, allow_private_network_access=allow_private_network_access, + include_response_schema=include_response_schema, ) generated._operation_parser = operation_parser return generated @@ -374,6 +384,8 @@ def _get_declaration(self) -> FunctionDeclaration: parameters_json_schema=schema_dict, response_json_schema=( self._operation_parser.get_response_json_schema() + if self._include_response_schema + else None ), ) else: diff --git a/tests/unittests/tools/openapi_tool/openapi_spec_parser/test_openapi_toolset.py b/tests/unittests/tools/openapi_tool/openapi_spec_parser/test_openapi_toolset.py index cefba427795..eaabc62677d 100644 --- a/tests/unittests/tools/openapi_tool/openapi_spec_parser/test_openapi_toolset.py +++ b/tests/unittests/tools/openapi_tool/openapi_spec_parser/test_openapi_toolset.py @@ -262,6 +262,23 @@ def test_openapi_toolset_preserve_property_names(openapi_spec: Dict[str, Any]): assert "calendarId" in schema["properties"] +@pytest.mark.parametrize("include_response_schema", [True, False]) +def test_openapi_toolset_include_response_schema( + openapi_spec: Dict[str, Any], include_response_schema: bool +): + toolset = OpenAPIToolset( + spec_dict=openapi_spec, include_response_schema=include_response_schema + ) + tool = toolset.get_tool("calendar_calendars_get") + assert tool is not None + + declaration = tool._get_declaration() + + assert (declaration.response_json_schema is not None) == ( + include_response_schema + ) + + def test_openapi_toolset_default_snake_case_conversion( openapi_spec: Dict[str, Any], ): diff --git a/tests/unittests/tools/openapi_tool/openapi_spec_parser/test_rest_api_tool.py b/tests/unittests/tools/openapi_tool/openapi_spec_parser/test_rest_api_tool.py index 63a40e0cba8..b4a2feed106 100644 --- a/tests/unittests/tools/openapi_tool/openapi_spec_parser/test_rest_api_tool.py +++ b/tests/unittests/tools/openapi_tool/openapi_spec_parser/test_rest_api_tool.py @@ -326,7 +326,19 @@ def test_get_declaration_with_json_schema_feature_enabled( "required": ["test_param"], } - def test_get_declaration_includes_response_json_schema(self): + @pytest.mark.parametrize( + "include_response_schema,expected", + [ + ( + True, + {"type": "object", "properties": {"name": {"type": "string"}}}, + ), + (False, None), + ], + ) + def test_get_declaration_response_json_schema( + self, include_response_schema, expected + ): operation = Operation( operationId="getPet", responses={ @@ -352,14 +364,12 @@ def test_get_declaration_includes_response_json_schema(self): method="GET", ), operation=operation, + include_response_schema=include_response_schema, ) declaration = tool._get_declaration() - assert declaration.response_json_schema == { - "type": "object", - "properties": {"name": {"type": "string"}}, - } + assert declaration.response_json_schema == expected class TestRestApiTool: From 776420e4a3352f0764399de34b4658d3e332a1f7 Mon Sep 17 00:00:00 2001 From: Ben Clarke Date: Sun, 8 Nov 2026 12:47:18 +0000 Subject: [PATCH 3/4] fix(tools): describe REST tool success results accurately - Describe the supported success statuses and media types as one schema. - Preserve explicit null constraints and translate nullable and write-only fields. - Return declared non-JSON bodies as text objects for opted-in tools. - Cover the schema and decoded results with OpenAPI tool tests. --- .../adk/tools/openapi_tool/common/common.py | 6 ++ .../openapi_spec_parser/openapi_toolset.py | 5 +- .../openapi_spec_parser/operation_parser.py | 91 ++++++++++++++++++- .../openapi_spec_parser/rest_api_tool.py | 27 ++++-- .../test_operation_parser.py | 59 ++++++++++++ .../openapi_spec_parser/test_rest_api_tool.py | 70 ++++++++++++++ 6 files changed, 241 insertions(+), 17 deletions(-) diff --git a/src/google/adk/tools/openapi_tool/common/common.py b/src/google/adk/tools/openapi_tool/common/common.py index 281f4032771..75f436bb09a 100644 --- a/src/google/adk/tools/openapi_tool/common/common.py +++ b/src/google/adk/tools/openapi_tool/common/common.py @@ -30,6 +30,12 @@ from ..._gemini_schema_util import _to_snake_case +def _is_json_media_type(content_type: str) -> bool: + """Returns whether the media type denotes a JSON representation.""" + media_type = content_type.partition(';')[0].strip().lower() + return media_type == 'application/json' or media_type.endswith('+json') + + def _schema_from_openapi(value: object, *, context: str) -> Schema: """Normalizes a schema-bearing OpenAPI field to a concrete Schema. diff --git a/src/google/adk/tools/openapi_tool/openapi_spec_parser/openapi_toolset.py b/src/google/adk/tools/openapi_tool/openapi_spec_parser/openapi_toolset.py index 58fdee1b74a..a0e01d9f1b8 100644 --- a/src/google/adk/tools/openapi_tool/openapi_spec_parser/openapi_toolset.py +++ b/src/google/adk/tools/openapi_tool/openapi_spec_parser/openapi_toolset.py @@ -174,8 +174,9 @@ def __init__( to allow requests to private networks, localhost, and custom non-DNS transports. include_response_schema: If True, each generated tool's function - declaration includes the operation's 2xx response schema as - ``response_json_schema``, so the model can see what the tool returns. + declaration includes the tool's declared success shapes as + ``response_json_schema`` when known. Explicitly non-JSON responses + are returned as a text object. This adds the schemas to every model request that includes the tools. Defaults to False. """ diff --git a/src/google/adk/tools/openapi_tool/openapi_spec_parser/operation_parser.py b/src/google/adk/tools/openapi_tool/openapi_spec_parser/operation_parser.py index db8cfa5112f..2cb13be55a1 100644 --- a/src/google/adk/tools/openapi_tool/openapi_spec_parser/operation_parser.py +++ b/src/google/adk/tools/openapi_tool/openapi_spec_parser/operation_parser.py @@ -15,6 +15,7 @@ from __future__ import annotations import inspect +import json from textwrap import dedent from typing import Any from typing import cast @@ -32,6 +33,7 @@ from fastapi.openapi.models import Schema from ..._gemini_schema_util import _to_snake_case +from ..common.common import _is_json_media_type from ..common.common import _schema_from_openapi from ..common.common import ApiParameter from ..common.common import PydocHelper @@ -40,6 +42,53 @@ _MAX_TOOL_NAME_LENGTH = 60 +def _normalize_response_schema(schema: dict[str, Any]) -> None: + """Translates OpenAPI schema keywords for use as a JSON response schema.""" + schema_type = schema.get('type') + if ( + schema.pop('nullable', False) is True + and isinstance(schema_type, str) + and schema_type != 'null' + ): + schema['type'] = [schema_type, 'null'] + + properties = schema.get('properties') or {} + if schema.get('required'): + schema['required'] = [ + name + for name in schema['required'] + if not ( + isinstance(properties.get(name), dict) + and properties[name].get('writeOnly') is True + ) + ] + + for key in ('properties', 'patternProperties', 'dependentSchemas', '$defs'): + for child in (schema.get(key) or {}).values(): + if isinstance(child, dict): + _normalize_response_schema(child) + for key in ('allOf', 'anyOf', 'oneOf', 'prefixItems'): + for child in schema.get(key) or (): + if isinstance(child, dict): + _normalize_response_schema(child) + for key in ( + 'items', + 'additionalProperties', + 'contains', + 'propertyNames', + 'not', + 'if', + 'then', + 'else', + 'unevaluatedItems', + 'unevaluatedProperties', + 'contentSchema', + ): + child = schema.get(key) + if isinstance(child, dict): + _normalize_response_schema(child) + + def _required_scheme_name( security: Optional[List[Dict[str, List[str]]]], ) -> str: @@ -356,11 +405,43 @@ def get_json_schema(self) -> Dict[str, Any]: } def get_response_json_schema(self) -> Dict[str, Any] | None: - """Returns the JSON schema of the 2xx response, or None if undeclared.""" - schema = jsonable_encoder( - self._require_return_value()._openapi_schema, exclude_none=True - ) - return schema or None + """Returns the tool's declared success shapes, or None if unknown.""" + schemas: dict[str, dict[str, Any]] = {} + text_response = False + for status, response in (self._operation.responses or {}).items(): + if not status.startswith('2'): + continue + if not isinstance(response, Response): + return None + if not response.content or status in ('204', '205'): + text_response = True + continue + for media_type, media in response.content.items(): + if '*' in media_type: + return None + if not _is_json_media_type(media_type): + text_response = True + continue + if not isinstance(media.schema_, Schema): + return None + schema = media.schema_.model_dump( + mode='json', by_alias=True, exclude_unset=True + ) + _normalize_response_schema(schema) + if not schema: + return None + schemas[json.dumps(schema, sort_keys=True)] = schema + + variants = list(schemas.values()) + if text_response: + variants.append({ + 'type': 'object', + 'properties': {'text': {'type': 'string'}}, + 'required': ['text'], + }) + if len(variants) > 1: + return {'anyOf': variants} + return variants[0] if variants else None def get_signature_parameters(self) -> List[inspect.Parameter]: """Returns a list of inspect.Parameter objects for the function.""" diff --git a/src/google/adk/tools/openapi_tool/openapi_spec_parser/rest_api_tool.py b/src/google/adk/tools/openapi_tool/openapi_spec_parser/rest_api_tool.py index cc7237b9de2..28b310af95f 100644 --- a/src/google/adk/tools/openapi_tool/openapi_spec_parser/rest_api_tool.py +++ b/src/google/adk/tools/openapi_tool/openapi_spec_parser/rest_api_tool.py @@ -59,6 +59,7 @@ from ..auth.auth_helpers import credential_to_param from ..auth.auth_helpers import dict_to_auth_scheme from ..auth.credential_exchangers.auto_auth_credential_exchanger import AutoAuthCredentialExchanger +from ..common.common import _is_json_media_type from ..common.common import ApiParameter from .openapi_spec_parser import OperationEndpoint from .openapi_spec_parser import ParsedOperation @@ -263,9 +264,10 @@ def __init__( to allow requests to private networks, localhost, and custom non-DNS transports. include_response_schema: If True, the function declaration includes - the operation's 2xx response schema as ``response_json_schema``, so - the model can see what the tool returns. This adds the schema to - every model request that includes the tool. Defaults to False. + the tool's declared success shapes as ``response_json_schema`` when + known. Explicitly non-JSON responses are returned as a text object. + This adds the schema to every model request that includes the tool. + Defaults to False. """ # Gemini restrict the length of function name to be less than 64 characters self.name = name[:_MAX_TOOL_NAME_LENGTH] @@ -330,7 +332,7 @@ def from_parsed_operation( to allow requests to private networks, localhost, and custom non-DNS transports. include_response_schema: Whether the function declaration includes the - operation's 2xx response schema. See ``RestApiTool.__init__``. + tool's declared success shapes. See ``RestApiTool.__init__``. Returns: A RestApiTool object. @@ -645,12 +647,13 @@ def _prepare_request_params( @override async def run_async( self, *, args: dict[str, Any], tool_context: Optional[ToolContext] - ) -> Dict[str, Any]: + ) -> Any: + """Runs the REST operation and returns its decoded result.""" return await self.call(args=args, tool_context=tool_context) async def call( self, *, args: dict[str, Any], tool_context: Optional[ToolContext] - ) -> Dict[str, Any]: + ) -> Any: """Executes the REST API call. Args: @@ -660,9 +663,9 @@ async def call( attempt and the guard that bounds the retry. Returns: - The API response as a dictionary. HTTP, authorization, and URL - validation failures are reported as an "error" entry rather than - raised. + The decoded JSON value or a dictionary containing the response text. + HTTP, authorization, and URL validation failures return an "error" + entry. """ # Prepare auth credentials for the API call tool_auth_handler = ToolAuthHandler.from_tool_context( @@ -779,7 +782,11 @@ async def call( # Parse API response try: response.raise_for_status() # Raise HTTPStatusError for bad responses - return response.json() # Try to decode JSON + if self._include_response_schema: + content_type = response.headers.get("content-type") + if content_type and not _is_json_media_type(content_type): + return {"text": response.text} + return response.json() except httpx.HTTPStatusError: error_details = response.text self._logger.warning( diff --git a/tests/unittests/tools/openapi_tool/openapi_spec_parser/test_operation_parser.py b/tests/unittests/tools/openapi_tool/openapi_spec_parser/test_operation_parser.py index 968e8361121..dc29839af13 100644 --- a/tests/unittests/tools/openapi_tool/openapi_spec_parser/test_operation_parser.py +++ b/tests/unittests/tools/openapi_tool/openapi_spec_parser/test_operation_parser.py @@ -478,6 +478,65 @@ def test_get_response_json_schema_without_2xx_schema(): assert parser.get_response_json_schema() is None +def test_get_response_json_schema_normalizes_nested_openapi_fields() -> None: + operation = Operation( + responses={ + '200': Response( + description='Success', + content={ + 'application/json': MediaType( + schema=Schema( + type='array', + items=Schema( + type='object', + required=['name', 'password'], + properties={ + 'name': Schema(type='string', nullable=True), + 'password': Schema( + type='string', writeOnly=True + ), + }, + ), + ) + ) + }, + ) + } + ) + + assert OperationParser(operation).get_response_json_schema() == { + 'type': 'array', + 'items': { + 'type': 'object', + 'required': ['name'], + 'properties': { + 'name': {'type': ['string', 'null']}, + 'password': {'type': 'string', 'writeOnly': True}, + }, + }, + } + + +def test_get_response_json_schema_preserves_null_const() -> None: + operation = Operation( + responses={ + '200': Response( + description='Success', + content={ + 'application/json': MediaType( + schema=Schema(type=['string', 'null'], const=None) + ) + }, + ) + } + ) + + assert OperationParser(operation).get_response_json_schema() == { + 'type': ['string', 'null'], + 'const': None, + } + + def test_get_signature_parameters(sample_operation): """Test get_signature_parameters method.""" parser = OperationParser(sample_operation) diff --git a/tests/unittests/tools/openapi_tool/openapi_spec_parser/test_rest_api_tool.py b/tests/unittests/tools/openapi_tool/openapi_spec_parser/test_rest_api_tool.py index b4a2feed106..be0638cf08b 100644 --- a/tests/unittests/tools/openapi_tool/openapi_spec_parser/test_rest_api_tool.py +++ b/tests/unittests/tools/openapi_tool/openapi_spec_parser/test_rest_api_tool.py @@ -61,6 +61,7 @@ from google.genai.types import FunctionDeclaration from google.genai.types import Schema import httpx +from jsonschema import Draft202012Validator import pytest import requests @@ -371,6 +372,75 @@ def test_get_declaration_response_json_schema( assert declaration.response_json_schema == expected + @patch( + "google.adk.tools.openapi_tool.openapi_spec_parser.rest_api_tool._request" + ) + @pytest.mark.asyncio + async def test_declared_schema_matches_successful_results( + self, mock_request: AsyncMock, sample_endpoint: OperationEndpoint + ) -> None: + operation = Operation( + operationId="getPets", + responses={ + "200": Response( + description="Pets", + content={ + "application/json": MediaType( + schema=OpenAPISchema( + type="array", items={"type": "string"} + ) + ), + "text/plain": MediaType( + schema=OpenAPISchema(type="string") + ), + }, + ), + "202": Response( + description="Job accepted", + content={ + "application/vnd.example+json": MediaType( + schema=OpenAPISchema( + type="object", + properties={"jobId": OpenAPISchema(type="string")}, + required=["jobId"], + ) + ) + }, + ), + "204": Response(description="No content"), + }, + ) + tool = RestApiTool( + name="get_pets", + description="Get pets.", + endpoint=sample_endpoint, + operation=operation, + include_response_schema=True, + ) + validator = Draft202012Validator( + tool._get_declaration().response_json_schema + ) + request = httpx.Request("GET", "https://example.com/pets") + cases = [ + (httpx.Response(200, request=request, json=["Milo"]), ["Milo"]), + (httpx.Response(200, request=request, text="42"), {"text": "42"}), + ( + httpx.Response( + 202, + request=request, + json={"jobId": "job-1"}, + headers={"Content-Type": "application/vnd.example+json"}, + ), + {"jobId": "job-1"}, + ), + (httpx.Response(204, request=request), {"text": ""}), + ] + for reply, expected in cases: + mock_request.return_value = reply + result = await tool.run_async(args={}, tool_context=None) + assert result == expected + validator.validate(result) + class TestRestApiTool: From 68fa32f68e0c54b5e80baca08626d58379c8f134 Mon Sep 17 00:00:00 2001 From: Ben Clarke Date: Mon, 16 Nov 2026 17:41:41 +0000 Subject: [PATCH 4/4] fix(tools): request the JSON that REST tool declarations describe A success response that lists JSON beside another media type, such as `text/csv`, was declared as a union of its JSON shape and a text object, because httpx sends `Accept: */*` and the server may pick either. Declare such a response by its JSON alone and send an `Accept` header listing the media types the declaration describes, keeping parameters such as `version=2` that can select the shape. - Only tools created with `include_response_schema=True` change. - Operations whose every listed success media type is declared, or whose response schema is unknown, send no `Accept`. --- .../openapi_spec_parser/openapi_toolset.py | 4 +- .../openapi_spec_parser/operation_parser.py | 33 ++++++++++- .../openapi_spec_parser/rest_api_tool.py | 9 +++ .../test_operation_parser.py | 59 +++++++++++++++++++ .../openapi_spec_parser/test_rest_api_tool.py | 48 ++++++++++++++- 5 files changed, 150 insertions(+), 3 deletions(-) diff --git a/src/google/adk/tools/openapi_tool/openapi_spec_parser/openapi_toolset.py b/src/google/adk/tools/openapi_tool/openapi_spec_parser/openapi_toolset.py index a0e01d9f1b8..a930e8ef2a2 100644 --- a/src/google/adk/tools/openapi_tool/openapi_spec_parser/openapi_toolset.py +++ b/src/google/adk/tools/openapi_tool/openapi_spec_parser/openapi_toolset.py @@ -176,7 +176,9 @@ def __init__( include_response_schema: If True, each generated tool's function declaration includes the tool's declared success shapes as ``response_json_schema`` when known. Explicitly non-JSON responses - are returned as a text object. + are returned as a text object. A response that lists JSON beside other + media types is declared by its JSON alone, which the tool requests + with an ``Accept`` header. This adds the schemas to every model request that includes the tools. Defaults to False. """ diff --git a/src/google/adk/tools/openapi_tool/openapi_spec_parser/operation_parser.py b/src/google/adk/tools/openapi_tool/openapi_spec_parser/operation_parser.py index 2cb13be55a1..f1a4a7cd3e4 100644 --- a/src/google/adk/tools/openapi_tool/openapi_spec_parser/operation_parser.py +++ b/src/google/adk/tools/openapi_tool/openapi_spec_parser/operation_parser.py @@ -24,6 +24,7 @@ from typing import Optional from fastapi.encoders import jsonable_encoder +from fastapi.openapi.models import MediaType from fastapi.openapi.models import Operation from fastapi.openapi.models import Parameter from fastapi.openapi.models import ParameterInType @@ -89,6 +90,12 @@ def _normalize_response_schema(schema: dict[str, Any]) -> None: _normalize_response_schema(child) +def _requested_media_types(content: dict[str, MediaType]) -> list[str]: + """Returns the media types a tool asks for: the JSON ones, if any.""" + json_types = [t for t in content if _is_json_media_type(t)] + return json_types or list(content) + + def _required_scheme_name( security: Optional[List[Dict[str, List[str]]]], ) -> str: @@ -416,7 +423,8 @@ def get_response_json_schema(self) -> Dict[str, Any] | None: if not response.content or status in ('204', '205'): text_response = True continue - for media_type, media in response.content.items(): + for media_type in _requested_media_types(response.content): + media = response.content[media_type] if '*' in media_type: return None if not _is_json_media_type(media_type): @@ -443,6 +451,29 @@ def get_response_json_schema(self) -> Dict[str, Any] | None: return {'anyOf': variants} return variants[0] if variants else None + def get_accept_header(self) -> str | None: + """Returns an Accept value for the declared success shapes. + + A success response that lists JSON beside other media types is declared by + its JSON alone, so the tool must ask for it. Returns None when the response + schema is unknown or every listed media type is declared. + """ + if self.get_response_json_schema() is None: + return None + listed: list[str] = [] + requested: list[str] = [] + for status, response in (self._operation.responses or {}).items(): + if ( + status.startswith('2') + and isinstance(response, Response) + and response.content + ): + listed.extend(response.content) + requested.extend(_requested_media_types(response.content)) + if len(requested) == len(listed): + return None + return ', '.join(dict.fromkeys(requested)) + def get_signature_parameters(self) -> List[inspect.Parameter]: """Returns a list of inspect.Parameter objects for the function.""" return [ diff --git a/src/google/adk/tools/openapi_tool/openapi_spec_parser/rest_api_tool.py b/src/google/adk/tools/openapi_tool/openapi_spec_parser/rest_api_tool.py index 28b310af95f..8ed41842769 100644 --- a/src/google/adk/tools/openapi_tool/openapi_spec_parser/rest_api_tool.py +++ b/src/google/adk/tools/openapi_tool/openapi_spec_parser/rest_api_tool.py @@ -266,6 +266,8 @@ def __init__( include_response_schema: If True, the function declaration includes the tool's declared success shapes as ``response_json_schema`` when known. Explicitly non-JSON responses are returned as a text object. + A response that lists JSON beside other media types is declared by + its JSON alone, which the tool requests with an ``Accept`` header. This adds the schema to every model request that includes the tool. Defaults to False. """ @@ -495,6 +497,13 @@ def _prepare_request_params( user_agent = f"google-adk/{adk_version} (tool: {self.name})" header_params["User-Agent"] = user_agent + if self._include_response_schema: + # Without it, httpx sends `*/*` and the server may pick a media type + # that the declaration leaves out. + accept = self._operation_parser.get_accept_header() + if accept: + header_params["Accept"] = accept + if ( self.auth_credential and self.auth_credential.http diff --git a/tests/unittests/tools/openapi_tool/openapi_spec_parser/test_operation_parser.py b/tests/unittests/tools/openapi_tool/openapi_spec_parser/test_operation_parser.py index dc29839af13..f31c530af88 100644 --- a/tests/unittests/tools/openapi_tool/openapi_spec_parser/test_operation_parser.py +++ b/tests/unittests/tools/openapi_tool/openapi_spec_parser/test_operation_parser.py @@ -537,6 +537,65 @@ def test_get_response_json_schema_preserves_null_const() -> None: } +def test_get_response_json_schema_declares_json_beside_other_media_types() -> ( + None +): + operation = Operation( + responses={ + '200': Response( + description='Success', + content={ + 'text/csv': MediaType(schema=Schema(type='string')), + 'application/json': MediaType(schema=Schema(type='integer')), + '*/*': MediaType(schema=Schema(type='string')), + }, + ) + } + ) + + assert OperationParser(operation).get_response_json_schema() == { + 'type': 'integer' + } + + +_JSON = MediaType(schema=Schema(type='object')) +_TEXT = MediaType(schema=Schema(type='string')) + + +@pytest.mark.parametrize( + 'contents, expected', + [ + ( + {'200': {'application/json; version=2': _JSON, 'text/csv': _TEXT}}, + 'application/json; version=2', + ), + ( + { + '200': {'application/json': _JSON, 'text/csv': _TEXT}, + '201': {'application/hal+json': _JSON}, + '202': {'text/plain': _TEXT}, + }, + 'application/json, application/hal+json, text/plain', + ), + ({'200': {'application/json': _JSON}}, None), + ({'200': {'text/csv': _TEXT}}, None), + # Without a JSON schema nothing is declared, so nothing is requested. + ({'200': {'application/json': MediaType(), 'text/csv': _TEXT}}, None), + ], +) +def test_get_accept_header( + contents: dict[str, dict[str, MediaType]], expected: str | None +) -> None: + operation = Operation( + responses={ + status: Response(description='Success', content=content) + for status, content in contents.items() + } + ) + + assert OperationParser(operation).get_accept_header() == expected + + def test_get_signature_parameters(sample_operation): """Test get_signature_parameters method.""" parser = OperationParser(sample_operation) diff --git a/tests/unittests/tools/openapi_tool/openapi_spec_parser/test_rest_api_tool.py b/tests/unittests/tools/openapi_tool/openapi_spec_parser/test_rest_api_tool.py index be0638cf08b..9729ef737f7 100644 --- a/tests/unittests/tools/openapi_tool/openapi_spec_parser/test_rest_api_tool.py +++ b/tests/unittests/tools/openapi_tool/openapi_spec_parser/test_rest_api_tool.py @@ -372,6 +372,43 @@ def test_get_declaration_response_json_schema( assert declaration.response_json_schema == expected + @pytest.mark.parametrize( + "include_response_schema,expected", + [(True, "application/json"), (False, None)], + ) + def test_prepare_request_params_asks_for_declared_json( + self, include_response_schema, expected + ): + operation = Operation( + operationId="getPet", + responses={ + "200": Response( + description="The pet.", + content={ + "application/json": MediaType( + schema=OpenAPISchema(type="object") + ), + "text/csv": MediaType(schema=OpenAPISchema(type="string")), + }, + ) + }, + ) + tool = RestApiTool( + name="get_pet", + description="Get a pet.", + endpoint=OperationEndpoint( + base_url="https://petstore.example.com", + path="/pets/1", + method="GET", + ), + operation=operation, + include_response_schema=include_response_schema, + ) + + request_params = tool._prepare_request_params([], {}) + + assert request_params["headers"].get("Accept") == expected + @patch( "google.adk.tools.openapi_tool.openapi_spec_parser.rest_api_tool._request" ) @@ -395,6 +432,12 @@ async def test_declared_schema_matches_successful_results( ), }, ), + "201": Response( + description="Created", + content={ + "text/plain": MediaType(schema=OpenAPISchema(type="string")) + }, + ), "202": Response( description="Job accepted", content={ @@ -423,7 +466,7 @@ async def test_declared_schema_matches_successful_results( request = httpx.Request("GET", "https://example.com/pets") cases = [ (httpx.Response(200, request=request, json=["Milo"]), ["Milo"]), - (httpx.Response(200, request=request, text="42"), {"text": "42"}), + (httpx.Response(201, request=request, text="42"), {"text": "42"}), ( httpx.Response( 202, @@ -440,6 +483,9 @@ async def test_declared_schema_matches_successful_results( result = await tool.run_async(args={}, tool_context=None) assert result == expected validator.validate(result) + assert mock_request.call_args.kwargs["headers"]["Accept"] == ( + "application/json, text/plain, application/vnd.example+json" + ) class TestRestApiTool: