Skip to content

Structured output

Get JSON that matches a schema from Workers AI. Use strict mode and automatic re-ask.

Updated

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

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).

'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.
  • 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.

Type to search…

↑↓ navigate↵ selectEsc close