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.