Text generation

Prompt an agent

Use the agent() helper for a one-off call:

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 uses this package.

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:

Name a model for one call with model:. Name one for an agent with #[Model('@cf/...')]. Change the defaults in config. See Models.

Set the token cap

Cloudflare stops a completion at 256 tokens when the request has no cap. That cuts most structured output 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,
],

Set it to null to send no cap. Avoid this. Measured on 2026-09-09 on one account: @cf/zai-org/glm-5.3-flash ran to 8,190 tokens in 369 seconds with no cap.

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

use Laravel\Ai\Attributes\MaxTokens;

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

Precedence, highest first: the per-call or per-agent value, then default_max_tokens, then the Cloudflare default.

Set the timeout

Laravel AI uses a 60-second timeout. Large models, structured output and reasoning models can need more. Raise the timeout:

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 does not 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. Set them 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 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]
            : [];
    }
}

$provider is a string for this package, not a Lab case. The package does not check the fields. Read the model page in the Cloudflare catalog to see which fields it accepts.