Prompting best practices when using structured output (output_schema)

[sigott]

Just wondering if there are any prompting guidelines when using output_schema. Is it still useful to use few shot prompting (give examples of output JSON) when using output_schema or is that unnecessary. My rudimentary testing seems to suggest few shot prompting isn't needed but wouldn't mind hearing from others.

[adk-bot]

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

TLDR: Your intuition is correct—output_schema is powerful and often removes the need for few-shot examples for structure alone. However, providing examples can still be very useful for guiding the semantic content and handling complex logic, especially now that output_schema can be used in combination with other tools.

---

Hello! That's a great question, and your initial testing is on the right track.

Here’s a more detailed breakdown of the best practices:

1. output_schema is often sufficient: For many use cases, defining a Pydantic BaseModel in output_schema is enough. The model is highly capable of understanding the desired structure and generating a valid JSON response that conforms to your schema. This is because output_schema acts as a strong constraint on the model's final output. [1]

2. When to use Few-Shot Examples: While not always necessary for the structure, few-shot examples remain a valuable tool for guiding the content and logic of the output. Consider using them when:

   • The logic is complex: If the mapping from input to the structured output is nuanced or requires specific reasoning, examples can demonstrate this logic more clearly than instructions alone.
   • Specific formatting is required: If you need a field to have a specific format that isn't captured by the data type (e.g., a string that must be a formatted date, or a name in ALL_CAPS), providing an example is an excellent way to show the model what you want.
   • Guiding a sequence of actions: A recent ADK update allows output_schema to be used in conjunction with other tools. In this scenario, few-shot examples can demonstrate a full workflow: the user asks a question, the agent uses a tool to find information, and then it uses the special set_model_response tool to format the final answer according to your schema. [2]

3. Alternative: Detailed Instructions: Don't forget the power of well-written instructions. Instead of (or in addition to) few-shot examples, you can provide a detailed description of the desired output, explaining what each field represents and how to populate it. This can be very effective for guiding the model's behavior. [3]

In summary, you can rely on output_schema for structural enforcement, but keep few-shot examples in your toolkit to refine the model's output for more complex or specific requirements.

[1] https://google.github.io/adk-docs/agents/llm-agents/
[2] https://github.com/google/adk-python/blob/main/contributing/samples/output_schema_with_tools/README.md
[3] https://github.com/google/adk-python/blob/main/contributing/samples/multi_agent_seq_config/sub_agents/code_reviewer_agent.yaml

[adityapandey216]

@adk-bot what if im using tools but need output_schema as well?

[adk-bot]

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

TLDR: While output_schema ensures the output structure, providing few-shot examples is still a recommended best practice to guide the model on the content and ensure reliable and accurate structured output.

---

That's a great question!

While output_schema is a powerful feature for enforcing a specific JSON output structure, it's still beneficial to provide clear instructions and examples in your prompts. Here's a breakdown:

• output_schema for Structure: The primary role of output_schema is to guarantee that the LLM's final response is a JSON string that conforms to your predefined schema. [1] It does this by setting the response_mime_type to application/json and providing the schema to the model.

• Instructions for Content: Even with a defined schema, the model needs to understand what to put into the JSON fields. Your prompt's instructions are crucial for guiding the model's reasoning and content generation. For example, the structured_capital_agent example in the documentation explicitly instructs the model to respond only with a JSON object in a specific format, even though it's also using output_schema. [1]

• Few-shot Examples for Precision: Providing few-shot examples in your prompt is a valuable practice that can significantly improve the model's performance, especially for complex outputs. The ADK has built-in support for including few-shot examples. For instance, the a2ui integration demonstrates generating a system prompt that includes both the JSON schema and few-shot examples. [2] There are also utility files in the ADK codebase, like example_util.py, that are designed to help build few-shot examples, which indicates that this is a recognized and supported pattern. [3]

So, while your initial tests might suggest that few-shot prompting isn't strictly necessary for simpler cases, it's a good habit to adopt for more complex and production-level scenarios to ensure the model consistently produces the desired output.

---

[1] https://google.github.io/adk-docs/agents/llm-agents/
[2] https://google.github.io/adk-docs/integrations/a2ui/
[3] https://github.com/google/adk-python/blob/main/src/google/adk/examples/example_util.py