> ## Documentation Index
> Fetch the complete documentation index at: https://docs.laragent.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Structured Output
> Define JSON schemas to receive structured, predictable responses from your AI agents instead of free-form text.
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.
```php Basic Schema theme={null}
protected $responseSchema = [
'name' => 'weather_info',
'schema' => [
'type' => 'object',
'properties' => [
'temperature' => [
'type' => 'number',
'description' => 'Temperature in degrees'
],
],
'required' => ['temperature'],
'additionalProperties' => false,
],
'strict' => true,
];
```
```php Complex Schema theme={null}
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:
string, number, boolean, array, object
Specify which fields must be present
Complex objects and arrays
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:
```php theme={null}
// 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:
```php theme={null}
// 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:
```php theme={null}
// 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
```php theme={null}
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,
];
```
```php theme={null}
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,
];
```
```php theme={null}
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