Skip to content

UPGRADE.md

Latest commit

 

History

History
105 lines (75 loc) · 3.2 KB

UPGRADE.md

File metadata and controls

105 lines (75 loc) · 3.2 KB
Raw

Upgrade Guide

Upgrading To 0.9 From 0.8

Provider Options API

Likelihood Of Impact: High

The providerOptions() method on embeddings and transcription builders has been removed in favor of withProviderOptions():

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

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

The withProviderOptions() signature on provider tools has also changed. The Lab|string $provider argument was dropped in favor of an array or closure:

// Before...
$tool->withProviderOptions('openai', ['key' => 'value']);

// After...
$tool->withProviderOptions(['key' => 'value']);

// Or, to vary options per provider, pass a closure...
$tool->withProviderOptions(fn (Lab|string $provider) => match ($provider) {
    Lab::OpenAi => ['key' => 'value'],
    default => [],
});

The TextGateway Contract Was Removed

Likelihood Of Impact: Low

Laravel\Ai\Contracts\Gateway\TextGateway has been removed. Provider gateways now implement only StepTextGateway, and the multi-step API lives entirely on the provider's TextGenerationLoop. Most applications are unaffected.

If you wrote or type-hinted a custom gateway, swap the contract:

// 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 */ }

The multi-step methods you used to call on the gateway now live on the loop:

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

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

If you implement TextProvider directly instead of extending the base Provider, add a textGenerationLoop(): TextGenerationLoop method. Anything extending Provider gets it for free.

Faked Responses Now Run Through The Real Loop

Likelihood Of Impact: Low

Agent::fake() responses now flow through the same TextGenerationLoop as real providers. Existing tests keep passing, but if you assert on exact messages or streamed events, four behaviors are now more realistic:

  • Faking a tool call for a tool the agent has not registered throws NoSuchToolException instead of being silently skipped. Register the tool.
  • After a faked tool call, $response->messages includes the final assistant reply (one extra message). text, toolCalls, toolResults, and steps are unchanged.
  • Faking an empty string no longer emits TextStart / TextEnd events while streaming.
  • Faked tool calls now emit a ToolCall event while streaming. If you count streamed events, expect one extra per tool call.

Native Anthropic Structured Outputs

Likelihood Of Impact: Low

Anthropic structured outputs now use the native output_config.format API by default instead of the synthetic tool approach. To restore the previous behavior, disable it in your provider configuration:

'anthropic' => [
    'use_native_structured_output' => false,
],