Repository navigation
Description
Describe the bug
It seems like the current approach for supporting LLMAgents that have both an output_schema and a set of tools is not working properly. Often an Agent ignores the defined output format and return a text-based message directly instead.
The issue gets aggravated once we attempt to use both output_schema and output_key fields along with tools, since the output_key field has a mandatory pydantic schema validation, causing the issue above to break the flow mid-execution. What happens here is that since the Agent ignores the schema, the output key step fails during the validation step. This seems to be another issue, but since it's the one that is "easier" to see, I've attached the reproduction to it below. However, it seems to me that the root cause here is that the output schema is not being properly followed.
To Reproduce
Setting output_schema, tools and output_key at the same time reproduces the validation issue. However, even when no output_key is used the Agent often ignores the output_schema, if tools are defined for it.
Agent(
name="task_planner",
model=create_litellm_model(model_name, api_base),
instruction=(
"You are a task planner. Return a JSON object with title, steps (array), "
"and estimated_time (integer). Return ONLY valid JSON, nothing else."
),
tools=[dummy_tool],
output_schema=TaskPlan,
output_key="task_plan",
)Python version: 3.12.9
adk-python version: 1.21.0
Expected behavior
When setting the output_schema field, agents should always generate an output according to the schema provided.
Additional Details
I understand that there's a degree of prompting and different agent composition patterns that could improve this issue and minimize its occurrence. However, output schema seems like a "hard" guardrail that I'd expect to be enforced internally within an Agent, without relying on having to add extra components around it to guarantee proper adherence to it.
Below the error trace of a more concrete example using the pattern above:
Traceback (most recent call last):
File "/Users/marcelo.bortolozzo/Documents/adk-bug-reproduction/src/task_planner/main.py", line 107, in test_bug_reproduction
async for event in response:
File "/Users/marcelo.bortolozzo/Documents/adk-bug-reproduction/.venv/lib/python3.12/site-packages/google/adk/runners.py", line 505, in run_async
async for event in agen:
File "/Users/marcelo.bortolozzo/Documents/adk-bug-reproduction/.venv/lib/python3.12/site-packages/google/adk/runners.py", line 493, in _run_with_trace
async for event in agen:
File "/Users/marcelo.bortolozzo/Documents/adk-bug-reproduction/.venv/lib/python3.12/site-packages/google/adk/runners.py", line 722, in _exec_with_plugin
async for event in agen:
File "/Users/marcelo.bortolozzo/Documents/adk-bug-reproduction/.venv/lib/python3.12/site-packages/google/adk/runners.py", line 482, in execute
async for event in agen:
File "/Users/marcelo.bortolozzo/Documents/adk-bug-reproduction/.venv/lib/python3.12/site-packages/google/adk/agents/base_agent.py", line 294, in run_async
async for event in agen:
File "/Users/marcelo.bortolozzo/Documents/adk-bug-reproduction/.venv/lib/python3.12/site-packages/google/adk/agents/loop_agent.py", line 100, in _run_async_impl
async for event in agen:
File "/Users/marcelo.bortolozzo/Documents/adk-bug-reproduction/.venv/lib/python3.12/site-packages/google/adk/agents/base_agent.py", line 294, in run_async
async for event in agen:
File "/Users/marcelo.bortolozzo/Documents/adk-bug-reproduction/.venv/lib/python3.12/site-packages/google/adk/agents/llm_agent.py", line 461, in _run_async_impl
self.__maybe_save_output_to_state(event)
File "/Users/marcelo.bortolozzo/Documents/adk-bug-reproduction/.venv/lib/python3.12/site-packages/google/adk/agents/llm_agent.py", line 810, in __maybe_save_output_to_state
result = self.output_schema.model_validate_json(result).model_dump(
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
File "/Users/marcelo.bortolozzo/Documents/adk-bug-reproduction/.venv/lib/python3.12/site-packages/pydantic/main.py", line 766, in model_validate_json
return cls.__pydantic_validator__.validate_json(
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
pydantic_core._pydantic_core.ValidationError: 1 validation error for TaskPlan
Invalid JSON: expected value at line 1 column 1 [type=json_invalid, input_value="To proceed, I first need...o help brainstorm them.", input_type=str]
Activity
klateefa commentedon Dec 18, 2025
@mcbortolozzo Thanks for reporting this issue!
In google-adk 1.21.0, output_schema isn’t enforced once tools are added. After tool calls the model can return plain text, and the schema only gets checked later when saving state.
That’s why tools + output_schema often ignores the schema, and adding output_key makes it fail with a pydantic error. This isn’t a prompt issue, just how the agent flow works right now.
Workaround: don’t mix tools and output_schema in the same agent. Use one agent for tools and another agent with no tools to format the final output.
Thank you.
GiulioCMSanto commentedon Dec 19, 2025
Hey @klateefa , thank you so much for the reply. The suggestion is something like the following?
Besides this workaround, do you know if an oficial solution is already being considered? Because this would add an extra LLM call.
klateefa commentedon Dec 23, 2025
@GiulioCMSanto Yes, this does add an extra LLM call.At the moment, there is no official or planned solution to enforce
output_schemawhen tools are used in the same agent. This is a known limitation of the current ADK agent flowThanks!
AlejandroBlanco2001 commentedon Jan 1, 2026
Hi @klateefa, do you think it would make sense to add a note in the documentation about this? For example, in this section: https://google.github.io/adk-docs/agents/llm-agents/#fine-tuning-llm-generation-generate_content_config.
I ran into the same issue a few months ago and only realized what was happening after some testing and trial and error, happy to make the PR.
alan-anzenna commentedon Jan 6, 2026
If this is a known limitation, can there a be a runtime check for this? Documentation would also be great, but something that makes it completely obvious what's going on if you do it would also be helpful.
Several folks on my team also just wasted a good amount of time on this.
feat: Enable output schema with tools for LiteLlm models
feat: Enable output schema with tools for LiteLlm models