Pydantic AI · Chapter 2 of 23

Typed output

By the end of this chapter you can ask an agent for a Pydantic object instead of text, explain how Pydantic AI gets one from a model that only writes text (an output tool the model calls), shape the object with Literal, Field descriptions and optional fields, and choose between the three output modes: tool, native and prompted. Build it in your browser: a real editor and terminal, AI that explains, and tests that tell you when it works.

  • Part: Your first agents
  • 4 tasks
  • Python
  • Free chapter

Free with a Google or GitHub sign-in, like the first 2 chapters of every lab.

Why you need this

Ganesh forwards a farmer's message: "20 quintal tamatar tayar ahe, Pimpalgaon la vikaycha" (20 quintals of tomato are ready, I want to sell at Pimpalgaon). Sneha books the collection in KhetBazaar's system, which needs three fields: the crop, the quantity in quintals and the mandi. A reply like "Sure, we can take your tomatoes!" is friendly, but her system cannot book a sentence.

In chapter 1 an agent's output was always text. Text is for a farmer to read. Code needs fields with types: a crop that is one of four, a quantity that is a number, a mandi that may be missing. This chapter makes the agent return exactly that.

The lesson

Text is hard to use

The obvious first try is to ask for the fields in the instructions:

agent = Agent(
    "openai-chat:lab-chat",
    instructions="Reply with the crop, the quantity and the mandi.",
)
result = agent.run_sync("20 quintal tamatar tayar ahe, Pimpalgaon la vikaycha")
print(result.output)
Happy to help. Thanks for your message. How can KhetBazaar help with your farm today?

Nothing in a text reply makes the model write what you asked, in the form you asked. Another run might say "Tomato, 20 qtl, Pimpalgaon", or "twenty quintals". Every form needs its own parsing code, and the day the reply has no number at all, that code crashes, or worse, books 0 quintals.

output_type: ask for an object

You already describe data with Pydantic models. Give the agent one as its output_type:

from typing import Literal

from pydantic import BaseModel, Field
from pydantic_ai import Agent


class Sale(BaseModel):
    crop: Literal["onion", "grape", "tomato", "pomegranate"]
    quantity: float = Field(description="Quintals to sell")
    mandi: str | None = None


agent = Agent("openai-chat:lab-chat", output_type=Sale)
result = agent.run_sync("20 quintal tamatar tayar ahe, Pimpalgaon la vikaycha")
print(type(result.output).__name__)
print(result.output)
print(result.output.quantity * 100, "kg")
Sale
crop='tomato' quantity=20.0 mandi='Pimpalgaon'
2000.0 kg

result.output is now a Sale, already checked by Pydantic: the crop is one of the four, the quantity a float you can do arithmetic with. The farmer wrote "tamatar"; the object says tomato, because that is the only spelling the field allows. Your editor knows the type too, so result.output.quantity autocompletes.

Inside: an output tool

A model only writes text, so how does an object come back? lab requests 1 shows what Pydantic AI sent (trimmed):

"messages": [{"role": "user", "content": "20 quintal tamatar tayar ahe, Pimpalgaon la vikaycha"}],
"tool_choice": "required",
"tools": [{"type": "function", "function": {
  "name": "final_result",
  "description": "The final response which ends this conversation",
  "parameters": {"properties": {
      "crop": {"enum": ["onion", "grape", "tomato", "pomegranate"], "type": "string"},
      "quantity": {"description": "Quintals to sell", "type": "number"},
      "mandi": {"default": null, "anyOf": [{"type": "string"}, {"type": "null"}]}},
    "required": ["crop", "quantity"], "type": "object"}}}]

Pydantic AI turned Sale into a JSON schema and offered it to the model as a tool named final_result. A tool is a function the model may ask your code to call (chapter 3 is all about them); models are trained to fill a tool's arguments to match its schema. "tool_choice": "required" says the model must call a tool, so it cannot answer in prose. The reply:

"tool_calls": [{"type": "function", "function": {
  "name": "final_result",
  "arguments": "{\"crop\":\"tomato\",\"quantity\":20,\"mandi\":\"Pimpalgaon\"}"}}]

The model wrote the arguments as JSON text. Pydantic AI validated that text against Sale and that became result.output. Nothing runs: the "tool" exists only to carry the object. result.all_messages() shows the same run from Pydantic AI's side:

[UserPromptPart(content='20 quintal tamatar tayar ahe, Pimpalgaon la vikaycha', ...)]
[ToolCallPart(tool_name='final_result', args='{"crop":"tomato","quantity":20,"mandi":"Pimpalgaon"}', ...)]
[ToolReturnPart(tool_name='final_result', content='Final result processed.', ...)]

Shaping the object

Everything in the model class reaches the model through the schema, so each piece is an instruction:

  • Literal[...] becomes an enum: the model must pick one of those exact strings, and Pydantic rejects anything else. Use it for crops, causes, labels: any field with a fixed set of answers.
  • Field(description=...) becomes the property's description. The model reads it, so say what the field means and its unit: "Quintals to sell", not just a number.
  • An optional field, str | None = None, is left out of required. When the farmer does not name a mandi, the model can leave it out and you get None, instead of a mandi it made up to fill a required field.

A docstring on the class travels too: it becomes the output tool's description, in place of "The final response which ends this conversation".

Three output modes

The output tool is Pydantic AI's default, and works with any model that can call tools. There are two other ways to ask for the same Sale:

from pydantic_ai import NativeOutput, PromptedOutput

native = Agent("openai-chat:lab-chat", output_type=NativeOutput(Sale))
prompted = Agent("openai-chat:lab-chat", output_type=PromptedOutput(Sale))

Both returned crop='tomato' quantity=20.0 mandi='Pimpalgaon'. What they sent differs (trimmed):

NativeOutput:   "response_format": {"type": "json_schema",
                  "json_schema": {"name": "Sale", "schema": {...}, "strict": false}}
PromptedOutput: {"role": "system", "content": "Always respond with a JSON object
                  that's compatible with this schema: {...}"}
                "response_format": {"type": "json_object"}
  • Tool output (the default): the schema as the final_result tool.
  • Native output: the schema in response_format, the provider's own structured output feature. The reply is plain JSON text, no tool call.
  • Prompted output: the schema written into the instructions, for models with neither feature. The weakest promise: the model is only asked.

The prompted reply here was {"to":"Pimpalgaon","crop":"tomato", "quantity":"20","mandi":"Pimpalgaon"}: an extra key and a number written as text. Pydantic dropped the extra key and turned "20" into 20.0. Whatever the mode, Pydantic validates the reply; chapter 5 shows what happens when the reply does not fit.

Your turn

Four tasks. Task 1 turns a sell message into a SellRequest; task 2 asks for a claim report in native mode and prints it as JSON; task 3 labels Ganesh's 29 messages with a Literal and scores the model against his labels. Task 4 is an interview question: ask for a quantity as text and as a typed output, and be ready to say why the typed one is the one to build on.

What you build: 4 tasks

Each task has tests. You write the code in the lab's editor and press Check.

  1. Task 1

    sell_request.py: a sell request as an object

    Sneha's booking system needs a farmer's sell message as fields, not prose. Write a Pydantic model SellRequest with three fields: crop, which can only be onion, grape, tomato or pomegranate; quantity, a float, with a Field description that says it is the number of quintals; and graded, a bool that is None when the farmer does not say.

    Make an agent for openai-chat:lab-chat whose output type is SellRequest, run it on the farmer's message exactly:

    kanda vikaycha ahe 25 quintal, ungraded

    and print one line from the output's fields, written as: crop, quantity quintals, graded: graded (for example: tomato, 12.0 quintals, graded: True).

  2. Task 2

    claim_report.py: a claim report in native mode

    Write a Pydantic model ClaimReport with four fields, each with a Field description: crop (onion, grape, tomato or pomegranate), cause (hail, unseasonal rain, flood or pest attack), acres (a float, None when the farmer does not say) and farmer_id (a string, None when not given).

    Make an agent for openai-chat:lab-chat that asks for a ClaimReport in native mode (the model's own JSON output, not an output tool), run it on:

    unseasonal rain damaged 2 acre onion, claim karaycha ahe

    and print the report as JSON on one line, with the Pydantic model's own JSON method.

  3. Task 3

    classify.py: label 29 messages and score them

    Ganesh labelled 29 real WhatsApp messages in /workspace/data/messages.jsonl (one JSON object per line, with id, text and label). Write a Pydantic model Label with one field, intent, that can only be one of the nine labels: price, sell, weather, pest, order, claim, payment, complaint, praise.

    Make one agent for openai-chat:lab-chat with Label as its output type and run it on every message's text, in the file's order. For each message whose intent is not its label, print: the id, a colon and a space, the intent, a comma, then labelled and the label (for example: W031: price, labelled sell). Then print the score as: Score: right/total.

  4. Task 4 · interview question

    Interview: typed_or_text.py, typed or text

    Run the farmer's message pomegranate 8 quintal hai, pickup ho jayega? through two agents for openai-chat:lab-chat. The first has no output type and the instructions: Reply with only the number of quintals. The second has an output type Lot, a Pydantic model with one float field, quintals.

    Print two lines: Text: and the first agent's output, then Typed: and the second output's quintals.

    The interviewer will ask why a typed output beats asking for text and parsing it.

What you will learn

  • output_type: give the agent a Pydantic model; the run's output is an instance of it.
  • The output tool: how Pydantic AI gets an object out of a model.
  • Literal, Field and optional fields: the shape the model must fill.
  • Three output modes: tool, native and prompted.

More in Your first agents

Build "Typed output" yourself

KhetBazaar, a Nashik agritech startup, answers farmers on WhatsApp from a bike. You build its farmer assistant. A real editor and terminal in your browser, AI that explains, and a Check that says when it works.

Free with a Google or GitHub sign-in, like the first 2 chapters of every lab.