Pydantic AI & Instructor Best Practices

Ten practices for schema design that keeps validated agent output both strict and useful. Use this list when reviewing Pydantic models, agent output_type choices, Instructor extractors, and typed tools.

How to Use This List

Walk A when designing models; B when wiring agents and retries; C when operating in production.
Tick an item only when it is true in code or docs, not as a hope.
Pair with Why Structured Output Matters More as Agents Get Autonomous for the rationale.
Re-check after schema changes, model swaps, or new tool side effects.

A - Schema Design

1. Model the decision, not the essay. Include only fields a machine will route on, store, or display as structured UI.
2. Prefer required fields + enums over optional free-text bags. Optional everything is a schema that never fails and never helps.
3. Write Field descriptions as operator instructions. Closed sets, formats, and examples belong in the schema the model sees.
4. Keep nested models shallow and named. Deep anonymous blobs raise validation thrash; named sub-models clarify intent.
5. Share one Pydantic model across Instructor and Pydantic AI when both exist. One contract prevents extractor/agent drift.

B - Agent Wiring and Retries

6. Separate tool schemas from final output_type. Tools intermediate; final output terminates with an explicit success or typed failure.
7. Cap retries and make validator errors actionable. max_retries / output retry budgets stay small; error text teaches the repair.
8. Provide escape-hatch output types. NeedMoreInfo, Rejected, or Escalate beat infinite reask on impossible inputs.
9. Type tools with hints, docstrings, and least privilege. Validate args before side effects; split read vs write tools.
10. Choose the thin client vs full agent deliberately. Instructor for extraction; Pydantic AI when you need loops, deps, and stream UI adapters.

C - Operate and Evolve

11. Measure first-try pass rate and mean retries. Spikes after prompt or model changes are regressions, not noise.
12. Version schemas like APIs. Add optional fields first; never silently rename fields that other services consume.
13. Log validation failures with field paths (redacted). Feed chronic offenders into golden-set evals.
14. Guard streaming partials before side effects. Commit only on final validated objects.
15. Revisit structure when autonomy rises. New tools, handoffs, or unsupervised runs need new contracts at each boundary.

Applying These Practices in Order

Design (1-5): cheapest place to prevent production pain.
Wiring (6-10): launch blockers for agents that act on outputs.
Operate (11-15): keeps schemas honest under real traffic and model churn.

FAQs

Why more than ten checkboxes?

Items 1-10 are the core schema and wiring practices. Items 11-15 extend them into operations so the list stays useful after launch.

What is the single highest-leverage practice?

Required fields for anything you will act on, plus enums for closed sets. Most silent failures come from optional mush.

How strict is too strict?

If mean retries stay high on good inputs, loosen optionality, split models, or improve descriptions before raising retry caps.

Should every chat feature use structured output?

No. Structure the surfaces that software consumes: tools, handoffs, forms, and commits. Pure human-readable answers can stay text.

How do these practices map to Instructor only projects?

1-5 and 7, 11-13 apply directly. 6, 8-10, 14-15 matter as soon as you grow into tools or agents.

Where should schema reviews happen?

In PR review next to agent code, with a short golden-set run for first-try pass rate when fields change.

How do we handle provider differences?

Keep schemas provider-agnostic. Pin model-specific output modes (native vs tool vs prompted) in config, not in the domain model.

What belongs in instructions vs schema?

Policy and role go in instructions. Shape, types, and closed values go in schema. Duplicating closed sets only in prose causes drift.

How do we stop mega-schema growth?

Require a named consumer for every new field. No consumer, no field. Nested "misc" dicts are rejected in review.

When should we introduce typed failure models?

As soon as retries would otherwise loop on missing user data or policy blocks. Host apps need a clean branch, not an exception soup.

Do structured outputs replace evals?

No. They reduce parse failures. Evals still catch wrong-but-valid content and bad tool choices.

How does this list interact with security reviews?

Least-privilege tools, validation before side effects, and no secrets in error/retry text are security controls as much as quality controls.

Why Structured Output Matters More as Agents Get Autonomous - rationale
Pydantic AI & Instructor Basics - hands-on start
Defining Agent Output Schemas with Pydantic Models - schema recipe
Using Instructor for Schema-Constrained Outputs Across Providers - extraction path
Handling Validation Failures and Retry Loops Gracefully - retry strategy
Type-Safe Tool Definitions with Pydantic AI - tool contracts
Pydantic AI's Native Vercel AI SDK Data Stream Support - streaming UI bridge

Stack versions: Pins from the category manifest (verify at build): OpenRouter (~315+ models, July 2026 pricing/fees); LangGraph 1.0+; CrewAI 1.14+; Microsoft Agent Framework 1.0; Vercel AI SDK 6; Pydantic AI (latest); LlamaIndex (latest); OpenAI Agents SDK (latest + MCP); MCP (Linux Foundation governance); A2A (HTTP+SSE+JSON-RPC 2.0); Solana @solana/web3.js + @solana/spl-token.

Pydantic AI & Instructor Best Practices

How to Use This List

Walk A when designing models; B when wiring agents and retries; C when operating in production.
Tick an item only when it is true in code or docs, not as a hope.
Pair with Why Structured Output Matters More as Agents Get Autonomous for the rationale.
Re-check after schema changes, model swaps, or new tool side effects.

A - Schema Design

1. Model the decision, not the essay. Include only fields a machine will route on, store, or display as structured UI.
2. Prefer required fields + enums over optional free-text bags. Optional everything is a schema that never fails and never helps.
3. Write Field descriptions as operator instructions. Closed sets, formats, and examples belong in the schema the model sees.
4. Keep nested models shallow and named. Deep anonymous blobs raise validation thrash; named sub-models clarify intent.
5. Share one Pydantic model across Instructor and Pydantic AI when both exist. One contract prevents extractor/agent drift.

B - Agent Wiring and Retries

6. Separate tool schemas from final output_type. Tools intermediate; final output terminates with an explicit success or typed failure.
7. Cap retries and make validator errors actionable. max_retries / output retry budgets stay small; error text teaches the repair.
8. Provide escape-hatch output types. NeedMoreInfo, Rejected, or Escalate beat infinite reask on impossible inputs.
9. Type tools with hints, docstrings, and least privilege. Validate args before side effects; split read vs write tools.
10. Choose the thin client vs full agent deliberately. Instructor for extraction; Pydantic AI when you need loops, deps, and stream UI adapters.

C - Operate and Evolve

11. Measure first-try pass rate and mean retries. Spikes after prompt or model changes are regressions, not noise.
12. Version schemas like APIs. Add optional fields first; never silently rename fields that other services consume.
13. Log validation failures with field paths (redacted). Feed chronic offenders into golden-set evals.
14. Guard streaming partials before side effects. Commit only on final validated objects.
15. Revisit structure when autonomy rises. New tools, handoffs, or unsupervised runs need new contracts at each boundary.

Applying These Practices in Order

Design (1-5): cheapest place to prevent production pain.
Wiring (6-10): launch blockers for agents that act on outputs.
Operate (11-15): keeps schemas honest under real traffic and model churn.

FAQs

Why more than ten checkboxes?

Items 1-10 are the core schema and wiring practices. Items 11-15 extend them into operations so the list stays useful after launch.

What is the single highest-leverage practice?

Required fields for anything you will act on, plus enums for closed sets. Most silent failures come from optional mush.

How strict is too strict?

If mean retries stay high on good inputs, loosen optionality, split models, or improve descriptions before raising retry caps.

Should every chat feature use structured output?

No. Structure the surfaces that software consumes: tools, handoffs, forms, and commits. Pure human-readable answers can stay text.

How do these practices map to Instructor only projects?

1-5 and 7, 11-13 apply directly. 6, 8-10, 14-15 matter as soon as you grow into tools or agents.

Where should schema reviews happen?

In PR review next to agent code, with a short golden-set run for first-try pass rate when fields change.

How do we handle provider differences?

Keep schemas provider-agnostic. Pin model-specific output modes (native vs tool vs prompted) in config, not in the domain model.

What belongs in instructions vs schema?

Policy and role go in instructions. Shape, types, and closed values go in schema. Duplicating closed sets only in prose causes drift.

How do we stop mega-schema growth?

Require a named consumer for every new field. No consumer, no field. Nested "misc" dicts are rejected in review.

When should we introduce typed failure models?

As soon as retries would otherwise loop on missing user data or policy blocks. Host apps need a clean branch, not an exception soup.

Do structured outputs replace evals?

No. They reduce parse failures. Evals still catch wrong-but-valid content and bad tool choices.

How does this list interact with security reviews?

Least-privilege tools, validation before side effects, and no secrets in error/retry text are security controls as much as quality controls.

Why Structured Output Matters More as Agents Get Autonomous - rationale
Pydantic AI & Instructor Basics - hands-on start
Defining Agent Output Schemas with Pydantic Models - schema recipe
Using Instructor for Schema-Constrained Outputs Across Providers - extraction path
Handling Validation Failures and Retry Loops Gracefully - retry strategy
Type-Safe Tool Definitions with Pydantic AI - tool contracts
Pydantic AI's Native Vercel AI SDK Data Stream Support - streaming UI bridge

Stack versions: Pins from the category manifest (verify at build): OpenRouter (~315+ models, July 2026 pricing/fees); LangGraph 1.0+; CrewAI 1.14+; Microsoft Agent Framework 1.0; Vercel AI SDK 6; Pydantic AI (latest); LlamaIndex (latest); OpenAI Agents SDK (latest + MCP); MCP (Linux Foundation governance); A2A (HTTP+SSE+JSON-RPC 2.0); Solana @solana/web3.js + @solana/spl-token.

Pydantic AI & Instructor Best Practices

Search Documentation

Pydantic AI & Instructor Best Practices