How to ensure LLMAgent(..., output_schema=...) always returns valid output?

[lenixbyte]

I'm Using:

LLMAgent(
name="MyAgent",
instructions="...",
output_schema=MySchema
)

If the LLM produces invalid structure or missing fields, Pydantic validation fails and the frontend receives an unpredictable response.

What is the best practice to guarantee that final outputs always match output_schema?

Specifically:

Where should schema enforcement + fallback happen?

How to emit a safe final event when validation fails?

Should intermediate events also follow a minimal schema?

Looking for official ADK guidance or production patterns to keep the contract stable when the model deviates.

[adk-bot]

Response from ADK Answering Agent (experimental, answer may be inaccurate)

TLDR: The most robust method to guarantee schema validation is to use a multi-agent "Generator-Critic" pattern, where one agent generates the output and a second agent validates it. For simpler cases, you can use an after_model_callback to inspect the output and handle failures.

---

That's an excellent question about ensuring output reliability. Here are some recommended patterns and practices based on ADK's capabilities:

1. The Generator-Critic Pattern (Most Robust)

The cleanest and most powerful way to enforce output structure is by using a multi-agent pattern where different agents have different responsibilities. [1] You can orchestrate this using a SequentialAgent:

• Agent 1 (Generator): An LlmAgent responsible for generating the response based on your instructions and attempting to fit the output_schema.
• Agent 2 (Critic/Validator): A second agent (either a custom BaseAgent or another LlmAgent) that takes the output from the Generator. Its sole job is to validate the data against your Pydantic schema.
  • If validation passes, it finalizes the turn and returns the valid output.
  • If validation fails, it can either return a safe, default error response or send feedback to the Generator to retry. You could wrap this interaction in a LoopAgent for a set number of retries.

2. Using Callbacks for Validation (Simpler)

For less complex scenarios, you can use callbacks as a lightweight way to inspect and intercept the agent's process. [2]

• after_model_callback: This callback is triggered after the LLM call is complete but before the final event is yielded. You can inspect the llm_response here, try to parse it with your Pydantic schema, and if it fails, you can return a new LlmResponse object containing a safe fallback message. This prevents the invalid response from propagating.

  def validate_output(resource, llm_response, **kwargs):
      try:
          MySchema.parse_obj(llm_response.final_output)
          return llm_response  # It's valid, do nothing
      except ValidationError as e:
          # Validation failed, return a safe response
          return LlmResponse(
              final_output={"error": "Invalid output from model", "details": str(e)}
          )
  
  agent = LlmAgent(
      ...,
      after_model_callback=validate_output
  )

3. How to Emit a Safe Final Event

When validation fails in a callback or a Critic agent, you can emit a custom, safe event. This ensures your frontend always receives a predictable structure.

# Inside an agent or callback
if validation_failed:
    yield Event(
        author=self.name,
        content={"status": "error", "message": "Output validation failed."}
    )

4. Schema for Intermediate Events

You asked if intermediate events should follow a schema. While not strictly enforced by the framework for all events, it is a strong best practice. [3] ADK's own components for logging and analytics rely on a consistent event structure. Defining a schema for your intermediate events will make your application much easier to debug, extend, and maintain.

Finally, it's worth noting that ADK now supports using output_schema and tools together. When you do this, ADK automatically creates a special tool for the model to call with the final structured output, which can also help improve reliability. [4]

[1] https://google.github.io/adk-docs/agents/multi-agents/
[2] https://google.github.io/adk-docs/callbacks/design-patterns-and-best-practices/
[3] https://google.github.io/adk-docs/events/
[4] https://github.com/google/adk-python/blob/main/contributing/samples/output_schema_with_tools/README.md