Skip to content

Output Schema consistently ignored by LLM Agent with tools #3969

Closed

Description

@mcbortolozzo

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

  1. added
    core[Component] This issue is related to the core interface and implementation
    on Dec 18, 2025
  2. added theissue type on Dec 18, 2025
  3. klateefa commented on Dec 18, 2025

    @klateefa

    @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.

  4. GiulioCMSanto commented on Dec 19, 2025

    @GiulioCMSanto

    @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.

    Hey @klateefa , thank you so much for the reply. The suggestion is something like the following?

    from google.adk.agents import Agent, SequentialAgent
    from pydantic import BaseModel
    
    class Out(BaseModel):
        ...
    
    first_agent= Agent(
        name="agent_that_calls_tools",
        model=...,
        tools=[...],
        instruction="...",
        output_key="draft",
    )
    
    second_agent= Agent(
        name="agent_that_formats_output",
        model=...,
        instruction="...",
        output_schema=Out,
    )
    
    agent= SequentialAgent(sub_agents=[first_agent, second_agent])

    Besides this workaround, do you know if an oficial solution is already being considered? Because this would add an extra LLM call.

  5. klateefa commented on Dec 23, 2025

    @klateefa

    @GiulioCMSanto Yes, this does add an extra LLM call.At the moment, there is no official or planned solution to enforce output_schema when tools are used in the same agent. This is a known limitation of the current ADK agent flow
    Thanks!

  6. AlejandroBlanco2001 commented on Jan 1, 2026

    @AlejandroBlanco2001

    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.

  7. alan-anzenna commented on Jan 6, 2026

    @alan-anzenna

    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.

  8. added
    answered[Status] This issue has been answered by the maintainer
    on Feb 3, 2026
  9. self-assigned this
    on Feb 23, 2026
  10. added a commit that references this issue on Mar 2, 2026
    89df5fc
  11. added a commit that references this issue on Aug 11, 2026
    661427f
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Labels

answered[Status] This issue has been answered by the maintainercore[Component] This issue is related to the core interface and implementation

Type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions