Laravel AI SDK

https://github.com/laravel/ai
Admin
Laravel AI SDK provides a unified API for interacting with AI providers like OpenAI, Anthropic, and...
Tokens:333,400
Snippets:2,130
Trust Score:9.7
License:MIT
Update:1 day ago
Show doc for...
Tokens:
Raw
### Install AWS SDK for Bedrock provider

Source: https://github.com/laravel/ai/blob/1.x/UPGRADE.md

The `aws/aws-sdk-php` package is no longer installed by default. Install it directly in your application. Resolving the Bedrock provider without the SDK throws a `RuntimeException`.

```bash
composer require aws/aws-sdk-php
```

--------------------------------

### Use provider for prompt and embeddings

Source: https://github.com/laravel/ai/blob/1.x/resources/boost/skills/ai-sdk-development/SKILL.md

Reference the configured provider by config key and specify a model per call. The prompt example uses provider 'my-llm' with model 'some-model'; the embeddings example uses provider 'my-llm' with model 'some-embedding-model'.

```php
agent()->prompt('Hello', provider: 'my-llm', model: 'some-model');

Embeddings::for(['Hello'])->generate(
    provider: 'my-llm',
    model: 'some-embedding-model',
);
```

--------------------------------

### Streaming event consumption example

Source: https://github.com/laravel/ai

Example of iterating over streamed events from an agent, using match(true) to handle StreamStart, TextDelta, ReasoningDelta, and StreamEnd events.

```php
foreach ($agent->stream('Explain streams.') as $event) {
    match (true) {
        $event instanceof StreamStart => Log::info("started: {$event->provider}/{$event->model}"),
        $event instanceof TextDelta => echo $event->delta,
        $event instanceof ReasoningDelta => Log::debug("reasoning: {$event->delta}"),
        $event instanceof StreamEnd => Log::info("done, {$event->usage->outputTokens} tokens out"),
        default => null,
    };
}
```

--------------------------------

### Stringable::toEmbeddings usage example

Source: https://github.com/laravel/ai

Example call to the toEmbeddings macro with provider 'openai' and dimensions 256.

```php
$embedding = str('Laravel AI')->toEmbeddings(provider: 'openai', dimensions: 256);
```

--------------------------------

### Example of stored tool call with approval_reason

Source: https://github.com/laravel/ai/blob/1.x/UPGRADE.md

Shows the JSON structure for a stored tool call that is waiting for approval, identified by the `approval_reason` key and no `result` field.

```json
{"id": "call_1", "name": "delete_file", "arguments": {"path": "a"}, "approval_reason": "Destructive."}
```

--------------------------------

### QueuedAgentResponse usage example

Source: https://github.com/laravel/ai

Example of queueing an agent response and attaching callbacks for success and error handling.

```php
$queued = $agent->queue('Write a haiku.');

$queued->onResponse(fn (AgentResponse $response) => Log::info($response->text));
$queued->onError(fn (Throwable $e) => report($e));
```

--------------------------------

### Usage constructor before and after TextUsage introduction

Source: https://github.com/laravel/ai/blob/1.x/UPGRADE.md

Shows the change from the old Usage constructor to the new TextUsage constructor, with argument order changes and nullable counts.

```php
// Before...
use Laravel\Ai\Responses\Data\Usage;

new Usage($promptTokens, $completionTokens, $cacheWriteInputTokens, $cacheReadInputTokens, $reasoningTokens);
```

```php
// After...
use Laravel\Ai\Responses\Data\TextUsage;

new TextUsage($inputTokens, $outputTokens, $cacheReadInputTokens, $cacheWriteInputTokens, $reasoningTokens);
```

--------------------------------

### Using textGenerationLoop to generate a response

Source: https://github.com/laravel/ai

Shows how to obtain a TextGenerationLoop from a provider and call generate with a model, instructions, messages, tools, and options. The example uses 'gpt-4o' with a CurrentDateTool and sets maxSteps to 5 and temperature to 0.2.

```php
$loop = $provider->textGenerationLoop();

$response = $loop->generate(
    $provider,
    'gpt-4o',
    'You are helpful.',
    messages: [new UserMessage('Hello!')],
    tools: [new CurrentDateTool()],
    options: new TextGenerationOptions(maxSteps: 5, temperature: 0.2),
);
```

--------------------------------

### Collection::rerank usage example

Source: https://github.com/laravel/ai

Example call to the rerank macro with by as an array of field names and a limit of 5.

```php
$ranked = collect($articles)->rerank(
    by: ['title', 'body'],
    query: 'laravel performance tips',
    limit: 5,
);
```

--------------------------------

### Example of steps column structure in agent_conversation_messages

Source: https://github.com/laravel/ai/blob/1.x/UPGRADE.md

Shows the JSON structure stored in the new `steps` column, where each assistant message contains one entry per model round trip, and each tool result is stored on the tool call that produced it.

```json
[
    {"content": "", "tool_calls": [{"id": "call_1", "name": "read_file", "arguments": {}, "result": "..."}], "reasoning": "", "replay_blocks": [], "provider_tool_calls": []},
    {"content": "Done.", "tool_calls": [], "reasoning": "", "replay_blocks": [], "provider_tool_calls": []}
]
```

--------------------------------

### ReasoningStart

Source: https://github.com/laravel/ai

Event emitted when reasoning starts. Contains the stream ID, reasoning ID, and timestamp.

```APIDOC
## ReasoningStart

### Description
Event emitted when reasoning starts. Contains the stream ID, reasoning ID, and timestamp.

### Constructor
```php
public function __construct(public string $id, public string $reasoningId, public int $timestamp)
```

### Parameters
- **id** (string) - Required - The stream ID.
- **reasoningId** (string) - Required - The reasoning ID.
- **timestamp** (int) - Required - Unix timestamp of the event.

### Type
`reasoning_start`
```

--------------------------------

### Run migration command

Source: https://github.com/laravel/ai/blob/1.x/UPGRADE.md

Execute this command to run the migration before deploying Laravel AI 1.0.

```shell
php artisan migrate
```

--------------------------------

### Stringable::decide usage example

Source: https://github.com/laravel/ai

Example call to the decide macro with criteria and threshold 0.8.

```php
$isToxic = str($review)->decide('Is this review toxic?', criteria: [
    'true' => 'Contains hate speech, harassment, or slurs.',
    'false' => 'Constructive criticism or neutral feedback.',
], threshold: 0.8);
```

--------------------------------

### WeatherTool implementation

Source: https://github.com/laravel/ai

Example tool implementing the Tool interface, using Request validation and schema definition.

```php
use Laravel\Ai\Contracts\Tool;
use Laravel\Ai\Tools\Request;

class WeatherTool implements Tool
{
    public function description(): string
    {
        return 'Get the weather for a city.';
    }

    public function handle(Request $request): string
    {
        $validated = $request->validate([
            'city' => ['required', 'string'],
            'units' => ['sometimes', 'in:celsius,fahrenheit'],
        ]);

        return weather_for($validated['city'], $validated['units'] ?? 'celsius');
    }

    public function schema($schema): array
    {
        return [
            'city' => $schema->string()->description('City name')->required(),
            'units' => $schema->string()->enum(['celsius', 'fahrenheit']),
        ];
    }
}
```

--------------------------------

### ProviderToolEvent Constructor

Source: https://github.com/laravel/ai/blob/1.x/UPGRADE.md

Constructor for the ProviderToolEvent, now requiring a provider name string.

```APIDOC
## ProviderToolEvent Constructor

### Description
Constructs a new ProviderToolEvent. The `$provider` argument is now a required string representing the provider name.

### Method
__construct

### Signature
```php
public function __construct(string $provider);
```

### Parameters
- **$provider** (string) - Required - The provider name.

### Response
- No return value.
```

--------------------------------

### Image::of

Source: https://github.com/laravel/ai

Static entry point to start an image generation. Creates a PendingImageGeneration instance with the given prompt.

```APIDOC
## Image::of

### Description
Static entry point to start an image generation. Creates a PendingImageGeneration instance with the given prompt.

### Method
`public static function of(string $prompt): PendingImageGeneration`

### Parameters
- **prompt** (string) - Required - The prompt for the image generation.

### Return Value
- **PendingImageGeneration** - A pending image generation instance.
```

--------------------------------

### QuickAgent with attributes

Source: https://github.com/laravel/ai

Example agent class using multiple attributes to configure provider, model, timeout, temperature, max steps, max tokens, cheapest model, and suppress error broadcasts. The Promptable trait is used and instructions method is defined.

```php
use Laravel\Ai\Attributes\MaxSteps;
use Laravel\Ai\Attributes\MaxTokens;
use Laravel\Ai\Attributes\Model;
use Laravel\Ai\Attributes\Provider;
use Laravel\Ai\Attributes\Temperature;
use Laravel\Ai\Attributes\Timeout;
use Laravel\Ai\Attributes\UseCheapestModel;
use Laravel\Ai\Attributes\WithoutBroadcasting;
use Laravel\Ai\Contracts\Agent;

#[Provider('openai')]
#[Model('gpt-4o-mini')]
#[Timeout(120)]
#[Temperature(0.3)]
#[MaxSteps(10)]
#[MaxTokens(1024)]
#[UseCheapestModel]
#[WithoutBroadcasting(Error::class)] // suppress error event broadcasts
class QuickAgent implements Agent
{
    use Promptable;

    public function instructions(): string { return 'Be brief.'; }
}
```

--------------------------------

### Provider::withHeaders()

Source: https://github.com/laravel/ai/blob/1.x/UPGRADE.md

Method to add custom headers to provider requests.

```APIDOC
## Provider::withHeaders()

### Description
Adds custom headers to provider requests. This method is part of the `Laravel\Ai\Contracts\Providers\Provider` contract and is inherited by providers extending `Laravel\Ai\Providers\Provider`.

### Method
withHeaders

### Signature
```php
public function withHeaders();
```

### Parameters
- No parameters documented.

### Response
- Returns the provider instance for chaining.
```

--------------------------------

### AudioGateway::audio()

Source: https://github.com/laravel/ai/blob/1.x/UPGRADE.md

Method signature for the AudioGateway audio method, now accepting provider options and a timeout.

```APIDOC
## AudioGateway::audio()

### Description
Processes an audio generation request with support for provider-specific options and a timeout.

### Method
audio

### Signature
```php
public function audio(string $text, string $voice = 'default-female', ?string $instructions = null, ?string $model = null, int $timeout = 30, array $providerOptions = []): AudioResponse;
```

### Parameters
- **$text** (string) - Required - The text to convert to audio.
- **$voice** (string) - Optional - Voice to use, defaults to 'default-female'.
- **$instructions** (?string) - Optional - Additional instructions.
- **$model** (?string) - Optional - Model to use.
- **$timeout** (int) - Optional - Timeout in seconds, defaults to 30.
- **$providerOptions** (array) - Optional - Provider-specific options.

### Response
- **AudioResponse** - The response object.
```

--------------------------------

### On-demand provider usage example

Source: https://github.com/laravel/ai

Builds an on-demand Ollama provider via Ai::build() and uses it in an agent prompt. The provider name 'my-ollama' is passed as the provider argument. The on-demand provider must be built in the process where the work runs.

```php
$provider = Ai::build([
    'name' => 'my-ollama',
    'driver' => 'ollama',
    'key' => 'ollama',
    'url' => 'http://localhost:11434',
]);

$response = $agent->prompt('hello', provider: 'my-ollama');
```

--------------------------------

### Embeddings::for usage example

Source: https://github.com/laravel/ai

Shows how to generate embeddings for a list of inputs using the Embeddings facade, with optional dimensions, caching, and provider selection.

```php
use Laravel\Ai\Embeddings;

$response = Embeddings::for(['Laravel is great', 'PHP 8.3 features'])
    ->dimensions(256)
    ->cache()          // enable caching with default TTL
    ->generate(provider: 'voyageai');

$firstVector = $response->first();
$count = count($response); // or $response->embeddings
```

--------------------------------

### Move multi-step methods to textGenerationLoop()

Source: https://github.com/laravel/ai/blob/1.x/UPGRADE.md

The multi-step methods previously on the gateway now live on the loop. Use textGenerationLoop()->generate() and textGenerationLoop()->onToolInvocation().

```php
// Before...
$provider->textGateway()->generateText(...);
$provider->textGateway()->onToolInvocation(...);

// After...
$provider->textGenerationLoop()->generate(...);
$provider->textGenerationLoop()->onToolInvocation(...);
```

--------------------------------

### Store files and create vector stores

Source: https://github.com/laravel/ai/blob/1.x/resources/boost/skills/ai-sdk-development/SKILL.md

Shows how to store a file with the provider and create a vector store, adding files by ID or directly from storage.

```php
use Laravel\Ai\Files\Document;
use Laravel\Ai\Stores;

// Store a file with the provider
$file = Document::fromPath('/path/to/doc.pdf')->put();

// Create a vector store and add files
$store = Stores::create('Knowledge Base');
$store->add($file->id);
$store->add(Document::fromStorage('manual.pdf')); // Store + add in one step
```

--------------------------------

### Define and use an Agent with Promptable

Source: https://github.com/laravel/ai/blob/1.x/resources/boost/skills/ai-sdk-development/SKILL.md

Shows how to define an agent class implementing the Agent contract with the Promptable trait, then prompt it, resolve via the container, override provider/model/timeout, stream, queue, and use anonymous agents.

```php
use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Enums\Lab;
use Laravel\Ai\Promptable;

class SalesCoach implements Agent
{
    use Promptable;

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

// Prompting
$response = (new SalesCoach)->prompt('Analyze this transcript...');
echo $response->text;

// Container resolution with dependency injection
$agent = SalesCoach::make(user: $user);

// Override provider, model, or timeout per-prompt
$response = (new SalesCoach)->prompt(
    'Analyze this transcript...',
    provider: Lab::Anthropic,
    model: 'claude-haiku-4-5-20251001',
    timeout: 120,
);

// Streaming (returns SSE response from a route)
return (new SalesCoach)->stream('Analyze this transcript...');

// Queueing
(new SalesCoach)->queue('Analyze this transcript...')
    ->then(fn ($response) => /* ... */);

// Anonymous agents
use function Laravel\Ai\{agent};

$response = agent(instructions: 'You are a helpful assistant.')->prompt('Hello');
```

--------------------------------

### continueLastConversation() Scoped to Agent

Source: https://github.com/laravel/ai/blob/1.x/UPGRADE.md

Example of continueLastConversation() now resolving the latest conversation with the current agent instead of any agent.

```php
// Before... the user's newest conversation, whichever agent wrote it.
// After... the user's newest conversation with this agent.
(new SupportAgent)->continueLastConversation($user)->prompt('...');
```

--------------------------------

### Using SummarizeAgent with prompt() and str()->summarize() macro

Source: https://github.com/laravel/ai

Shows two ways to use SummarizeAgent: directly instantiate with a sentence count and call prompt() to get a summary, or use the Stringable macro 'summarize' registered by the service provider. The macro accepts a 'sentences' parameter.

```php
use Laravel\Ai\Agents\SummarizeAgent;

$summary = (new SummarizeAgent(5))
    ->prompt($longText)
    ->text;

// Or via the Stringable macro registered by the service provider:
echo str('...')->summarize(sentences: 5);
```

--------------------------------

### Pin Gemini text model to previous version

Source: https://github.com/laravel/ai/blob/1.x/UPGRADE.md

Configure the Gemini provider to use `gemini-3.6-flash` as the default and smartest text models to stay on the previous version.

```php
'gemini' => [
    'driver' => 'gemini',
    'key' => env('GEMINI_API_KEY'),
    'models' => [
        'text' => [
            'default' => 'gemini-3.6-flash',
            'smartest' => 'gemini-3.6-flash',
        ],
    ],
],
```

--------------------------------

### Agent contract accepts more input types

Source: https://github.com/laravel/ai/blob/1.x/UPGRADE.md

Example of using the widened prompt() method that now accepts AgentInput|UserMessage|Decisions|string instead of Decisions|string.

```php
$chat = Vercel::chat($request);

$agent->withMessages($chat->history())->stream($chat);
```

--------------------------------

### RemembersConversations::continueOrStart() signature

Source: https://github.com/laravel/ai/blob/1.x/UPGRADE.md

Add the continueOrStart() method to agents implementing the RemembersConversations contract directly; it continues the given conversation or starts a new one when the ID is null.

```php
public function continueOrStart(?string $conversationId, object $as): static;
```

--------------------------------

### Using agent() function

Source: https://github.com/laravel/ai

Creates an agent with instructions and tools, then prompts it. The agent() function is autoloaded globally.

```php
use function Laravel\Ai\agent;

$agent = agent('You are a helpful assistant.', tools: [new SearchTool()]);

$response = $agent->prompt('Hello!');
```

--------------------------------

### Modify a step by creating a copy before passing to next middleware

Source: https://github.com/laravel/ai/blob/1.x/UPGRADE.md

You can modify a step by creating a copy before passing it to the next middleware. This example removes the 'SearchDocumentation' tool from non-first steps.

```php
public function handle(PendingStep $step, Closure $next)
{
    if (! $step->isFirstStep()) {
        $step = $step->withoutTools('SearchDocumentation');
    }

    return $next($step);
}
```

--------------------------------

### Use provider tools in tools() method

Source: https://github.com/laravel/ai/blob/1.x/resources/boost/skills/ai-sdk-development/SKILL.md

Return provider tools like WebSearch, WebFetch, and FileSearch from the tools() method. WebSearch can be configured with max results and allowed domains.

```php
use Laravel\Ai\Providers\Tools\{WebSearch, WebFetch, FileSearch};

public function tools(): iterable
{
    return [
        (new WebSearch)->max(5)->allow(['laravel.com']),
        new WebFetch,
        new FileSearch(stores: ['store_id']),
    ];
}
```

--------------------------------

### Define openai-compatible provider instance in config/ai.php

Source: https://github.com/laravel/ai/blob/1.x/resources/boost/skills/ai-sdk-development/SKILL.md

Add a named instance with driver 'openai-compatible', required URL, optional Bearer key, and model configurations for text, embeddings, and transcription. Embedding dimensions are optional; omit to use native dimensions.

```php
'my-llm' => [
    'driver' => 'openai-compatible',
    'url' => env('MY_LLM_URL'),        // required
    'key' => env('MY_LLM_API_KEY'),    // optional Bearer token
    'models' => [
        'text' => ['default' => 'some-chat-model'],
        'embeddings' => [
            'default' => 'some-embedding-model',
            'dimensions' => 1024, // optional; omit to use native dimensions
        ],
        'transcription' => ['default' => 'some-transcription-model'],
    ],
],
```

--------------------------------

### Token Usage Property Renames: promptTokens to inputTokens, completionTokens to outputTokens

Source: https://github.com/laravel/ai/blob/1.x/UPGRADE.md

Before and after examples for the renamed token usage properties. The new properties include cached and reasoning tokens that were previously excluded.

```php
// Before...
$response->usage->promptTokens;
$response->usage->completionTokens;

// After...
$response->usage->inputTokens;
$response->usage->outputTokens;
```

--------------------------------

### Register MCP client and return its tools

Source: https://github.com/laravel/ai/blob/1.x/resources/boost/skills/ai-sdk-development/SKILL.md

Register an MCP client once in a service provider or routes/ai.php, then return its tools from tools(). The SDK automatically wraps each Laravel\Mcp\Client\Primitives\Tool and presents it to the model as mcp_tools_<name>. The client connects on its first call; call connect() only when you need to control timing. Use Client::local('npx', ['-y', 'some-server']) for servers that run over stdio.

```php
use Laravel\Mcp\Client;
use Laravel\Mcp\Facades\Mcp;

// In a service provider or routes/ai.php
Mcp::registerClient('linear', fn () => Client::web('https://mcp.linear.app/mcp')
    ->withToken(config('services.linear.token')));

class SupportAgent implements Agent, HasTools
{
    use Promptable;

    public function tools(): iterable
    {
        return Mcp::client('linear')->tools();
    }
}
```

--------------------------------

### Skill::__construct

Source: https://github.com/laravel/ai

Creates a new Skill instance with the given name, description, instructions, and optional files and path.

```APIDOC
## Skill::__construct

### Description
Creates a new Skill instance with the given name, description, instructions, and optional files and path.

### Method
Constructor

### Signature
```php
public function __construct(
    public readonly string $name,
    public readonly Stringable|string $description,
    public readonly Stringable|string $instructions,
    public readonly array $files = [],
    public readonly ?string $path = null,
) {}
```

### Parameters
- **name** (string) - Required - The name of the skill.
- **description** (Stringable|string) - Required - A description of the skill.
- **instructions** (Stringable|string) - Required - Instructions for the skill.
- **files** (array) - Optional - List of files associated with the skill.
- **path** (?string) - Optional - Path to the skill directory.
```

--------------------------------

### Configure provider failover with provider array

Source: https://github.com/laravel/ai/blob/1.x/resources/boost/skills/ai-sdk-development/SKILL.md

Pass an array of providers to the prompt method to enable failover. The agent will try the providers in order.

```php
$response = (new MyAgent)->prompt('Hello', provider: [Lab::OpenAI, Lab::Anthropic]);
```

--------------------------------

### Skill class constructor and fromDirectory method

Source: https://github.com/laravel/ai

Defines a Skill with name, description, instructions, optional files, and path. fromDirectory returns null when no SKILL.md, front-matter, or description is found.

```php
public function __construct(
    public readonly string $name,
    public readonly Stringable|string $description,
    public readonly Stringable|string $instructions,
    public readonly array $files = [],
    public readonly ?string $path = null,
) {}

public static function fromDirectory(string $directory): ?self; // null when no SKILL.md/front-matter/description
```

--------------------------------

### Reranking usage example

Source: https://github.com/laravel/ai

Shows how to rerank documents using the Reranking facade with a limit of 5 and a specific provider. Iterates over the response to print each ranked document's index, score, and content.

```php
$response = Reranking::of($documents)
    ->limit(5)
    ->rerank('How do I install Laravel?', provider: 'cohere');

foreach ($response as $ranked) {
    echo "#{$ranked->index} ({$ranked->score}): {$ranked->document}\n";
}
```

--------------------------------

### Update agent middleware handle() method for PendingStep

Source: https://github.com/laravel/ai/blob/1.x/UPGRADE.md

Middleware now wraps each generation step instead of the entire run. Update `handle()` to accept `Laravel\Ai\PendingStep` and return `Laravel\Ai\Gateway\StepResult` from `$next($step)`. The before and after versions show the required changes.

```php
// Before...
use Closure;
use Laravel\Ai\Prompts\AgentPrompt;
use Laravel\Ai\Responses\AgentResponse;

class LogTheRun
{
    public function handle(AgentPrompt $prompt, Closure $next)
    {
        return $next($prompt)->then(function (AgentResponse $response) {
            // ...
        });
    }
}

// After...
use Closure;
use Laravel\Ai\Gateway\StepResponse;
use Laravel\Ai\PendingStep;

class LogTheRun
{
    public function handle(PendingStep $step, Closure $next)
    {
        return $next($step)->then(function (StepResponse $response) {
            // ...
        });
    }
}
```

--------------------------------

### Testing AI Capabilities with fake()

Source: https://github.com/laravel/ai/blob/1.x/resources/boost/skills/ai-sdk-development/SKILL.md

Demonstrates how to use the fake() method and various assertion methods for different AI services including Agents, Images, Audio, Transcription, Embeddings, Reranking, Files, and Stores.

```php
use App\Ai\Agents\SalesCoach;
use Laravel\Ai\{Image, Audio, Transcription, Embeddings, Reranking, Files, Stores};

// Agents
SalesCoach::fake(['Response 1', 'Response 2']);
SalesCoach::assertPrompted('query');
SalesCoach::assertNotPrompted('query');
SalesCoach::assertNeverPrompted();
SalesCoach::fake()->preventStrayPrompts();

// Images
Image::fake();
Image::assertGenerated(fn ($prompt) => $prompt->contains('sunset'));
Image::assertNothingGenerated();

// Audio
Audio::fake();
Audio::assertGenerated(fn ($prompt) => $prompt->contains('Hello'));

// Transcription
Transcription::fake(['Transcribed text.']);
Transcription::assertGenerated(fn ($prompt) => $prompt->isDiarized());

// Embeddings
Embeddings::fake();
Embeddings::assertGenerated(fn ($prompt) => $prompt->contains('Laravel'));

// Reranking
Reranking::fake();
Reranking::assertReranked(fn ($prompt) => $prompt->contains('PHP'));

// Files
Files::fake();
Files::assertStored(fn ($file) => $file->mimeType() === 'text/plain');

// Stores
Stores::fake();
Stores::assertCreated('Knowledge Base');
$store = Stores::get('id');
$store->assertAdded('file_id');
```

--------------------------------

### ToolResultMessage class and usage example

Source: https://github.com/laravel/ai

ToolResultMessage extends Message with toolResults collection. Constructor requires a Collection of ToolResult objects. Example shows creating a message with a single tool result.

```php
class ToolResultMessage extends Message
{
    public Collection $toolResults; // Collection<int, ToolResult>

    public function __construct(Collection $toolResults)
    {
        parent::__construct('tool_result', content: null);
    }
}
```

```php
use Laravel\Ai\Messages\ToolResultMessage;

$messages[] = new ToolResultMessage(collect([
    new ToolResult(id: 'call_1', name: 'search', arguments: ['q' => 'laravel'], result: '...'),
]));
```

--------------------------------

### UserMessage class and usage example

Source: https://github.com/laravel/ai

UserMessage extends Message with attachments. Constructor requires content string; attachments default to empty array. Example shows creating a message with an image attachment.

```php
class UserMessage extends Message
{
    public Collection $attachments;

    public function __construct(string $content, Collection|array $attachments = [])
    {
        parent::__construct('user', $content);
        $this->attachments = Collection::wrap($attachments);
    }
}
```

```php
use Laravel\Ai\Messages\UserMessage;

$message = new UserMessage('Summarize this image.', [Image::fromPath($path)]);
```

--------------------------------

### TextGenerationOptions::withProviderOptions

Source: https://github.com/laravel/ai

Returns a new instance with the specified raw provider options.

```APIDOC
## TextGenerationOptions::withProviderOptions

### Description
Returns a new instance with the specified raw provider options.

### Method
withProviderOptions

### Signature
```php
withProviderOptions(?array $providerOptions): self
```

### Parameters
- **providerOptions** (?array) - Required - Raw provider options.
```

--------------------------------

### Agent with FileStorage::all tools

Source: https://github.com/laravel/ai

Creates an agent with filesystem tools from FileStorage::all, specifying a disk. The tools are a Collection of Tool instances.

```php
$agent = agent(
    'Help with files.',
    tools: [
        ...FileStorage::all('s3-docs'),  // Collection of Tool instances
    ],
);
```

--------------------------------

### AnonymousAgent::instructions

Source: https://github.com/laravel/ai

Returns the system instructions for the agent.

```APIDOC
## Method: `AnonymousAgent::instructions`

### Description
Returns the system instructions for the agent.

### Signature
```php
public function instructions(): string;
```
```

--------------------------------

### HasName

Source: https://github.com/laravel/ai

Contract for file name. Provides methods to get and set the name.

```APIDOC
## HasName

### Description
Contract for file name. Provides methods to get and set the name.

### Methods
- `name(): ?string` - Returns the name or null if not set.
- `as(?string): static` - Sets the name and returns a new instance.
```

--------------------------------

### TextGenerationOptions::__construct

Source: https://github.com/laravel/ai

Creates a new TextGenerationOptions instance with optional configuration parameters for text generation.

```APIDOC
## TextGenerationOptions::__construct

### Description
Creates a new TextGenerationOptions instance with optional configuration parameters for text generation.

### Method
Constructor

### Signature
```php
public function __construct(
    public readonly ?int $maxSteps = null,
    public readonly ?int $maxTokens = null,
    public readonly ?float $temperature = null,
    public readonly ?Agent $agent = null,
    public readonly ?float $topP = null,
    public readonly ?ToolChoice $toolChoice = null,
    public readonly ?CacheInstructions $cacheInstructions = null,
    public readonly ?CacheToolDefinitions $cacheToolDefinitions = null,
    public readonly ?array $providerOptions = null,
)
```

### Parameters
- **maxSteps** (?int) - Optional - Cap on tool-call steps (validate with `#[MaxSteps]`)
- **maxTokens** (?int) - Optional - Output token cap (`#[MaxTokens]`)
- **temperature** (?float) - Optional - Sampling temperature (`#[Temperature]`)
- **agent** (?Agent) - Optional - Source agent used for `providerOptions` merging
- **topP** (?float) - Optional - Nucleus sampling (`#[TopP]`)
- **toolChoice** (?ToolChoice) - Optional - Tool selection mode
- **cacheInstructions** (?CacheInstructions) - Optional - Provider prompt caching TTL hint
- **cacheToolDefinitions** (?CacheToolDefinitions) - Optional - Provider tool-definition caching TTL hint
- **providerOptions** (?array) - Optional - Raw provider options
```

--------------------------------

### getInstanceConfig($name): array

Source: https://github.com/laravel/ai

Returns the runtime configuration for a given provider name. It checks on-demand providers first, then the 'ai.providers.<name>' configuration, and finally falls back to a driver-only configuration. Converts a Lab driver to its string value and injects the 'name' key.

```APIDOC
## getInstanceConfig($name): array

### Description
Returns the runtime configuration for a given provider name. It checks on-demand providers first, then the 'ai.providers.<name>' configuration, and finally falls back to a driver-only configuration. Converts a Lab driver to its string value and injects the 'name' key.

### Method
Method

### Parameters
#### Arguments
- **$name** (mixed) - Required - The provider name or Lab enum.

### Returns
- **array** - The runtime configuration array.
```

--------------------------------

### Reranking::timeout()

Source: https://github.com/laravel/ai/blob/1.x/UPGRADE.md

Method to set a custom timeout for a reranking request.

```APIDOC
## Reranking::timeout()

### Description
Sets a custom timeout for a reranking operation, overriding the default 30-second timeout.

### Method
timeout

### Signature
```php
Reranking::of($documents)->timeout(60)->rerank('...');
```

### Parameters
- **$timeout** (int) - Required - Timeout in seconds.

### Response
- Returns the Reranking instance for chaining.
```

--------------------------------

### ReasoningStart, ReasoningDelta, ReasoningEnd constructors and combine

Source: https://github.com/laravel/ai

Constructors for reasoning events and the ReasoningDelta::combine() static method that groups deltas by reasoningId and joins blocks with '\n\n'. Types: 'reasoning_start', 'reasoning_delta', 'reasoning_end'.

```php
// ReasoningStart
public function __construct(public string $id, public string $reasoningId, public int $timestamp)

// ReasoningDelta
public function __construct(
    public string $id,
    public string $reasoningId,
    public string $delta,
    public int $timestamp,
    public ?array $summary = null,
)
public static function combine(Collection|array $events): string  // groups deltas by reasoningId then joins blocks with "\n\n"

// ReasoningEnd
public function __construct(public string $id, public string $reasoningId, public int $timestamp, public ?array $summary = null)
```

--------------------------------

### Generate and store audio with Audio

Source: https://github.com/laravel/ai/blob/1.x/resources/boost/skills/ai-sdk-development/SKILL.md

Generates audio from text with a female voice and custom instructions, then stores it.

```php
use Laravel\Ai\Audio;

$audio = Audio::of('Hello from Laravel.')
    ->female()
    ->instructions('Speak warmly')
    ->generate();

$path = $audio->store();
```

--------------------------------

### HasMimeType

Source: https://github.com/laravel/ai

Contract for file MIME type. Provides methods to get and set the MIME type.

```APIDOC
## HasMimeType

### Description
Contract for file MIME type. Provides methods to get and set the MIME type.

### Methods
- `mimeType(): ?string` - Returns the MIME type or null if not set.
- `withMimeType(string): static` - Sets the MIME type and returns a new instance.
```

--------------------------------

### File::name / File::as

Source: https://github.com/laravel/ai

Gets or sets the file name.

```APIDOC
## File::name / File::as

### Description
Gets or sets the file name.

### Methods
- `name(): ?string` - Returns the file name.
- `as(?string $name): static` - Sets the file name and returns the instance.
```

--------------------------------

### SummarizeAgent::instructions

Source: https://github.com/laravel/ai

Returns the instructions for the agent. This method is part of the Agent interface and is used internally.

```APIDOC
## [METHOD] SummarizeAgent::instructions

### Description
Returns the instructions for the agent. This method is part of the Agent interface and is used internally.

### Method
instructions

### Signature
`public function instructions(): string`

### Return Value
- **string** - The instructions for the agent.
```

--------------------------------

### RerankingGateway::rerank()

Source: https://github.com/laravel/ai/blob/1.x/UPGRADE.md

Method signature for the RerankingGateway rerank method, now accepting provider options and a timeout.

```APIDOC
## RerankingGateway::rerank()

### Description
Processes a reranking request with support for provider-specific options and a timeout.

### Method
rerank

### Signature
```php
public function rerank(array $documents, string $query, ?int $limit = null, ?string $model = null, int $timeout = 30, array $providerOptions = []): RerankingResponse;
```

### Parameters
- **$documents** (array) - Required - Documents to rerank.
- **$query** (string) - Required - Query for reranking.
- **$limit** (?int) - Optional - Maximum number of results.
- **$model** (?string) - Optional - Model to use.
- **$timeout** (int) - Optional - Timeout in seconds, defaults to 30.
- **$providerOptions** (array) - Optional - Provider-specific options.

### Response
- **RerankingResponse** - The response object.
```

--------------------------------

### Generate an image with Image::of()

Source: https://github.com/laravel/ai

Use the static Image entry point to generate an image from a prompt. Chain landscape() and quality('hd') before calling generate(). The returned ImageResponse provides firstImage(), storePubliclyAs(), and toHtml() methods.

```php
use Laravel\Ai\Image;

$response = Image::of('A serene mountain lake at sunset')
    ->landscape()
    ->quality('hd')
    ->generate();

$image = $response->firstImage();       // GeneratedImage
$response->storePubliclyAs('images', 'lake.png'); // stores firstImage()
echo $response->toHtml('A lake');      // <img src="data:image/png;base64,..." ... />
```

--------------------------------

### Implement HasTools interface and scaffold tools

Source: https://github.com/laravel/ai/blob/1.x/resources/boost/skills/ai-sdk-development/SKILL.md

Implement the HasTools interface and scaffold tools with 'php artisan make:tool'. The tools() method must return an iterable of tool instances.

```php
use Laravel\Ai\Contracts\HasTools;

class MyAgent implements Agent, HasTools
{
    use Promptable;

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

--------------------------------

### ImageGateway::image()

Source: https://github.com/laravel/ai/blob/1.x/UPGRADE.md

Method signature for the ImageGateway image method, now accepting provider options and a timeout.

```APIDOC
## ImageGateway::image()

### Description
Processes an image generation request with support for provider-specific options and a timeout.

### Method
image

### Signature
```php
public function image(string $prompt, array $attachments = [], ?string $size = null, ?string $quality = null, ?string $model = null, ?int $timeout = null, array $providerOptions = []): ImageResponse;
```

### Parameters
- **$prompt** (string) - Required - The prompt for image generation.
- **$attachments** (array) - Optional - Attachments for the request.
- **$size** (?string) - Optional - Desired image size.
- **$quality** (?string) - Optional - Desired image quality.
- **$model** (?string) - Optional - Model to use.
- **$timeout** (?int) - Optional - Timeout in seconds.
- **$providerOptions** (array) - Optional - Provider-specific options.

### Response
- **ImageResponse** - The response object.
```

--------------------------------

### TextGenerationOptions::withToolChoice

Source: https://github.com/laravel/ai

Returns a new instance with the specified tool choice mode.

```APIDOC
## TextGenerationOptions::withToolChoice

### Description
Returns a new instance with the specified tool choice mode.

### Method
withToolChoice

### Signature
```php
withToolChoice(?ToolChoice $toolChoice): self
```

### Parameters
- **toolChoice** (?ToolChoice) - Required - The tool selection mode.
```

--------------------------------

### Replace providerOptions() with withProviderOptions()

Source: https://github.com/laravel/ai/blob/1.x/UPGRADE.md

The providerOptions() method on embeddings and transcription builders has been removed. Use withProviderOptions() instead.

```php
// Before...
Ai::embeddings('...')->providerOptions(['dimensions' => 256]);

// After...
Ai::embeddings('...')->withProviderOptions(['dimensions' => 256]);
```

--------------------------------

### recordPrompt

Source: https://github.com/laravel/ai

Records a prompt for later assertions. Returns the current instance for chaining.

```APIDOC
## recordPrompt

### Description
Records a prompt for later assertions. Returns the current instance for chaining.

### Method
recordPrompt

### Signature
`recordPrompt(AgentPrompt|QueuedAgentPrompt $prompt): self`

### Parameters
- **$prompt** (AgentPrompt|QueuedAgentPrompt) - Required - The prompt to record.

### Response
- **self** - The current instance.
```

--------------------------------

### ConversationStore::storeConversation() signature

Source: https://github.com/laravel/ai/blob/1.x/UPGRADE.md

Update custom ConversationStore implementations to accept an optional ID for the conversation to store under.

```php
public function storeConversation(
    ?string $participantType,
    string|int|null $participantId,
    string $title,
    ?string $id = null,
): string;
```

--------------------------------

### Generate and store an image with Image

Source: https://github.com/laravel/ai/blob/1.x/resources/boost/skills/ai-sdk-development/SKILL.md

Generates an image from a text prompt with landscape orientation and high quality, then stores it to the default disk.

```php
use Laravel\Ai\Image;

$image = Image::of('A sunset over mountains')
    ->landscape()
    ->quality('high')
    ->generate();

$path = $image->store(); // Store to default disk
```

--------------------------------

### usingVercelDataProtocol boolean argument removed

Source: https://github.com/laravel/ai/blob/1.x/UPGRADE.md

Shows the change from passing a boolean to usingVercelDataProtocol() to only passing the message ID.

```php
// Before...
$agent->stream('...')->usingVercelDataProtocol(true, 'msg_1');
```

```php
// After...
$agent->stream('...')->usingVercelDataProtocol('msg_1');
```

--------------------------------

### FileStorage all and readOnly methods

Source: https://github.com/laravel/ai

Provides collections of filesystem tools. all() includes read-only tools plus write/delete/copy/move; readOnly() returns only the five read-only tools.

```php
public static function all(string|Filesystem|null $disk = null): Collection;
public static function readOnly(string|Filesystem|null $disk = null): Collection;
```

--------------------------------

### Swap TextGateway contract to StepTextGateway

Source: https://github.com/laravel/ai/blob/1.x/UPGRADE.md

TextGateway has been removed. Implement StepTextGateway instead. The methods changed from generateText/streamText/onToolInvocation to generateTextStep/generateStreamStep.

```php
// Before...
use Laravel\Ai\Contracts\Gateway\TextGateway;

class MyGateway implements TextGateway { /* generateText, streamText, onToolInvocation */ }

// After...
use Laravel\Ai\Contracts\Gateway\StepTextGateway;

class MyGateway implements StepTextGateway { /* generateTextStep, generateStreamStep */ }
```

--------------------------------

### Automatic conversation persistence with RemembersConversations

Source: https://github.com/laravel/ai/blob/1.x/resources/boost/skills/ai-sdk-development/SKILL.md

Uses the RemembersConversations trait to automatically persist conversation history, starting a new conversation with forUser() and continuing with continue().

```php
use Laravel\Ai\Concerns\RemembersConversations;
use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Contracts\Conversational;
use Laravel\Ai\Promptable;

class SalesCoach implements Agent, Conversational
{
    use Promptable, RemembersConversations;

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

// Start a new conversation
$response = (new SalesCoach)->forUser($user)->prompt('Hello!');
$conversationId = $response->conversationId;

// Continue an existing conversation
$response = (new SalesCoach)->continue($conversationId, as: $user)->prompt('Tell me more.');
```

--------------------------------

### Ai::audioProvider(?string $name = null): AudioProvider

Source: https://github.com/laravel/ai

Returns the audio provider for the given name (or default). Throws LogicException if the default provider does not support audio generation.

```APIDOC
## Ai::audioProvider(?string $name = null): AudioProvider

### Description
Returns the audio provider for the given name (or default). Throws LogicException if the default provider does not support audio generation.

### Method
audioProvider

### Endpoint
Ai::audioProvider

### Parameters
#### Query Parameters
- **name** (?string) - Optional - Provider name. Defaults to null (default provider).

### Response
#### Success Response
- **AudioProvider** - The audio provider instance.

### Error Handling
Throws LogicException with message: "Provider [App\Ai\Providers\MyProvider] does not support audio generation."
```

--------------------------------

### ConversationStore::latestConversationId() signature

Source: https://github.com/laravel/ai/blob/1.x/UPGRADE.md

Update custom ConversationStore implementations to accept the agent class name and scope the lookup to that agent.

```php
public function latestConversationId(
    string $participantType,
    string|int $participantId,
    string $agent,
): ?string;
```

--------------------------------

### Configure agent with PHP attributes

Source: https://github.com/laravel/ai/blob/1.x/resources/boost/skills/ai-sdk-development/SKILL.md

Use PHP attributes to configure an agent's provider, model, max steps, max tokens, temperature, and timeout. The class must implement the Agent interface and use the Promptable trait.

```php
use Laravel\Ai\Attributes\{Provider, Model, MaxSteps, MaxTokens, Temperature, Timeout};
use Laravel\Ai\Enums\Lab;

#[Provider(Lab::Anthropic)]
#[Model('claude-haiku-4-5-20251001')]
#[MaxSteps(10)]
#[MaxTokens(4096)]
#[Temperature(0.7)]
#[Timeout(120)]
class MyAgent implements Agent
{
    use Promptable;
    // ...
}
```

--------------------------------

### Create store and add document with Stores facade

Source: https://github.com/laravel/ai

Shows the static entry point for creating a store, uploading a file, adding it with metadata, and removing it. Uses the `Stores` and `Files` facades from the `Laravel\Ai` namespace.

```php
use Laravel\Ai\Stores;

$store = Stores::create('Knowledge Base', 'Product documentation');
$file = Files::putFromPath(storage_path('docs.md'));

$document = $store->add($file, metadata: ['topic' => 'getting-started']);
$store->remove($document->id());
```

--------------------------------

### Filter Out Failed Turns by Status

Source: https://github.com/laravel/ai/blob/1.x/UPGRADE.md

Filter conversation messages to exclude failed turns by checking the status against MessageStatus::Completed.

```php
$conversation->messages()->where('status', MessageStatus::Completed);
```

--------------------------------

### Catching Approval Exceptions

Source: https://github.com/laravel/ai

Wrap agent prompt calls in try-catch to handle ApprovalMismatchException (HTTP 409) and ApprovalNotResumableException (client should start over).

```php
try {
    $agent->prompt($decisions);
} catch (ApprovalMismatchException $e) {
    return response()->json(['error' => $e->getMessage()], 409);
} catch (ApprovalNotResumableException $e) {
    // instruct the client to start over
}
```

--------------------------------

### TextStart, TextDelta, TextEnd constructors and combine

Source: https://github.com/laravel/ai

Constructors for text events and the TextDelta::combine() static method that joins deltas per step with '\n\n'. Types: 'text_start', 'text_delta', 'text_end'.

```php
// TextStart
public function __construct(public string $id, public string $messageId, public int $timestamp)

// TextDelta
public function __construct(public string $id, public string $messageId, public string $delta, public int $timestamp)
public static function combine(Collection|array $events): string  // joins deltas per step, joined by "\n\n"

// TextEnd
public function __construct(public string $id, public string $messageId, public int $timestamp)
```

--------------------------------

### Transcription with provider options for verbose_json

Source: https://github.com/laravel/ai/blob/1.x/resources/boost/skills/ai-sdk-development/SKILL.md

Override transcription response format by passing provider options. This example requests 'verbose_json' for segments, using the configured provider 'my-llm'.

```php
Transcription::fromDisk('recordings', $path)
    ->withProviderOptions(['response_format' => 'verbose_json'])
    ->generate(provider: 'my-llm');
```
Tokens:
Raw