Skip to main content

Typed output

Pass a type as output_model_schema. Read the instance from result.structured_output.
Any type Pydantic can validate works: a model, list[Model], Literal['yes', 'no']. For a JSON-schema dict, wrap it in pydantic_ai.StructuredDict(schema). Anything else raises a TypeError in Agent(...).

The result

run() returns an AgentHistoryList.
Methods kept from 0.x: final_result(), structured_output, is_done(), is_successful(), errors(), has_errors(), number_of_steps(), total_duration_seconds(). print(result) omits messages, which can be large.

Status and success

A run that reaches max_steps or the timeout gets one forced delivery turn. If the agent delivers, status is still 'completed', and success is False when it reports the task unfinished. 'max_steps' and 'timeout' mean nothing was delivered; read result.partial.
  • is_done() is True when status == 'completed'.
  • is_successful() is the agent’s verdict: True, False, or None when it gave none. It is the agent’s own claim; verify important actions independently.
  • errors() lists only the error that ended the run. Cell errors the agent recovered from are in messages.
For the 0.x default (no verdict counts as success), use result.is_done() and result.success is not False.

Judge

By default, after a run that took a step, the same model judges the task and trace at low reasoning effort. result.judgement holds success, failure_reason, description, prompt_injection_detected, bot_block_or_captcha_detected and gotchas: up to five short lessons grounded in what happened, also on successful runs. This is separate from the agent’s own result.success; it does not change the run’s status.
  • Agent(task, judge_context='the answer is 42') supplies your criteria, which the judge puts first. The 0.x names use_judge and ground_truth still work.
  • The judge sees up to 120k characters of trace, with secrets redacted, and the last 4 distinct images available, including a final-page capture when possible. Images are sent as they are, without redaction. use_vision=False sends text only.
  • A model that rejects images gets one text-only retry. A judge failure logs a warning and leaves result.judgement as None.
  • Judge tokens and cost are included in result.usage and result.cost_usd. Judging and the final screenshot are outside the run(timeout=...) loop budget.
  • Agent(task, judge=False) sends no judge request.

Removed from 0.x

There are no per-step actions in 1.0, so history, urls(), screenshots(), action_names(), model_thoughts(), extracted_content(), save_to_file(), load_from_file() and similar raise an AttributeError that points to the replacement. Use final_result(), structured_output, messages, partial and the files in agent.workspace. is_judged() and is_validated() also raise; read result.judgement instead.