Skip to content

Tools

Let a Workers AI model call your PHP tools. Pick a model that calls them, and force a call when needed.

Updated

You write tools with the standard Laravel AI interfaces, and the package turns each one into an OpenAI-style function definition.

Define a tool and an agent

use Illuminate\Contracts\JsonSchema\JsonSchema;
use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Contracts\HasTools;
use Laravel\Ai\Contracts\Tool;
use Laravel\Ai\Promptable;
use Laravel\Ai\Tools\Request;

class GetWeather implements Tool
{
    public function description(): string
    {
        return 'Look up the current weather.';
    }

    public function handle(Request $request): string
    {
        return "Sunny in {$request['city']}.";
    }

    public function schema(JsonSchema $schema): array
    {
        return ['city' => $schema->string()->required()];
    }
}

class WeatherAgent implements Agent, HasTools
{
    use Promptable;

    public function instructions(): string
    {
        return 'Use the tool to answer weather questions.';
    }

    public function tools(): iterable
    {
        return [new GetWeather];
    }
}

(new WeatherAgent)->prompt('Weather in Tokyo?', provider: 'workers-ai');

What the package does

  • It sends tool_choice: auto when the agent has tools.
  • A tool with no parameters works. The package sends an empty properties object, because Workers AI rejects an empty array.
  • It keeps the reasoning text from a tool-call turn and sends it back on the next turn.
  • It supports sub-agents and MCP tools. When a tool has a name() method, the package uses that name, so two instances of one class don’t collide.
  • It encodes array tool results as JSON without escaping slashes or unicode.

Choose a model for tools

Not every model calls tools. In tests on 2026-06-11 on the direct API, on one account:

Model Tool calls
@cf/meta/llama-3.3-70b-instruct-fp8-fast (default) Answers in prose. Does not call tools on the /v1 endpoint.
@cf/meta/llama-4-scout-17b-16e-instruct Calls tools.
@cf/openai/gpt-oss-120b Calls tools.

If your agent uses tools, set the model on the agent or the call, because the default model won’t call them.

Force a tool call

With tool_choice: auto, open-weight models call a tool only some of the time. To force a call, return tool_choice from providerOptions():

use Laravel\Ai\Enums\Lab;

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

On the turn after the tool result, the package switches a forced tool_choice back to auto. Otherwise the model would keep calling the tool until it hit the step limit and never return text. A tool_choice of none is left as it is.

Provider tools are not supported

Laravel AI provider tools, such as WebSearch, run inside a provider’s own API, and Workers AI has no such tools. On laravel/ai 1.1 and later, Laravel AI removes them before the call, so the model answers without them and you get no error. On 0.9 to 1.0, the package throws RuntimeException with the message Workers AI does not support [ToolName] provider tools.

For web search, use CloudflareWebSearch. For anything else, write a normal tool that calls the service yourself.

Limit the steps

Laravel AI runs the tool loop, so you cap the number of steps the usual way, with #[MaxSteps] on the agent.

Type to search…

↑↓ navigate↵ selectEsc close