output_schema
with the question. The agent does its work as usual, then returns its final
result as JSON that matches the schema.
Where it works
Schema rules
The schema is checked before the agent starts, so a schema that can’t be used costs nothing.- Every object sets
"additionalProperties": false. - Every property is listed in
required. For a value that may be missing, make the field required and allownullin its type. - References to other documents (
$refto a URL) aren’t supported.
Reading the result
The result is inoutput. With a schema it is the JSON value; without one it is
the agent’s text answer. Status, run ID, model and usage sit beside it.
An async request returns at once with an invocation_id. Read the finished run
from GET /v1/runs/{run_id}, which also returns output, or let the CLI wait
for you. The older answer field and the run’s text output still work while
clients move to output.
When the result doesn’t match
If the agent’s final result doesn’t match the schema, the run fails witherror_type: "output_schema_mismatch" and an error saying which part didn’t
match. Nothing is retried automatically, and you are charged for the work the
agent did. A run waiting for an approval or for your answer to a question is
paused, not finished, and has no output yet.
