Structured output allows you to define a specific JSON schema that your AI responses must conform to, making it easier to integrate AI-generated content with your application logic.

​
Defining Response Schemas

You can define the response schema in your agent class using the $responseSchema property or add the structuredOutput method in your agent class for defining more complex schemas.

protected $responseSchema = [
    'name' => 'weather_info',
    'schema' => [
        'type' => 'object',
        'properties' => [
            'temperature' => [
                'type' => 'number',
                'description' => 'Temperature in degrees'
            ],
        ],
        'required' => ['temperature'],
        'additionalProperties' => false,
    ],
    'strict' => true,
];

Pay attention to the required, additionalProperties, and strict properties. It’s recommended by OpenAI to set these when defining schemas to get exactly the structure you need.

For complex schemas, it’s recommended to use the structuredOutput() method instead of the property, as it provides more flexibility and can include dynamic logic.

Using trait with structuredOutput() method is a good practice to avoid code duplication and make your code more maintainable.

​
Schema Configuration Options

The schema follows the JSON Schema specification and supports all its features:

Basic Types

string, number, boolean, array, object

Required Properties

Specify which fields must be present

Nested Structures

Complex objects and arrays

Property Descriptions

Guide the AI on what each field should contain

​
Using Structured Output

When structured output is defined, the agent’s response will be automatically formatted and returned as an array according to the schema:

// Example response when using the complex schema above
$response = $agent->respond("What's the weather like today?");

// Returns:
[
    'temperature' => 25.5,
    'conditions' => 'sunny',
    'forecast' => [
        ['day' => 'tomorrow', 'temp' => 28],
        ['day' => 'Wednesday', 'temp' => 24]
    ]
]

​
Runtime Schema Management

The schema can be accessed or modified using the structuredOutput() method at runtime:

// Get current schema
$schema = $agent->structuredOutput();

// Check if structured output is enabled
if ($agent->structuredOutput()) {
    // Handle structured response
}

​
Example Use Cases

In most of the cases you need to include all properties in required, skip only properties which are optional in ANY case.

​
Best Practices

Do make your schema as specific as possible

Do include descriptive property descriptions to guide the AI

Do set additionalProperties to false when you want to restrict the output to only the defined properties

Don’t create overly complex (Deeply Nested) schemas that the AI might struggle to fulfill

Don’t forget to set the required property for fields that must be present