Repository navigation
feat: type stub return values and escape docstrings - #28
Merged
Merged
Conversation
- Build each stub's return type from `response_json_schema`: objects become `TypedDict` classes in the stub module, arrays `list[...]`, the rest `Any` - Let a tool with exactly one required parameter take it positionally - Escape backslashes and `"""` in generated docstrings so regex patterns no longer raise `SyntaxWarning` Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013TYQ7CMpjWGGd4WWTt2Czk
- Hand code an MCP tool's `structuredContent` when it declares an `outputSchema`, after callbacks have seen ADK's result - Read MCP return types from the tool's `outputSchema`, so they no longer need ADK's JSON-schema feature flag - Give identical shapes one `TypedDict` across a module's tools - Name classes after their `$defs` key or `title`, else the property holding them; qualify by parent, then number, on a clash - Resolve `$ref` into `$defs`/`definitions`, including recursive refs Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013TYQ7CMpjWGGd4WWTt2Czk
- Name it `<Tool>Response` rather than reusing another tool's identical shape, which named it after whichever tool sorted first Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013TYQ7CMpjWGGd4WWTt2Czk
- Only an untitled top-level object stays per tool; array items are entities like any nested object Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013TYQ7CMpjWGGd4WWTt2Czk
Contributor
Author
One interaction with google/adk-python#8033 when its response-schema option is enabled. A declared |
- Save an MCP tool's `structuredContent` as its artifact, so reloading it gives what the call returned. The size threshold measures that value too. - Key shared `$ref` classes by the definitions they reach, so two tools whose `$defs` differ no longer share one class. - Render `prefixItems` arrays as `list[...]`, since JSON arrays reach code as lists. - Pass `mcp_results` the unwrapped tool, avoiding a circular import. - Drop `large_result_threshold` from the dispatcher test; its fixture fits the default. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Contributor
Author
|
Addressed in f553235:
On google/adk-python#8033: that link is to the older head |
benclarkeio
pushed a commit
that referenced
this pull request
Nov 8, 2026
- Take main's stubs, dispatcher and MCP result handling from #28 and #27 - Keep this branch's per-module catalog rendering Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_013TYQ7CocX3w8EpGvN7Heip
This was referenced Nov 13, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
First of two stacked PRs. This one changes the generated stubs and what MCP calls return; the catalog follows in #29.
Changes
response_json_schema, or from an MCP tool'soutputSchema, which is read from the tool directly so it no longer needs ADK'sJSON_SCHEMA_FOR_FUNC_DECLflag. Stubs no longer all return-> Any.TypedDictclasses. Arrays becomelist[...],prefixItemsincluded, since JSON arrays reach code as lists. Open maps becomedict[str, ...]. Unions and nullables are kept. Anything unrepresentable becomesAny, and so does a tool with no schema.$refinto$defs/definitionsis resolved, including recursive references.$refclass is shared only when the definitions it reaches match, so two tools whose$defsdiffer don't share one.<Tool>Response. Otherwise a tool could return a class named after a different tool.$defskey ortitle, else the property holding it (Guest,BookingsItem).requiredkeys, the class istotal=False. Otherwise only the keys it leaves out getNotRequired[...].NotRequiredis imported underTYPE_CHECKING, so stubs still import on the sandbox's 3.10 floor.first-name,class) use the functionalTypedDict(...)syntax.McpToolreturns the wholeCallToolResult. When the tool declares anoutputSchema, code now getsstructuredContentalone, so the result matches the declared type.structuredContentto match theoutputSchema, and thecontentblock is meant to be a serialised copy of it.outputSchemaare unchanged.structuredContenttoo, so reloading it gives what the call returned. The large-result threshold measures that value.load_artifact("x", version=2)works. All other parameters stay keyword-only._format_docstringnow escapes backslashes and""", so docstrings containingpatternregexes no longer raiseSyntaxWarning.Tests
McpToolwith anoutputSchemaproduces the expectedTypedDicts without the feature flag, and its stub runs.$refclasses split when the tools'$defsdiffer; a clash qualified by the parent's name;$defsandtitlenaming with a recursive$ref; top-level types kept per tool while top-level array items are shared; names avoiding imports and tool names.structuredContentfor an MCP tool with anoutputSchema, through the result wrapper, while callbacks see the full result. The saved artifact holdsstructuredContent. Without anoutputSchemathe full result is returned.prefixItemsarray return type is alist.ruff,mypyandpytestall pass (233 tests).🤖 Generated with Claude Code
https://claude.ai/code/session_013TYQ7CMpjWGGd4WWTt2Czk