Skip to content
Tutorials Center
My learning

Topics

Lesson 9 of 39 ยท Agent Concepts and Loops

Structured Outputs and Parsing Model Responses

Make model output safe to use in code: ask for JSON, extract it from messy text, validate fields and types, and send validation errors back for repair.

An agent loop turns model text into program actions, and that boundary is where many bugs live. A person can ignore an extra sentence or a missing comma; json.loads cannot. This lesson shows how to ask for structured output, how to extract it from imperfect text, how to validate it against what your code expects, and how to feed errors back so the model can repair its own answer.

Many providers now offer a "structured output" or "JSON mode" that constrains the model to a schema. Use it when available, since it removes most formatting failures. You still need validation: the JSON can be well-formed but wrong, for example a negative quantity or a name that is not a known tool.

Ask clearly, then verify

A reliable prompt states the exact format, gives one example, and says what to do when information is missing:

TEXT
Reply with ONLY a JSON object, no other text:
{"action": "search" | "finish", "query": string | null, "answer": string | null}
If you do not know, use action "search".

The stand-in model below sometimes wraps JSON in prose or code fences, which real models do too. A robust parser must cope.

Step 1: extract the JSON

Python Extract JSON from messy model text

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Step 2: validate the shape

Parsed JSON is just dictionaries and lists. Check that the keys exist, the types are right and the values are in the allowed set. Return a list of problems in plain language, because you will often send them straight back to the model.

Python Validate an action with readable errors

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

In production code you would usually describe the shape once, with a schema (see tool schemas) or a validation library such as Pydantic, rather than hand-writing checks. The principle is identical: never trust, always check.

Step 3: repair loop

When validation fails, do not crash. Send the problems back and ask again, a bounded number of times. Models are good at fixing a specific complaint.

Python Stand-in: a parse, validate, repair loop

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Three attempts is a common cap. If repairs keep failing, treat it as a failed step: log the raw text, stop or fall back, instead of looping endlessly (see stop conditions).

Practical tips

  • Keep schemas small. Flat objects with few fields fail less often than deep nesting.
  • Use enums for choices and validate against them.
  • Ask for reasoning in a separate field ("thought") before the action, rather than mixing prose into the JSON.
  • Log the raw text whenever parsing fails. It is the only way to learn how the model really behaves.
  • Do not eval model output. Parse with a JSON parser only.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why validate parsed JSON even when it is well-formed?

    Syntax correctness says nothing about meaning. Your code needs fields and values it can safely act on.
  2. 2. The model wraps its JSON in a markdown code fence. What should your parser do?

    Robust extraction handles common wrappers so small formatting habits do not break the loop.
  3. 3. What is the best use of validation error messages?

    Specific complaints let the model fix exactly what was wrong in the next attempt.
  4. 4. Why cap the number of repair attempts?

    A bound turns a persistent failure into a handled error instead of unlimited cost.

Summary

  • Ask for a precise format with an example; use provider structured-output modes when available.
  • Extract JSON defensively from fences and surrounding prose.
  • Validate keys, types and allowed values; produce readable problem lists.
  • Repair loop: send problems back, retry a few times, then fail cleanly.
  • Never eval model output; log raw text when parsing fails.

Next: What Are Tools? Function Calling Basics