Pydantic AI · Chapter 13 of 23

Your first graph

By the end of this chapter you can say what a graph is and when it beats an agent, write nodes as dataclasses whose run returns the next node or End, share a state between them, build and run a graph with pydantic-graph, draw its Mermaid diagram, and read what the diagram is drawn from. Build it in your browser: a real editor and terminal, AI that explains, and tests that tell you when it works.

  • Part: Graphs
  • 4 tasks
  • Python
  • In the all labs plan

The first 2 chapters of Pydantic AI are free. This one comes with the all labs plan.

Why you need this

Sneha has watched the crop cover agent for a week. It works, but she cannot sign off on it. A claim must be checked in the same order every time: does the farmer have cover, is the cause one the cover pays for, is it within 72 hours, and only then is it filed. With an agent, the model decides which tool to call next. Most days it decides well; she cannot promise an auditor that it always will, and every step costs a request.

Kedar agrees: when you already know the steps and the order, you do not need a model to choose them. You need a workflow your code runs, step by step, that anyone can draw on a whiteboard. Pydantic AI's team ships one, pydantic-graph, and Pydantic AI runs on it: every agent run you have made is a small graph of nodes (the user's prompt, a model request, the tool calls) going round until the end. Now you build your own.

What you build: 4 tasks

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

  1. Task 1

    two_nodes.py: a two-node graph

    With pydantic-graph, make the state, a dataclass Lot with farmer_id, crop, quintals (an int), mandi (text, empty to start) and rate (an int, 0 to start), and two nodes.

    Rate looks up the farmer's nearest mandi with khetbazaar.get_farmer and today's modal price of the crop there with khetbazaar.mandi_price, stores the mandi and the rate (the modal price less the 2% fee, rounded) in the state, and goes to Quote. Quote ends the run with the line 12 quintals of onion at Lasalgaon: ₹1999 a quintal, ₹23988 in all (made from the state: quintals, crop, mandi, rate, and rate times quintals; those numbers are only an example).

    Build the graph as graph at the top level of the file. Under if __name__ == "__main__":, run it for F1002's 12 quintals of onion and print its output. The check also runs your graph on other lots.

  2. Task 2

    claim_flow.py: a claim workflow

    The state, a dataclass Claim: farmer_id, crop, cause, acres (a float) and loss_date (text). Three nodes. CheckCover: if the farmer's crop_cover (khetbazaar.get_farmer) is false, end with Rejected: no crop cover; otherwise go to CheckCause. CheckCause: if the cause is not in khetbazaar.COVERED, end with Rejected: CAUSE is not covered (policy 3.5), with the claim's cause; otherwise go to File. File: call khetbazaar.file_claim with the claim's fields; if its ok is false, end with Rejected: and its reason, otherwise with Filed CLAIM_ID: ₹AMOUNT, STATUS from its claim_id, amount and status (Filed KC4019: ₹36000, reported).

    Build the graph as graph at the top level. Under if __name__ == "__main__":, run these claims, in order, and print each output: F1011, onion, hail, 1.0 acres, 2026-10-22; F1001, grape, drought, 1.5 acres, 2026-10-21; F1018, onion, hail, 1.5 acres, 2026-10-19; F1021, onion, unseasonal rain, 1.5 acres, 2026-10-22. The check runs your graph on other claims too.

  3. Task 3

    diagram.py: the Mermaid diagram

    Import the graph from claim_flow.py and print its Mermaid diagram, with the title KhetBazaar claims and the direction LR. Then save the same diagram to claim_flow.md in this folder, inside a Markdown fence marked mermaid: a line of three backticks and the word mermaid, the diagram, and a line of three backticks.

    The check also reads the diagram: each of CheckCover and CheckCause must have a way to the end and to its next node, so keep task 2's return hints true.

  4. Task 4 · interview question

    Interview: graph_or_agent.py, graph or agent?

    Make an agent for openai-chat:lab-chat with the tool khetbazaar.file_claim and the instructions You are KhetBazaar's crop cover assistant. Today is 2026-10-23. Use the tools. and run it on Drought damaged 2 acres of my grapes on 22 Oct. I am F1004.

    Then run claim_flow.py's graph on the same claim: F1004, grape, drought, 2 acres, 2026-10-22.

    Print two lines: Agent, the agent run's request count in brackets with the word requests, a colon and a space, then its output (Agent (2 requests): ...); then Graph (0 requests): and the graph's output.

    The interviewer will ask: who decides the next step in each? When would you choose a graph, and when an agent?

What you will learn

  • State: the data every step reads and changes.
  • Nodes: dataclasses whose run returns the next node, or End.
  • GraphBuilder: putting the nodes together, and running the graph.
  • The diagram: Mermaid, drawn from your return type hints.
  • Graph or agent: who decides the next step.

More in Graphs

Build "Your first graph" 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.

The first 2 chapters of Pydantic AI are free. This one comes with the all labs plan.