---
title: "Structured output"
description: "Get JSON that matches a schema from Workers AI. Use strict mode and automatic re-ask."
---

> Documentation Index
> Fetch the complete documentation index at: https://laravel-cf-workersai.meirdick.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Structured output

Implement `Laravel\Ai\Contracts\HasStructuredOutput` on the agent and return a schema from `schema()`:

```php
use Illuminate\Contracts\JsonSchema\JsonSchema;
use Laravel\Ai\Attributes\Strict;
use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Contracts\HasStructuredOutput;
use Laravel\Ai\Promptable;

#[Strict]
class TaskAgent implements Agent, HasStructuredOutput
{
    use Promptable;

    public function instructions(): string
    {
        return 'Extract the task from the message.';
    }

    public function schema(JsonSchema $schema): array
    {
        return [
            'title' => $schema->string()->required(),
            'priority' => $schema->string()->enum(['low', 'high'])->required(),
        ];
    }
}

$task = (new TaskAgent)->prompt('Fix the login bug, it is urgent.', provider: 'workers-ai');
$task->toArray();
```

The package sends the schema as `response_format` with type `json_schema`.

## Strict mode

Add `#[Strict]` to the agent. The request then sends `strict: true`, and the schema requires every property. Without `#[Strict]`, it sends `strict: false`.

Some models ignore the strict flag, and the re-ask below catches those cases.

## Automatic re-ask

Workers AI's JSON mode is best-effort, so a model can leave out a required field or return a value outside an enum.

The package checks each structured response for required fields and enum values. If the check fails, it adds the error to the conversation and asks again, up to `structured_output_retries` times (2 by default).

```php
'workers-ai' => [
    // ...
    'structured_output_retries' => 0, // turn re-ask off
],
```

The package doesn't re-ask when the finish reason is `length`, because the output was cut off. Raise the token cap instead. A re-ask runs inside one step, so it doesn't count against `#[MaxSteps]`.

## Give structured calls enough budget

Reasoning and the answer share one token cap, so a reasoning model can spend the whole cap on thinking and leave no room for the JSON. For schema work:

- Set `#[ReasoningEffort(ReasoningEffort::LOW)]`. See [Reasoning models](/docs/guides/reasoning/).
- Raise `#[Timeout]`, because structured calls run longer.
- Turn on `throw_on_truncation`, so a cut-off JSON object throws instead of returning bad JSON. See [Errors and retries](/docs/guides/errors-and-retries/).

Source: https://laravel-cf-workersai.meirdick.com/docs/guides/structured-output/index.mdx
