Response Schema Support

The response_schema parameter allows you to request structured, machine-readable responses from the Statement Agent API. Instead of receiving only free-form text, you can define the expected output format and have the agent return data that conforms to your schema.

This is particularly useful for:

• Building automated workflows
• Populating dashboards and reports
• Extracting structured business insights
• Integrating agent responses into applications and APIs
• Reducing post-processing and parsing requirements

When a valid schema is provided, the agent attempts to generate output that matches the specified structure. If successful, the parsed result is returned in the choices[].structured field of the response.

Supported Schema Fields

The Statement API supports a subset of JSON Schema concepts designed for common structured output use cases.

Supported Types

The following schema types are supported:

Object Schema Requirements

Object schemas must define a non-empty properties object.

Example

{
  "type": "object",
  "properties": {
    "summary": {
      "type": "string"
    },
    "confidence": {
      "type": "number"
    }
  }
}

Validation Rules

• properties must be present.
• properties cannot be empty.
• Every property listed in required must also exist in properties.

Valid Example

{
  "type": "object",
  "properties": {
    "summary": {
      "type": "string"
    }
  },
  "required": ["summary"]
}

Invalid Example

{
  "type": "object",
  "properties": {
    "summary": {
      "type": "string"
    }
  },
  "required": ["summary", "risk_level"]
}

The example above is invalid because risk_level is listed as required but is not defined in properties.

Array Schema Requirements

Array schemas must define an items field describing the structure of each array element.

Example

{
  "type": "array",
  "items": {
    "type": "string"
  }
}

Array of Objects Example

{
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "metric": {
        "type": "string"
      },
      "value": {
        "type": "number"
      }
    }
  }
}

Enum Support

Use enum to restrict a field to a predefined set of values.

Example

{
  "type": "string",
  "enum": [
    "low",
    "medium",
    "high"
  ]
}

The generated response will attempt to use only one of the specified values.

Default Values

The default field can be used to provide a fallback value for a schema property.

The default value must match the property's declared type.

Example

{
  "type": "string",
  "default": "unknown"
}

Invalid Example

{
  "type": "number",
  "default": "unknown"
}

The example above is invalid because the default value is a string while the declared type is number.

Example Response Schema

The following schema requests a structured business analysis response:

{
  "type": "object",
  "properties": {
    "summary": {
      "type": "string",
      "description": "Brief business summary"
    },
    "revenue_growth": {
      "type": "number"
    },
    "risk_level": {
      "type": "string",
      "enum": [
        "low",
        "medium",
        "high"
      ]
    }
  },
  "required": [
    "summary",
    "revenue_growth",
    "risk_level"
  ]
}

Validation Rules

Before processing a request, the API validates the supplied schema.

A schema is considered valid when:

• A supported type is specified.
• Object schemas include a non-empty properties field.
• Array schemas include an items definition.
• All entries in required exist in properties.
• Any default value matches the declared field type.
• Any enum definition contains at least one valid value.

Requests containing invalid schemas will be rejected before agent execution begins.

Notes

• The schema format is intentionally lightweight and optimized for structured AI responses.
• Schema validation occurs before the request is routed to an agent.
• Structured output is returned in choices[].structured only when the generated response successfully conforms to the provided schema.
• The original generated content is always available in choices[].message.content.
• Complex or deeply nested schemas may reduce generation reliability. For best results, keep schemas concise and focused on the data you need.