Structured subagent output

DataMind Oda can ask a subagent to answer with a result that matches a fixed shape, called a schema, instead of plain text; the subagent reports it with the structured_output tool, and the run carries the recorded answer back. This page covers the call, what counts as the answer, and the cases that end without one.

How the answer is recorded

• When a delegated run carries an output schema, the subagent receives the structured_output tool. How delegation itself works is in Delegating work to subagents.
• The subagent is told to call the tool exactly once, when its answer is complete, and that only the tool call counts as its result. Closing with plain text is not the answer.
• A recorded call is acknowledged with Structured output recorded., and the subagent's turn ends there: the run makes no further requests.
• The recorded answer travels with the run's result, so the delegating side receives a result it can check against the schema instead of free text.
• Each structured run carries its own schema; two structured runs at the same time do not share it.

Report it once

• Exactly one call is recorded per run, and that call is the answer.
• A later call is refused: Error: structured output already recorded: the run is complete, so <tool> is not executed.
• Calls before the recorded one still run, so the subagent can use its other tools while it works.
• A call whose arguments do not match the schema is refused with an invalid-arguments result, and the subagent can correct the call and try again in the same turn.

What the schema may contain

• The schema can use only the supported subset of schema features.
• A schema outside that subset is refused before the run starts, with unsupported JSON schema. Nothing starts for it: the refusal happens before the subagent is created.
• A schema annotation that cannot be represented as lossless JSON data is refused the same way.

When a run ends without the answer

• A run that finishes cleanly without reporting settles as an error. Its closing text is not accepted as the answer, and the run is not asked again.
• A run that was cancelled instead reads as cancelled, not as an error.
• A run that fails for its own reason keeps its own failure.

The failures a subagent run can meet are collected in Subagent failures and diagnostics.

Questions, answered

How does a subagent return a structured answer?

It calls structured_output once with the finished answer. The call is acknowledged with Structured output recorded., the subagent's turn ends there, and the run's result carries the recorded answer. Plain closing text is not the answer.

What happens if the subagent calls structured_output twice?

The second call is refused with Error: structured output already recorded: the run is complete, so <tool> is not executed. The run already has its answer, and the first recorded call stands.

Can the subagent use other tools before it reports?

Yes. Calls before the recorded one still run, so it can use its tools before it reports. Only its recorded call ends the turn.

Why was the schema refused with unsupported JSON schema?

The schema asked for a feature outside the supported subset, so the run was refused before any subagent started. Reduce the schema to the supported subset and delegate again.

What happens if the subagent finishes without reporting?

The run settles as an error. A clean turn that ends without the recorded call is not accepted as a plain-text answer, and the run is not prompted again to report.

The run was cancelled and did not report either. Why is that not an error?

A cancelled run reads as cancelled, not as an error. The error is kept for a clean finish without the report, so a cancellation is never misread as a failure to answer.

What if the call's arguments do not match the schema?

The call is refused with an invalid-arguments result, and the subagent can correct the call and try again within the same turn.

Does every subagent run return a structured answer?

No. Only runs that carry an output schema. A delegation without one does not give the subagent the tool, and a target that cannot carry a schema refuses the request before the run starts. See Choosing and enabling a delegation backend.

What does the delegating side receive from a structured run?

The recorded answer, carried with the run's result, so the delegating side has a result it can check against the schema instead of free text. How a result reaches your chat depends on the run's shape; see Delegating work to subagents and Background subagents and job collection.