Skip to content

Text generation

Send prompts to Workers AI models with Laravel AI agents. Set the model, token cap and timeout.

Updated

Prompt an agent

For a one-off call, use the agent() helper:

use function Laravel\Ai\agent;

$response = agent('You are a helpful assistant.')
    ->prompt('Name three uses for a paperclip.', provider: 'workers-ai');

echo $response->text;

For an agent class, implement Laravel\Ai\Contracts\Agent and use the Promptable trait. Add #[Provider('workers-ai')] so the agent always runs on Workers AI.

use Laravel\Ai\Attributes\Provider;
use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Promptable;

#[Provider('workers-ai')]
class SupportAgent implements Agent
{
    use Promptable;

    public function instructions(): string
    {
        return 'You answer support questions in two sentences.';
    }
}

$response = (new SupportAgent)->prompt('How do I reset my password?');

Choose a model

The package uses these models when you name none:

Role Default model Config key
Default @cf/meta/llama-3.3-70b-instruct-fp8-fast models.text.default
#[UseCheapestModel] @cf/meta/llama-3.2-3b-instruct models.text.cheapest
#[UseSmartestModel] @cf/moonshotai/kimi-k2.6 models.text.smartest

To pick a model for one call, pass model:. For a whole agent, add #[Model('@cf/...')]. To change the defaults, use the config keys above. See Models.

Set the token cap

When a request has no token cap, Cloudflare stops the completion at 256 tokens, which cuts most structured output off in the middle of the JSON. So the package sends max_completion_tokens: 4096 by default.

Change the default for all agents with default_max_tokens:

'workers-ai' => [
    // ...
    'default_max_tokens' => 2048,
],

You can set it to null to send no cap, but avoid that. On 2026-09-09 on one account, @cf/zai-org/glm-5.3-flash with no cap ran to 8,190 tokens in 369 seconds.

Set a cap for one agent with #[MaxTokens]:

use Laravel\Ai\Attributes\MaxTokens;

#[MaxTokens(500)]
class ShortAnswerAgent implements Agent { /* ... */ }

A per-call or per-agent value wins over default_max_tokens, which wins over the Cloudflare default.

Set the timeout

Laravel AI uses a 60-second timeout, and large models, structured output and reasoning models can need more. To raise it:

use Laravel\Ai\Attributes\Timeout;

#[Timeout(120)]
class ExtractionAgent implements Agent { /* ... */ }

// or per call, with any agent:
$agent = new ExtractionAgent;
$agent->prompt('...', provider: 'workers-ai', timeout: 120);

The package doesn’t retry a request that times out. It fails at once, because a retry would run as long again. See Errors and retries.

Temperature and top-p

The package sends temperature and top_p when Laravel AI sets them, which you do with #[Temperature] and #[TopP] on the agent.

Send extra request fields

To add fields to the request body, implement Laravel\Ai\Contracts\HasProviderOptions on the agent. The package merges the array you return into the body.

use Laravel\Ai\Contracts\HasProviderOptions;
use Laravel\Ai\Enums\Lab;

class MyAgent implements Agent, HasProviderOptions
{
    use Promptable;

    public function instructions(): string
    {
        return 'You are a helpful assistant.';
    }

    public function providerOptions(Lab|string $provider): array
    {
        return $provider === 'workers-ai'
            ? ['seed' => 42]
            : [];
    }
}

For this package, $provider is a string, not a Lab case. The package doesn’t check the fields, so read the model’s page in the Cloudflare catalog to see which ones it accepts.

Type to search…

↑↓ navigate↵ selectEsc close