Skip to content

Reasoning models

Control how much a reasoning model thinks with reasoning_effort. Handle empty or cut-off answers.

Updated

Many Workers AI models write reasoning text before the answer, and that reasoning costs tokens, time and neurons. Use reasoning_effort to limit it.

Set reasoning_effort

Cloudflare accepts the OpenAI reasoning_effort field on /compat. Laravel AI doesn’t send it, so the package does.

If you don’t set it, the model picks its own effort. Here’s the difference it makes, measured on 2026-09-09 on one account with @cf/openai/gpt-oss-120b and one two-sentence question:

reasoning_effort Reasoning Answer Wall time Neurons
low 20 chars 363 chars 1.4 s 9.6
unset 104 chars 433 chars 2.6 s 11.3
high 1,564 chars 296 chars 7.4 s 31.4

The low answer wasn’t worse. These figures show the order of magnitude, not a guarantee, but low is a good default when speed matters.

Valid values are low, medium and high. Cloudflare returns HTTP 400 for OpenAI’s none and minimal, so the package rejects them with an InvalidArgumentException before it sends the request.

Set it for all agents

'workers-ai' => [
    // ...
    'reasoning_effort' => 'low',
],

Set it for one agent

use Meirdick\WorkersAi\Attributes\ReasoningEffort;

#[ReasoningEffort(ReasoningEffort::LOW)]
class DraftingAgent implements Agent { /* ... */ }

Order of precedence

If you set it in more than one place, the later item in this list wins:

  1. reasoning_effort in the provider config.
  2. #[ReasoningEffort] on the agent.
  3. A reasoning_effort key returned by providerOptions().

Which models obey it

Model Result
@cf/openai/gpt-oss-120b Obeys all three levels.
@cf/zai-org/glm-5.3-flash Any value turns reasoning off.
@cf/zai-org/glm-4.7-flash Ignores it.

Test your own model before you rely on these results.

The thinking flag

chat_template_kwargs.thinking is an older, model-specific switch. It works on the Kimi chat template and on models that share it, but it had no effect on @cf/zai-org/glm-5.3-flash. Try reasoning_effort first.

To use it, return it from providerOptions():

use Laravel\Ai\Enums\Lab;

// Inside your agent class:
public function providerOptions(Lab|string $provider): array
{
    return $provider === 'workers-ai'
        ? ['chat_template_kwargs' => ['thinking' => false]]
        : [];
}

When thinking is true and the token cap is below 2048, the package raises the cap to 2048 and writes a warning to the log. Reasoning and the answer share one cap, so a small cap can leave no room for the answer.

Empty answers

A reasoning model can spend its whole token cap on thinking. Cloudflare then returns HTTP 200 with content: null, and Laravel AI gives you an empty string, which your code can’t tell apart from a real empty answer.

So by default the package throws EmptyResponseException instead. A tool-call turn with no text doesn’t throw.

To receive the empty response instead:

'workers-ai' => [
    // ...
    'throw_on_empty_response' => false,
],

When you see this exception, raise the token cap or lower reasoning_effort.

Cut-off answers

Cloudflare marks an answer that hit the token cap with finish_reason: "length", and Laravel AI returns the partial text as if it succeeded. To get an exception instead, turn on throw_on_truncation:

'workers-ai' => [
    // ...
    'throw_on_truncation' => true,
],

The package then throws TruncatedResponseException on any step that ends with finish reason length. It’s worth turning on for extraction and drafting, where a partial answer is worse than none.

Where reasoning text appears

Model Reasoning key in the response
@cf/zai-org/glm-5.3-flash reasoning_content
@cf/openai/gpt-oss-120b reasoning and reasoning_content
@cf/zai-org/glm-4.7-flash reasoning and reasoning_content
@cf/meta/llama-3.3-70b-instruct-fp8-fast reasoning, always null
@cf/qwen/qwq-32b None. Reasoning is inside content.

The package reads all of these keys, so you don’t have to. On laravel/ai 1.x, it also fills StepResponse::$reasoning. On every supported laravel/ai version, it sends the reasoning text back to the model between tool-call turns.

Type to search…

↑↓ navigate↵ selectEsc close