---
title: "Reasoning models"
description: "Control how much a reasoning model thinks with reasoning_effort. Handle empty or cut-off answers."
---

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

# Reasoning models

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

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

### Set it for one agent

```php
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()`:

```php
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:

```php
'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`:

```php
'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.

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