> ## Documentation Index
> Fetch the complete documentation index at: https://docs.erdo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Structured agent results

> Ask an agent for a JSON result that matches a schema you supply.

When a script or another system reads an agent's answer, pass `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

| Surface | How to pass the schema |
| - | - |
| CLI | `erdo agent ask` and `erdo agent send` take `--output-schema`, as inline JSON or `@file.json` |
| REST | `output_schema` in the body of `POST /v1/ask` and `POST /v1/threads/{thread_id}/send` |
| MCP | `output_schema` on the ask and send-message tools |

```bash theme={null}
erdo agent ask "How many leads arrived this week, by source?" \
  --output-schema @lead-counts.schema.json
```

## 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 allow `null` in its type.
* References to other documents (`$ref` to a URL) aren't supported.

## Reading the result

The result is in `output`. 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 with
`error_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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.