Skip to main content
Structured output gives every successful objective a machine-readable result that follows an agent-level JSON Schema. The conversation remains available in the timeline, while objective.output carries the value your application consumes. This guide builds a small refund-decision agent that returns:

Define the schema

Open Agents and create a new agent, or open an existing draft agent and select ActionsEdit. Under Structured output:
  1. Turn on Enable structured output.
  2. Enter this value in Output schema:
Structured output settings enabled with the refund-decision JSON Schema in the Output schema field

Structured output enabled with a refund-decision schema

You can also paste a representative JSON value:
The dashboard converts a pasted value into JSON Schema and marks every example key as required. Paste a schema directly when optional fields, enums, nested constraints, or additionalProperties need explicit control. Save the agent. Create a variation with a model and a prompt such as:
Publish the agent after it has at least one valid variation.

Run an objective

Open Objectives, select New Objective, and choose the published agent. Use this First User Message:
Select Create Objective. The agent processes the task, then Cadenya runs structured extraction with the selected variation’s model and the snapshotted schema. The objective reaches Finalized when extraction succeeds. In Timeline, the Finalized event displays Structured Output with a Copy action.
Objective Finalized event showing an approved refund object under Structured Output and a Copy action

The Finalized event with machine-readable output

The same object appears on the retrieved objective:

Read output from the event stream

finalized.output is narrowed by the objective-event union:
The finalized webhook carries the same value at data.objectiveEvent.data.finalized.output.

Configure the same schema from code

The schema belongs to the agent, not its variations:
Add a variation and publish the agent before creating an objective. The agents SDK guide contains that complete lifecycle.

Failure and cost behavior

Structured extraction is a separate model call after the agent finishes its work:
  • It uses the selected variation’s model.
  • It is billed as another model call.
  • Cadenya attempts extraction up to three times.
  • The schema is snapshotted when the objective is created.
If extraction cannot produce a matching object, the objective can finalize without output. Treat absence as an extraction failure in application code even when the terminal state is STATE_FINALIZED.

Run your first objective

Inspect the timeline, details, continuations, and feedback in the dashboard.

Stream objective events

Consume the typed finalized payload without polling.

Objectives from the SDK

Dispatch, continue, cancel, and score objectives.

Objective webhooks

React to finalized and error events from a durable delivery.