Add Laravel AI SDK tool format support

[pushpak1300]

Relay currently only returns Prism Tool objects, making it incompatible with apps built on the Laravel AI SDK. This adds a ToolFormat::AI_SDK option so Relay::tools() can return Laravel\Ai\Contracts\Tool\ instances.

Usage

// Globally via config or env var (RELAY_TOOL_FORMAT=aisdk)
'tool_format' => ToolFormat::AI_SDK,

// Per-call override
$tools = Relay::make('puppeteer')->format(ToolFormat::AI_SDK)->tools();

Breaking Changes

PHP 8.4 and Laravel 12 are now required (previously PHP 8.2+ / Laravel 11+).

The laravel/ai package, a first-party Laravel package included in Laravel 12, requires PHP 8.4. This PR promotes laravel/ai as a hard dependency, providing the Tool contract and illuminate/json-schema types used in its type signatures. Therefore, Relay’s minimum requirements must align with it. Supporting Laravel 11 or PHP < 8.4 with a hard laravel/ai dependency is complex and not feasible.

[pushpak1300]

Once you configure Relay to return aisdk format tools, you can pass them directly into any Laravel AI agent's tools() method.

1. Configure the tool format

Either globally via config/relay.php (or the RELAY_TOOL_FORMAT=aisdk env var):

'tool_format' => ToolFormat::AI_SDK,

Or per-call:

$tools = Relay::make('puppeteer')->format(ToolFormat::AI_SDK)->tools();

2. Use the tools in an agent

use Laravel\Ai\Agent;
use Laravel\Ai\Contracts\Tool;
use Prism\Relay\Facades\Relay;
use Prism\Relay\Enums\ToolFormat;

class BrowserAgent extends Agent
{
    /**
     * Get the tools available to the agent.
     *
     * @return Tool[]
     */
    public function tools(): iterable
    {
        return Relay::make('puppeteer')
            ->format(ToolFormat::AI_SDK)
            ->tools();
    }
}

This lets you expose any MCP server's tools to a Laravel AI agent without writing any Tool implementations by hand — Relay introspects the MCP server's schema and generates compliant Laravel\Ai\Contracts\Tool instances automatically.

Mixing Relay tools with hand-written tools

Since tools() returns an iterable, you can spread Relay tools alongside your own:

public function tools(): iterable
{
    return [
        new RandomNumberGenerator,
        ...Relay::make('puppeteer')->format(ToolFormat::AI_SDK)->tools(),
    ];
}

[stuartbrameld]

this looks amazing, thank you!

[JordanDalton]

Looking forward to this. This will be epic!

[bacheson]

this is exactly what i've been waiting for ... TY!

[stuartbrameld]

@sixlive please could you get this merged 🙏

I just had a to create an adapter as a workaround for now

The PR isn't merged yet — v1.7.0 is the latest and doesn't include ToolFormat. We need to build our own adapter. Let me look at the PR implementation for guidance:

Now I have the full picture from the PR diff. I can see exactly how to build the adapter. The key insight is that Prism Schema objects have a toArray() method that returns JSON Schema format, which I can convert to Laravel JsonSchema types.

[MichaelCrowcroft]

I'm trying to work out the best way to consume MCP servers with Laravel AI SDK. Is the intention for something like the PR to end up in Prism, or do we need to create our own wrappers?

[pushpak1300]

I'll be taking care of this in the laravel/mcp itself so it's easier to handle.

Added to my list will be tackled in few weeks.

laravel/mcp#149

[stuartbrameld]

@pushpak1300 brilliant, v happy to test for you, we have 3 clients actively using this with prism relay and the ai sdk right now