Return Structured Output

Enable Structured Output when downstream blocks need a JSON object with predictable fields instead of free-form model text. The AI Agent uses the configured JSON Schema as the response contract and sends failures through its Error port.

Choose free-form or structured output

Structured output improves predictability, but it does not make model-generated values trustworthy. Validate business rules such as email addresses, identifiers, monetary values, and permissions separately before causing side effects.

Define the JSON Schema

This example requires a subject, message, and constrained priority:

Copy{
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "subject": {
      "type": "string"
    },
    "message": {
      "type": "string"
    },
    "priority": {
      "type": "string",
      "enum": ["normal", "high"]
    }
  },
  "required": ["subject", "message", "priority"]
}

Use Format JSON to normalize indentation. Use Validate schema to check that the editor contains valid JSON and a compilable JSON Schema. Builders performs this editor-side schema validation with Ajv; see the Ajv JSON Schema reference and the JSON Schema getting-started guide.

Validating the schema does not call the model and does not prove that a future provider response will succeed. It only verifies the schema definition used by the block.

Make the contract strict enough

• Set the root type explicitly, usually to object.
• Put every expected field in properties.
• Add fields that must always exist to required.
• Use additionalProperties: false when unexpected fields should be rejected.
• Use enum for small, closed sets of allowed values.
• Keep the schema focused; deeply nested or oversized schemas consume context and are harder for models to satisfy.

For a private AI agent backed by OpenAI, also review the provider's Structured Outputs guide. Other providers can support different schema subsets and model capabilities.

Align the prompt with the schema

The prompt should describe the task and refer to the schema rather than reproducing a competing response shape. For example:

CopyReturn only the structured response requested by the schema.

Do not request Markdown, commentary, or a code fence when Structured Output is enabled. Keep field descriptions and allowed values unambiguous, especially when the schema uses enums.

Use the result downstream

Connect Out only to blocks that should run after the structured response succeeds. After a successful test, inspect the AI block output and use the Designer's template suggestions to select the exact returned fields instead of guessing their runtime path.

Connect Error to a separate branch. Provider errors, empty responses, timeouts, and responses that cannot satisfy the configured structured contract must not continue into blocks that assume the object exists.

CopyAI Agent Out   -> transform, store, send, or render the structured result
AI Agent Error -> log details, notify an operator, or apply a controlled fallback

Diagnose failures

Test the success and error branches independently before publishing. Never hide an invalid structured response behind a default object unless the fallback is explicit and safe for every downstream action.

Next steps

• AI Agent Overview
• Choose a Model Source and Control Usage
• Write Prompts and Tune Generation
• Validate Incoming Endpoint Data
• Test Runs in the Designer
• Read Block Logs and Output