Structured Output - Official LarAgent Documentation

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,
];

public function structuredOutput()
{
    return [
        'name' => 'weather_info',
        'schema' => [
            'type' => 'object',
            'properties' => [
                'temperature' => [
                    'type' => 'number',
                    'description' => 'Temperature in degrees'
                ],
                'conditions' => [
                    'type' => 'string',
                    'description' => 'Weather conditions (e.g., sunny, rainy)'
                ],
                'forecast' => [
                    'type' => 'array',
                    'items' => [
                        'type' => 'object',
                        'properties' => [
                            'day' => ['type' => 'string'],
                            'temp' => ['type' => 'number']
                        ],
                        'required' => ['day', 'temp'],
                        'additionalProperties' => false,
                    ],
                    'description' => '5-day forecast'
                ]
            ],
            'required' => ['temperature', 'conditions'],
            '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 at runtime.

Access schema

The schema can be accessed using the structuredOutput() method:

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

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

Modify or set schema

The schema can be modified using the responseSchema() method:

// responseSchema(?array $schema)

$agent->responseSchema([
    'name' => 'user_profile',
    'schema' => [
        'type' => 'object',
        'properties' => [
            'name' => ['type' => 'string'],
            'age' => ['type' => 'number'],
            'interests' => [
                'type' => 'array',
                'items' => ['type' => 'string']
            ],
        ],
        'required' => ['name', 'age', 'interests'],
        'additionalProperties' => false,
    ],
    'strict' => true,
]);

Example Use Cases

User Profile Generation

protected $responseSchema = [
    'name' => 'user_profile',
    'schema' => [
        'type' => 'object',
        'properties' => [
            'name' => ['type' => 'string'],
            'age' => ['type' => 'number'],
            'interests' => [
                'type' => 'array',
                'items' => ['type' => 'string']
            ],
        ],
        'required' => ['name', 'age', 'interests'],
        'additionalProperties' => false,
    ],
    'strict' => true,
];

Product Recommendations

protected $responseSchema = [
    'name' => 'product_recommendations',
    'schema' => [
        'type' => 'object',
        'properties' => [
            'products' => [
                'type' => 'array',
                'items' => [
                    'type' => 'object',
                    'properties' => [
                        'id' => ['type' => 'string'],
                        'name' => ['type' => 'string'],
                        'reason' => ['type' => 'string'],
                        'score' => ['type' => 'number'],
                    ],
                    'required' => ['id', 'name', 'reason'],
                    'additionalProperties' => false,
                ],
            ],
            'category' => ['type' => 'string'],
        ],
        'required' => ['products', 'category'],
        'additionalProperties' => false,
    ],
    'strict' => true,
];

Content Analysis

protected $responseSchema = [
    'name' => 'content_analysis',
    'schema' => [
        'type' => 'object',
        'properties' => [
            'sentiment' => [
                'type' => 'string',
                'enum' => ['positive', 'neutral', 'negative'],
            ],
            'topics' => [
                'type' => 'array',
                'items' => ['type' => 'string'],
            ],
            'summary' => ['type' => 'string'],
            'keyPoints' => [
                'type' => 'array',
                'items' => ['type' => 'string'],
            ],
        ],
        'required' => ['sentiment', 'topics', 'summary'],
        'additionalProperties' => false,
    ],
    'strict' => true,
];

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

​Defining Response Schemas

​Schema Configuration Options

Basic Types

Required Properties

Nested Structures

Property Descriptions

​Using Structured Output

​Runtime Schema Management

​Access schema

​Modify or set schema

​Example Use Cases

​Best Practices

Defining Response Schemas

Schema Configuration Options

Using Structured Output

Runtime Schema Management

Access schema

Modify or set schema

Example Use Cases

Best Practices