> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# Laravel AI SDK

> OpenAI・Anthropic・Geminiなど複数のAIプロバイダーを統一インターフェースで扱えるLaravel AI SDKの完全ガイド。エージェント、画像生成、音声、埋め込み、テストまで網羅します。

## はじめに

[Laravel AI SDK](https://github.com/laravel/ai) は、OpenAI・Anthropic・Gemini などの AI プロバイダーと対話するための統一された表現力豊かな API を提供します。AI SDK を使うと、ツールや構造化出力を備えたインテリジェントなエージェントの構築、画像生成、音声合成・文字起こし、ベクター埋め込みの作成など、多彩な AI 機能を一貫した Laravel らしいインターフェースで実現できます。

> [!NOTE]
>
> Laravel AI SDK は Laravel 13 で追加された公式パッケージです。`laravel/ai` として提供されており、複数の AI プロバイダーを統一 API で扱えます。

## プロバイダーサポート一覧

| 機能 | 対応プロバイダー |
| - | - |
| テキスト生成 | OpenAI, OpenAI Compatible, Anthropic, Gemini, Azure, Bedrock, Groq, xAI, DeepSeek, Mistral, Ollama, OpenRouter |
| 画像生成 | OpenAI, Gemini, xAI, Azure, Bedrock, OpenRouter |
| 音声合成（TTS） | OpenAI, ElevenLabs, Gemini, Mistral |
| 音声認識（STT） | OpenAI, OpenAI Compatible, ElevenLabs, Groq, Mistral, Gemini |
| 埋め込み | OpenAI, OpenAI Compatible, Gemini, Azure, Bedrock, Cohere, Mistral, Jina, VoyageAI, Ollama, OpenRouter |
| リランキング | Cohere, Jina, VoyageAI, Bedrock |
| ファイル | OpenAI, Anthropic, Gemini, Azure |

## インストール

**1. パッケージのインストール**

Composer で Laravel AI SDK をインストールします。

```shell theme={null}
composer require laravel/ai
```

**2. 設定ファイルとマイグレーションの公開**

`vendor:publish` Artisan コマンドで設定ファイルとマイグレーションを公開します。

```shell theme={null}
php artisan vendor:publish --provider="Laravel\Ai\AiServiceProvider"
```

**3. マイグレーションの実行**

データベースマイグレーションを実行します。`agent_conversations` と `agent_conversation_messages` テーブルが作成され、会話履歴の保存に使われます。

```shell theme={null}
php artisan migrate
```

## 設定

### 環境変数

使用する AI プロバイダーの API キーを `.env` ファイルに設定します。

```ini theme={null}
ANTHROPIC_API_KEY=
AZURE_OPENAI_API_KEY=
COHERE_API_KEY=
DEEPSEEK_API_KEY=
ELEVENLABS_API_KEY=
GEMINI_API_KEY=
GROQ_API_KEY=
MISTRAL_API_KEY=
OLLAMA_API_KEY=
OPENAI_API_KEY=
OPENROUTER_API_KEY=
JINA_API_KEY=
VOYAGEAI_API_KEY=
XAI_API_KEY=
```

テキスト・画像・音声・文字起こし・埋め込みに使うデフォルトモデルは `config/ai.php` でも設定できます。

### カスタムベース URL

プロキシサービスを経由させる場合は、プロバイダーごとにカスタム URL を設定できます。

```php theme={null}
'providers' => [
    'openai' => [
        'driver' => 'openai',
        'key' => env('OPENAI_API_KEY'),
        'url' => env('OPENAI_URL'),
    ],
    'anthropic' => [
        'driver' => 'anthropic',
        'key' => env('ANTHROPIC_API_KEY'),
        'url' => env('ANTHROPIC_BASE_URL'),
    ],
],
```

カスタムベース URL は OpenAI・Anthropic・Gemini・Groq・Cohere・DeepSeek・xAI・OpenRouter で利用できます。

### OpenAI-Compatible プロバイダー

LM Studio・vLLM・Together・Fireworks・ローカルゲートウェイなど、OpenAI 互換の API を使用する場合は `openai-compatible` ドライバーでプロバイダーを設定できます。`url` は必須で、`key` を指定した場合は Bearer トークンとして送信されます。

```php theme={null}
'providers' => [
    'local' => [
        'driver' => 'openai-compatible',
        'url' => env('LOCAL_AI_URL'),
        'key' => env('LOCAL_AI_API_KEY'),
    ],
],
```

設定後は、他のプロバイダーと同様にプロバイダー名で指定できます。

```php theme={null}
agent()->prompt('What is Laravel?', provider: 'local', model: 'local-model');
```

デフォルトテキストモデルを設定しておくと、毎回モデルを指定せずに使えます。

```php theme={null}
'local' => [
    'driver' => 'openai-compatible',
    'url' => env('LOCAL_AI_URL'),
    'key' => env('LOCAL_AI_API_KEY'),
    'models' => [
        'text' => [
            'default' => env('LOCAL_AI_MODEL'),
        ],
    ],
],
```

すべての送信リクエストにカスタムHTTPヘッダーを追加するには、設定に `headers` 配列を定義します。Bearerトークン以外の認証ヘッダーや識別ヘッダーが必要なエンドポイントで利用できます。

```php theme={null}
'local' => [
    'driver' => 'openai-compatible',
    'url' => env('LOCAL_AI_URL'),
    'key' => env('LOCAL_AI_API_KEY'),
    'headers' => [
        'X-Tenant-Id' => env('LOCAL_AI_TENANT_ID'),
    ],
],
```

OpenAI-Compatible プロバイダーはテキスト生成・ストリーミング・ツール・構造化出力・画像添付・埋め込み・文字起こしに対応しています。エンドポイントで追加のリクエストボディフィールドが必要な場合は、[プロバイダーオプション](#プロバイダーオプション)を使用してください。

#### OpenAI-Compatibleの埋め込み

任意のエンドポイントには既知のモデルがないため、OpenAI-Compatibleプロバイダーで `embeddings()` を使うにはデフォルトの埋め込みモデルを設定する必要があります。`dimensions` を省略するとリクエストにパラメーターが含まれず、モデル固有の次元数が使われます。

```php theme={null}
'local' => [
    'driver' => 'openai-compatible',
    'url' => env('LOCAL_AI_URL'),
    'key' => env('LOCAL_AI_API_KEY'),
    'models' => [
        'embeddings' => [
            'default' => 'text-embedding-qwen3-embedding-0.6b',
            'dimensions' => 1024, // 任意
        ],
    ],
],
```

#### OpenAI-Compatibleの文字起こし

OpenAI-Compatibleプロバイダーで `Transcription` を使うには、デフォルトの文字起こしモデルを設定します。音声は標準的な multipart リクエストとして、エンドポイントの `/audio/transcriptions` へアップロードされます。

```php theme={null}
'local' => [
    'driver' => 'openai-compatible',
    'url' => env('LOCAL_AI_URL'),
    'key' => env('LOCAL_AI_API_KEY'),
    'models' => [
        'transcription' => [
            'default' => 'whisper-1',
        ],
    ],
],
```

> [!NOTE]
>
> OpenAI-Compatible と Groq プロバイダーは話者分離に対応していません。これらのプロバイダーで `diarize` メソッドを呼び出すと例外がスローされます。

### オンデマンドプロバイダー

マルチテナントアプリでテナントごとのAPIキーをDBに保存している場合など、設定ファイルに定義していない認証情報を使いたいことがあります。`Ai::build` メソッドに `config/ai.php` のプロバイダー定義と同じ構造の配列を渡すと、その場でプロバイダーを作成できます。

```php theme={null}
use App\Ai\Agents\SalesCoach;
use Laravel\Ai\Ai;

$response = (new SalesCoach)->prompt('Analyze this sales transcript...', provider: [
    Ai::build([
        'driver' => 'anthropic',
        'key' => $user->anthropic_key,
    ]),
]);
```

オンデマンドプロバイダーは、[フェイルオーバー](#フェイルオーバー)のリストや、画像・音声・文字起こし・埋め込みの生成を含め、プロバイダーを受け取る場所ならどこでも使えます。モデルを指定するには、設定に `models` 配列を含めます。

```php theme={null}
$response = (new SalesCoach)->prompt('Analyze this sales transcript...', provider: [
    Ai::build(['driver' => 'anthropic', 'key' => $user->anthropic_key]),
    Ai::build([
        'driver' => 'openai',
        'key' => $user->openai_key,
        'models' => ['text' => ['default' => 'gpt-6']],
    ]),
]);
```

エージェントが常にオンデマンドプロバイダーを使う場合は、エージェントの `provider` メソッドからプロバイダーを返せます。エージェントが使われるたびにプロバイダーが再構築されるため、キュー実行するエージェントでも問題なく動作します。

```php theme={null}
use Laravel\Ai\Ai;
use Laravel\Ai\Providers\Provider;

public function provider(): Provider
{
    return Ai::build($this->user->aiConfiguration());
}
```

> [!NOTE]
>
> オンデマンドプロバイダーは、上の例のように配列で渡してください。設定配列に `name` を指定する場合、その名前を組み込みプロバイダーや `config/ai.php` で定義したプロバイダーと重複させることはできません。

### Lab enum

コード内でプロバイダーを参照するには `Lab` enum を使います。

```php theme={null}
use Laravel\Ai\Enums\Lab;

Lab::Anthropic;
Lab::OpenAI;
Lab::Gemini;
```

***

## エージェント

エージェントは Laravel AI SDK の基本的な構成要素です。`make:agent` コマンドでエージェントクラスを生成できます。

```shell theme={null}
php artisan make:agent SalesCoach

# 構造化出力付きエージェントの生成
php artisan make:agent SalesCoach --structured
```

生成されたエージェントは `app/Ai/Agents/` ディレクトリに配置されます。以下は主要なインターフェースをすべて実装したエージェントの例です。

```php theme={null}
<?php

namespace App\Ai\Agents;

use App\Ai\Tools\RetrievePreviousTranscripts;
use App\Models\History;
use App\Models\User;
use Illuminate\Contracts\JsonSchema\JsonSchema;
use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Contracts\Conversational;
use Laravel\Ai\Contracts\HasStructuredOutput;
use Laravel\Ai\Contracts\HasTools;
use Laravel\Ai\Messages\Message;
use Laravel\Ai\Promptable;
use Stringable;

class SalesCoach implements Agent, Conversational, HasTools, HasStructuredOutput
{
    use Promptable;

    public function __construct(public User $user) {}

    public function instructions(): Stringable|string
    {
        return 'You are a sales coach, analyzing transcripts and providing feedback and an overall sales strength score.';
    }

    public function messages(): iterable
    {
        return History::where('user_id', $this->user->id)
            ->latest()
            ->limit(50)
            ->get()
            ->reverse()
            ->map(function ($message) {
                return new Message($message->role, $message->content);
            })->all();
    }

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

    public function schema(JsonSchema $schema): array
    {
        return [
            'feedback' => $schema->string()->required(),
            'score' => $schema->integer()->min(1)->max(10)->required(),
        ];
    }
}
```

```mermaid theme={null}
flowchart TD
    A["ユーザーのプロンプト"] --> B["Agent::prompt()"]
    B --> C["オプション付与"]
    C -->|"Conversational の場合"| D["会話履歴を付与"]
    C -->|"HasTools の場合"| E["ツール一覧を付与"]
    C -->|"HasStructuredOutput の場合"| F["JSONスキーマを付与"]
    D --> G["AI プロバイダーへ送信"]
    E --> G
    F --> G
    B --> G
    G --> H["レスポンス"]
    H -->|"ツール呼び出し"| I["ツール実行"]
    I --> G
    H -->|"完了"| J["AgentResponse"]
```

### プロンプト

`prompt()` メソッドでエージェントにメッセージを送ります。

```php theme={null}
$response = (new SalesCoach)->prompt('Analyze this sales transcript...');
return (string) $response;
```

`make()` 静的メソッドを使うと、コンテナから依存関係を解決してインスタンスを生成できます。

```php theme={null}
$agent = SalesCoach::make(user: $user);
```

プロバイダー・モデル・タイムアウトは `prompt()` の引数で上書きできます。

```php theme={null}
$response = (new SalesCoach)->prompt(
    'Analyze this sales transcript...',
    provider: Lab::Anthropic,
    model: 'claude-haiku-4-5-20251001',
    timeout: 120,
);
```

#### 生のHTTPレスポンス

テキスト生成エージェントのレスポンスには、プロバイダーAPI呼び出しの生のHTTPレスポンスを返す `raw` プロパティがあります。レート制限ヘッダーやリクエストIDなど、AI SDKの共通レスポンスに含まれないプロバイダー固有の情報を取得できます。

```php theme={null}
$response = (new SalesCoach)->prompt('Analyze this sales transcript...');

$response->raw; // Illuminate\Http\Client\Response|null

$response->raw->header('X-RateLimit-Remaining-Requests');
$response->raw->json('id');
```

ツール呼び出しループでは、各ステップがそれぞれのリクエストの生レスポンスを保持します。

```php theme={null}
foreach ($response->steps as $step) {
    $step->raw?->header('X-RateLimit-Remaining-Requests');
}
```

> [!NOTE]
>
> ストリーミング、Bedrock（AWS SDK経由でAPIを呼び出すため）、または明示的な `withRawResponse` を指定していないFakeレスポンスでは `raw` は `null` です。

### 会話コンテキスト

`Conversational` インターフェースを実装して `messages()` メソッドを定義すると、過去の会話履歴を AI に渡せます。

`RemembersConversations` トレイトを使うと、会話履歴をデータベースに自動保存・取得できます。

```php theme={null}
use Laravel\Ai\Concerns\RemembersConversations;

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

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

`forUser()` で会話を開始し、返ってきた `conversationId` を使って `continue()` で続きの会話ができます。

```php theme={null}
$response = (new SalesCoach)->forUser($user)->prompt('Hello!');
$conversationId = $response->conversationId;

$response = (new SalesCoach)->continue($conversationId, as: $user)->prompt('Tell me more about that.');
```

### 構造化出力

`HasStructuredOutput` インターフェースを実装し、`schema()` メソッドで JSON スキーマを定義すると、AI のレスポンスを構造化されたデータとして受け取れます。

```php theme={null}
public function schema(JsonSchema $schema): array
{
    return ['score' => $schema->integer()->required()];
}

$response = (new SalesCoach)->prompt('Analyze this...');
return $response['score'];
```

#### ネストされたオブジェクト

```php theme={null}
public function schema(JsonSchema $schema): array
{
    return [
        'score' => $schema->integer()->required(),
        'metadata' => $schema->object(fn ($schema) => [
            'confidence' => $schema->string()->enum(['low', 'medium', 'high'])->required(),
            'language' => $schema->string()->required(),
        ])->required(),
    ];
}
```

#### オブジェクトの配列

```php theme={null}
public function schema(JsonSchema $schema): array
{
    return [
        'feedback' => $schema->array()->items(
            $schema->object(fn ($schema) => [
                'comment' => $schema->string()->required(),
                'score' => $schema->integer()->required(),
            ])
        )->required(),
    ];
}
```

#### anyOf（複数スキーマの選択）

値が複数のスキーマのいずれかにマッチする場合は、`anyOf` メソッドを使います。

```php theme={null}
public function schema(JsonSchema $schema): array
{
    return [
        'content' => $schema->anyOf([
            $schema->object(fn ($schema) => [
                'type' => $schema->string()->enum(['article'])->required(),
                'title' => $schema->string()->required(),
            ]),
            $schema->object(fn ($schema) => [
                'type' => $schema->string()->enum(['image'])->required(),
                'url' => $schema->string()->required(),
            ]),
        ])->required(),
    ];
}
```

### 添付ファイル

`attachments` 引数でドキュメントや画像をエージェントに渡せます。

```php theme={null}
use Laravel\Ai\Files;

$response = (new SalesCoach)->prompt(
    'Analyze the attached sales transcript...',
    attachments: [
        Files\Document::fromStorage('transcript.pdf'),
        Files\Document::fromPath('/home/laravel/transcript.md'),
        $request->file('transcript'),
    ]
);
```

画像の添付も同様に行えます。

```php theme={null}
$response = (new ImageAnalyzer)->prompt('What is in this image?', attachments: [
    Files\Image::fromStorage('photo.jpg'),
    Files\Image::fromPath('/home/laravel/photo.jpg'),
    $request->file('photo'),
]);
```

### ストリーミング

`stream()` メソッドを使うと、レスポンスをチャンク単位で返せます。長いレスポンスをリアルタイムにフロントエンドへ送るのに適しています。

```php theme={null}
Route::get('/coach', function () {
    return (new SalesCoach)->stream('Analyze this sales transcript...');
});
```

`then()` コールバックで、ストリーミング完了後の処理を記述できます。

```php theme={null}
use Laravel\Ai\Responses\StreamedAgentResponse;

Route::get('/coach', function () {
    return (new SalesCoach)
        ->stream('Analyze this sales transcript...')
        ->then(function (StreamedAgentResponse $response) {
            // $response->text, $response->events, $response->usage...
        });
});
```

ストリームを手動でイテレートすることもできます。

```php theme={null}
$stream = (new SalesCoach)->stream('Analyze this sales transcript...');

foreach ($stream as $event) {
    // ...
}
```

#### Vercel AI SDK プロトコル

フロントエンドで Vercel AI SDK を使う場合は `usingVercelDataProtocol()` を呼びます。

```php theme={null}
Route::get('/coach', function () {
    return (new SalesCoach)->stream('Analyze...')->usingVercelDataProtocol();
});
```

### ブロードキャスト

ストリームのイベントを Laravel Echo などのブロードキャストチャンネルに送信できます。

```php theme={null}
use Illuminate\Broadcasting\Channel;

$stream = (new SalesCoach)->stream('Analyze this sales transcript...');

foreach ($stream as $event) {
    $event->broadcast(new Channel('channel-name'));
}
```

`broadcastOnQueue()` を使うと、キューを経由してブロードキャストできます。

```php theme={null}
(new SalesCoach)->broadcastOnQueue(
    'Analyze this sales transcript...',
    new Channel('channel-name'),
);
```

#### 巨大なイベントのスキップ

ブロードキャストプラットフォームによっては WebSocket メッセージを約 10KB に制限しているものがあります。大きなツール結果など、データ量の多いストリームイベントがこの上限を超えてブロードキャストに失敗することがあります。`WithoutBroadcasting` Attribute を使用して、特定のイベントタイプをブロードキャストから除外できます。

```php theme={null}
<?php

namespace App\Ai\Agents;

use Laravel\Ai\Attributes\WithoutBroadcasting;
use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Contracts\HasTools;
use Laravel\Ai\Promptable;
use Laravel\Ai\Streaming\Events\ToolCall;
use Laravel\Ai\Streaming\Events\ToolResult;

#[WithoutBroadcasting(ToolCall::class, ToolResult::class)]
class SearchAgent implements Agent, HasTools
{
    use Promptable;

    // ...
}
```

除外されたイベントはブロードキャストされませんが、`agent_conversation_messages` テーブルへの保存は引き続き行われます。そのため、フロントエンドはストリーム完了後にツールの全データを取得できます。これはキュー経由（`broadcastOnQueue`）と同期（`broadcast` / `broadcastNow`）の両方で機能します。

### キュー

`queue()` メソッドでプロンプトをキューに積んで非同期処理できます。

```php theme={null}
use Laravel\Ai\Responses\AgentResponse;

Route::post('/coach', function (Request $request) {
    (new SalesCoach)
        ->queue($request->input('transcript'))
        ->then(function (AgentResponse $response) { /* ... */ })
        ->catch(function (Throwable $e) { /* ... */ });

    return back();
});
```

### ツール

ツールを使うと、AI がコード内の関数を呼び出せるようになります。`make:tool` コマンドでツールクラスを生成できます。

```shell theme={null}
php artisan make:tool RandomNumberGenerator
```

```php theme={null}
<?php

namespace App\Ai\Tools;

use Illuminate\Contracts\JsonSchema\JsonSchema;
use Laravel\Ai\Contracts\Tool;
use Laravel\Ai\Tools\Request;
use Stringable;

class RandomNumberGenerator implements Tool
{
    public function description(): Stringable|string
    {
        return 'This tool may be used to generate cryptographically secure random numbers.';
    }

    public function handle(Request $request): Stringable|string
    {
        return (string) random_int($request['min'], $request['max']);
    }

    public function schema(JsonSchema $schema): array
    {
        return [
            'min' => $schema->integer()->min(0)->required(),
            'max' => $schema->integer()->required(),
        ];
    }
}
```

エージェントの `tools()` メソッドでツールを登録します。

```php theme={null}
public function tools(): iterable
{
    return [new RandomNumberGenerator];
}
```

#### ツール引数のバリデーション

ツールの `schema` メソッドで受け取る引数の型は制約できますが、モデルが渡す値そのものが正しいとは限りません。リクエストの `validate` メソッドを使ってツールの引数を検証できます。

```php theme={null}
public function handle(Request $request): Stringable|string
{
    $validated = $request->validate([
        'city' => 'required|string',
        'days' => 'required|integer|max:7',
    ]);

    return $this->forecast($validated['city'], $validated['days']);
}
```

バリデーションが失敗すると、エラーメッセージがツールの結果としてモデルに返されるため、モデルは引数を修正して再度ツールを呼び出せます。

#### 類似検索ツール

ベクター埋め込みを使った類似検索ツールを簡単に追加できます。

```php theme={null}
use App\Models\Document;
use Laravel\Ai\Tools\SimilaritySearch;

public function tools(): iterable
{
    return [
        SimilaritySearch::usingModel(Document::class, 'embedding'),
    ];
}
```

オプションを指定することもできます。

```php theme={null}
SimilaritySearch::usingModel(
    model: Document::class,
    column: 'embedding',
    minSimilarity: 0.7,
    limit: 10,
    query: fn ($query) => $query->where('published', true),
),
```

クロージャで独自の検索ロジックを定義することもできます。

```php theme={null}
new SimilaritySearch(using: function (string $query) {
    return Document::query()
        ->where('user_id', $this->user->id)
        ->whereVectorSimilarTo('embedding', $query)
        ->limit(10)
        ->get();
}),
```

`withDescription()` でツールの説明をカスタマイズできます。

```php theme={null}
SimilaritySearch::usingModel(Document::class, 'embedding')
    ->withDescription('Search the knowledge base for relevant articles.'),
```

### ファイルストレージツール

`FileStorage` ツールファクトリーを使うと、エージェントに Laravel [ファイルシステムディスク](https://kawax.biz/jp/filesystem.md)へのアクセスを与えられます。`all` メソッドは、指定ディスク上のファイルを一覧・読み取り・URL 生成・書き込み・削除・コピーするツール一式を返します。

```php theme={null}
use Laravel\Ai\Tools\FileStorage;

public function tools(): iterable
{
    return FileStorage::all('local');
}
```

読み取り専用のアクセスだけを許可する場合は `readOnly` メソッドを使います。

```php theme={null}
return FileStorage::readOnly('local');
```

これらのメソッドは `Illuminate\Support\Collection` を返すため、提供するツールをさらに絞り込めます。

```php theme={null}
use Laravel\Ai\Tools\Filesystem\DeleteFile;

return FileStorage::all('s3')
    ->reject(fn ($tool) => $tool instanceof DeleteFile);
```

### MCP ツール

アプリケーションで [Laravel MCP](https://kawax.biz/jp/mcp.md) を使っている場合、[Model Context Protocol](https://modelcontextprotocol.io) サーバーが公開するツールをエージェントに提供できます。[Laravel MCP クライアント](https://kawax.biz/jp/mcp.md#mcp-クライアント)を使って、リモートまたはローカルの MCP サーバーに接続し、そのツールをエージェントに直接渡すことができます。

> [!NOTE]
>
> MCP ツールを使用するには、アプリケーションに [Laravel MCP](https://kawax.biz/jp/mcp.md) パッケージがインストールされている必要があります。

MCP クライアントの `tools` メソッドはコレクションを返すため、`...` スプレッド演算子を使ってエージェントの `tools` 配列に展開します。

```php theme={null}
use App\Ai\Tools\RandomNumberGenerator;
use Laravel\Mcp\Client;

/**
 * Get the tools available to the agent.
 *
 * @return Tool[]
 */
public function tools(): iterable
{
    return [
        ...Client::web('https://mcp.example.com')
            ->withToken($token)
            ->tools(),

        new RandomNumberGenerator,
    ];
}
```

AI SDK は各 MCP ツールを自動的にラップし、エージェントが他のツールと同様に呼び出せるようにします。[名前付き MCP クライアント](https://kawax.biz/jp/mcp.md#名前付きクライアント) を使うこともできます。

```php theme={null}
use Laravel\Mcp\Facades\Mcp;

public function tools(): iterable
{
    return [
        ...Mcp::client('github')->tools(),
    ];
}
```

または、[ローカル MCP サーバー](https://kawax.biz/jp/mcp.md#ローカルサーバー) に接続することも可能です。

```php theme={null}
use Laravel\Mcp\Client;

public function tools(): iterable
{
    return [
        ...Client::local('php', ['artisan', 'mcp:start'])->tools(),
    ];
}
```

MCP クライアントの作成と認証（Bearer トークンや OAuth など）については、[MCP クライアントのドキュメント](https://kawax.biz/jp/mcp.md#mcp-クライアント) を参照してください。

### プロバイダーツール

AI プロバイダーがネイティブで実装している特別なツールです。

#### Web 検索

ウェブ検索をエージェントに追加します。Anthropic・OpenAI・Azure・Gemini・xAI・OpenRouter に対応しています。

```php theme={null}
use Laravel\Ai\Providers\Tools\WebSearch;

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

オプションで検索件数やドメインの絞り込み、位置情報の指定ができます。

```php theme={null}
(new WebSearch)->max(5)->allow(['laravel.com', 'php.net']),
(new WebSearch)->location(city: 'New York', region: 'NY', country: 'US');
```

#### Web フェッチ

指定した URL のコンテンツを取得するツールです。Anthropic・Gemini・OpenRouter に対応しています。

```php theme={null}
use Laravel\Ai\Providers\Tools\WebFetch;

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

(new WebFetch)->max(3)->allow(['docs.laravel.com']),
```

#### ファイル検索

ベクターストアからドキュメントを検索するツールです。OpenAI・Gemini・xAI に対応しています。

```php theme={null}
use Laravel\Ai\Providers\Tools\FileSearch;

public function tools(): iterable
{
    return [new FileSearch(stores: ['store_id'])];
}

// 複数のストアを指定
new FileSearch(stores: ['store_1', 'store_2']);

// メタデータでフィルタリング
new FileSearch(stores: ['store_id'], where: ['author' => 'Taylor Otwell', 'year' => 2026]);
```

`FileSearchQuery` を使った複雑なフィルターも指定できます。

```php theme={null}
use Laravel\Ai\Providers\Tools\FileSearchQuery;

new FileSearch(stores: ['store_id'], where: fn (FileSearchQuery $query) =>
    $query->where('author', 'Taylor Otwell')
          ->whereNot('status', 'draft')
          ->whereIn('category', ['news', 'updates'])
);
```

### 遅延ツール読み込み

エージェントが公開するすべてのツールは、デフォルトではリクエストごとにプロバイダーへ送信されます。ツールが多いエージェントではトークンを消費し、モデルのツール選択精度が下がることがあります。OpenAI または Anthropic では `ToolSearch` プロバイダーツールを使い、必要なときだけツール定義を読み込むよう遅延できます。

```php theme={null}
use App\Ai\Tools\RefundOrder;
use App\Ai\Tools\SearchInvoices;
use App\Ai\Tools\Weather;
use Laravel\Ai\Providers\Tools\ToolSearch;

public function tools(): iterable
{
    return [
        new Weather,
        new ToolSearch(tools: [
            new SearchInvoices,
            new RefundOrder,
        ]),
    ];
}
```

ラップしたツール自体を変更する必要はありません。プロバイダーがプロンプトに関連するツールを検索して読み込み、通常のツールと同じように呼び出します。

Anthropic では `strategy` 引数で検索方法を指定できます。利用できる戦略はデフォルトの `regex` と `bm25` です。

```php theme={null}
new ToolSearch(tools: [new SearchInvoices], strategy: 'bm25'),
```

Anthropic 固有のオプションは `withProviderOptions` メソッドで渡せます。

```php theme={null}
(new ToolSearch(tools: [new SearchInvoices]))
    ->withProviderOptions(['cache_control' => ['type' => 'ephemeral']]),
```

> [!WARNING]
>
> ツール検索に対応していないプロバイダーは、遅延ツールを黙って破棄せず例外をスローします。Anthropic では `ToolSearch` の外側にも少なくとも1つのツールが必要です。

### ツール呼び出しの修復

モデルが存在しないローカルツールを呼び出したときに、エージェントがその呼び出しを修復できるようにするには `RepairToolCalls` アトリビュートを使います。Laravelは失敗した呼び出しと利用可能なローカルツールの名前をモデルへ返すため、モデルは呼び出しを修正できます。

```php theme={null}
use Laravel\Ai\Attributes\RepairToolCalls;
use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Contracts\HasTools;
use Laravel\Ai\Promptable;

#[RepairToolCalls]
class SupportAgent implements Agent, HasTools
{
    use Promptable;

    // ...
}
```

Laravelが最大ステップ数を自動的に決定する場合、このアトリビュートによる修復呼び出しのために1ステップが追加されます。`MaxSteps` で明示的に上限を指定した場合、その上限は変わりません。

### サブエージェント

エージェントは別のエージェントの `tools()` メソッドから返すこともできます。エージェントをツールとして登録すると、親エージェントが特定のタスクをサブエージェントに委譲し、その結果を元の応答に組み込めます。汎用エージェントが専門的な指示・ツール・モデル設定・プロバイダー設定を持つ特化型エージェントにアクセスするときに便利です。

たとえば、カスタマーサポートエージェントが返金ポリシーの質問を返金専門エージェントに委譲する例です。

```php theme={null}
<?php

namespace App\Ai\Agents;

use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Contracts\HasTools;
use Laravel\Ai\Promptable;

class CustomerSupportAgent implements Agent, HasTools
{
    use Promptable;

    public function instructions(): string
    {
        return 'You help customers with account, order, and billing questions. Delegate refund policy questions to the refunds specialist.';
    }

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

親エージェントへのサブエージェントの見せ方をカスタマイズするには、サブエージェントに `CanActAsTool` インターフェースを実装し、ツール用の名前と説明を定義します。

```php theme={null}
<?php

namespace App\Ai\Agents;

use App\Ai\Tools\LookupOrder;
use Laravel\Ai\Attributes\Provider;
use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Contracts\CanActAsTool;
use Laravel\Ai\Contracts\HasTools;
use Laravel\Ai\Enums\Lab;
use Laravel\Ai\Promptable;

#[Provider(Lab::Anthropic)]
class RefundsAgent implements Agent, CanActAsTool, HasTools
{
    use Promptable;

    public function instructions(): string
    {
        return 'You are a refunds specialist. Use order details and the refund policy to give concise eligibility guidance.';
    }

    public function name(): string
    {
        return 'refunds_specialist';
    }

    public function description(): string
    {
        return 'Determine whether an order is eligible for a refund and explain the next step.';
    }

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

`CanActAsTool` を実装しないサブエージェントの場合、Laravel はクラス名をツール名として使用し、汎用的な説明文を自動で生成します。各サブエージェントの呼び出しは独立して行われ、親エージェントの会話履歴は引き継ぎません。

> [!WARNING]
>
> サブエージェントは現在、[人間による承認](#人間による承認（human-tool-approval）)が必要なツールには対応していません。サブエージェントのツールが承認を必要とする場合、サブエージェントは一時停止しますが、親エージェントは通常のツール結果を受け取り、保留中の承認がアプリケーションに通知されることなく実行を続けます。承認が必要なツールはトップレベルのエージェントに登録してください。

親エージェントが[ストリーミング](#ストリーミング)している場合、サブエージェントも一緒にストリーミングします。ただし、[構造化出力](#構造化出力)を生成する場合は除きます。ストリーミングするサブエージェントについては、親エージェントが、サブエージェントがこれまでに生成したテキストを含む予備的な `ToolResult` イベントを発行します。ツール呼び出しの最終結果はこれらのイベントの後に続くため、イベントを手動でイテレートするときは予備的なイベントをスキップできます。

```php theme={null}
use Laravel\Ai\Streaming\Events\ToolResult;

foreach ($stream as $event) {
    if ($event instanceof ToolResult && $event->preliminary) {
        continue;
    }

    // ...
}
```

`text`、`usage`、`toolResults` などのレスポンス値は、予備的なイベントを無視します。[Vercel AI SDK ストリームプロトコル](#vercel-ai-sdk-プロトコル)はそれらをネイティブのストリーミングツール出力として描画するため、`useChat` はカスタムコードなしで進捗を表示します。一方、AG-UI プロトコルはそれらをアクティビティのスナップショットとして報告します。サブエージェントの最終テキストはツール呼び出しの結果となり、完了したレスポンスの `toolResults` から取得できます。完了したレスポンスの `text`、`reasoning`、`citations`、`usage` に含まれるのは、親エージェント自身の出力のみです。サブエージェントの使用量を追跡するには、`AgentStreamed` [イベント](#イベント)をリスニングし、イベントの `prompt->parentInvocationId` と親レスポンスの `invocationId` を比較します。

### ミドルウェア

エージェントの**モデル呼び出しごと**にミドルウェアを実行できます。`make:agent-middleware` でクラスを作成し、エージェントで `HasMiddleware` を実装して登録します。

```shell theme={null}
php artisan make:agent-middleware LogAgentSteps
```

```php theme={null}
<?php

namespace App\Ai\Agents;

use App\Ai\Middleware\LogAgentSteps;
use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Contracts\HasMiddleware;
use Laravel\Ai\Promptable;

class SalesCoach implements Agent, HasMiddleware
{
    use Promptable;

    public function instructions(): string
    {
        return 'Answer sales questions concisely.';
    }

    public function middleware(): array
    {
        return [new LogAgentSteps];
    }
}
```

ミドルウェアの `handle()` には、これから実行するステップを表す `PendingStep` が渡されます。`then()` に登録した処理はモデルの応答後、ツールの実行前に動きます。

```php theme={null}
<?php

namespace App\Ai\Middleware;

use Closure;
use Illuminate\Support\Facades\Log;
use Laravel\Ai\Gateway\StepResponse;
use Laravel\Ai\PendingStep;

class LogAgentSteps
{
    public function handle(PendingStep $step, Closure $next)
    {
        Log::info('AI step starting', ['step' => $step->number]);

        return $next($step)->then(function (StepResponse $response) use ($step): void {
            Log::info('AI model responded', ['step' => $step->number]);
        });
    }
}
```

ステップごとの実行順、累積トークンを使った `Stop::when()`、途中停止時の振る舞いは[エージェントミドルウェアの応用](https://kawax.biz/jp/advanced/ai-sdk-agent-middleware.md)を参照してください。

### 匿名エージェント

クラスを定義せずに `agent()` ヘルパーで匿名エージェントを使えます。

```php theme={null}
use function Laravel\Ai\{agent};

$response = agent(
    instructions: 'You are an expert at software development.',
    messages: [],
    tools: [],
)->prompt('Tell me about Laravel');
```

構造化出力付きの匿名エージェントも作成できます。

```php theme={null}
use Illuminate\Contracts\JsonSchema\JsonSchema;

$response = agent(
    schema: fn (JsonSchema $schema) => ['number' => $schema->integer()->required()],
)->prompt('Generate a random number less than 100');
```

### エージェント設定（PHP Attributes）

PHP Attribute を使ってエージェントのデフォルト設定を宣言的に記述できます。

| Attribute | 説明 |
| - | - |
| `#[Provider]` | 使用するプロバイダーを指定 |
| `#[Model]` | 使用するモデルを指定 |
| `#[MaxSteps]` | ツール呼び出しの最大ステップ数 |
| `#[MaxTokens]` | 最大トークン数 |
| `#[Temperature]` | 温度パラメーター（0.0〜1.0） |
| `#[TopP]` | 核サンプリングの確率（0.0〜1.0） |
| `#[Timeout]` | タイムアウト（秒） |
| `#[UseCheapestModel]` | 最安値モデルを自動選択 |
| `#[UseSmartestModel]` | 最高性能モデルを自動選択 |

```php theme={null}
<?php

namespace App\Ai\Agents;

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\TopP;
use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Enums\Lab;
use Laravel\Ai\Promptable;

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

モデル選択のショートカット Attribute も用意されています。

```php theme={null}
// 最も安価なモデルを使う
#[UseCheapestModel]
class SimpleSummarizer implements Agent
{
    use Promptable;
}

// 最も高性能なモデルを使う
#[UseSmartestModel]
class ComplexReasoner implements Agent
{
    use Promptable;
}
```

### プロバイダーオプション

`HasProviderOptions` インターフェースを実装すると、プロバイダー固有のオプションを渡せます。

```php theme={null}
<?php

namespace App\Ai\Agents;

use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Contracts\HasProviderOptions;
use Laravel\Ai\Enums\Lab;
use Laravel\Ai\Promptable;

class SalesCoach implements Agent, HasProviderOptions
{
    use Promptable;

    public function providerOptions(Lab|string $provider): array
    {
        return match ($provider) {
            Lab::OpenAI => [
                'reasoning' => ['effort' => 'low'],
                'frequency_penalty' => 0.5,
                'presence_penalty' => 0.3,
            ],
            Lab::Anthropic => [
                'thinking' => ['budget_tokens' => 1024],
            ],
            default => [],
        };
    }
}
```

`providerOptions` メソッドには現在使用中のプロバイダー（`Lab` enumまたは文字列）が渡されるため、プロバイダーごとに異なるオプションを返せます。各フォールバックプロバイダーに個別の設定を渡せるため、[フェイルオーバー](#フェイルオーバー)使用時に特に便利です。

上記の Anthropic の例では `cache_control` によって[プロンプトキャッシュ](#プロンプトキャッシュ)も有効化しています。

### プロンプトキャッシュ

多くのプロバイダーは繰り返されるプロンプトの接頭辞を自動的にキャッシュし、キャッシュされた部分を割引価格で課金します。OpenAI、Gemini、Groq、DeepSeek、xAI は設定不要で、レスポンスの usage から節約分を確認できます。

```php theme={null}
$response->usage->cacheReadInputTokens;
$response->usage->cacheWriteInputTokens;
```

`anthropic` と `bedrock` プロバイダーは明示的に指示した場合のみキャッシュします。`CacheInstructions` と `CacheToolDefinitions` 属性を使うと、エージェントの指示とツール定義の末尾にキャッシュのブレークポイントを配置できます。これにより、すべての会話がその接頭辞をキャッシュから読み込むようになり、毎回書き込む必要がなくなります。

```php theme={null}
use Laravel\Ai\Attributes\CacheInstructions;
use Laravel\Ai\Attributes\CacheToolDefinitions;

#[CacheInstructions]
#[CacheToolDefinitions]
class SalesCoach implements Agent
{
    use Promptable;

    // ...
}
```

現在の日付を埋め込むなど、リクエストごとに指示の内容が変わる場合は `CacheToolDefinitions` のみを使用してください。リクエストごとに変わる接頭辞をキャッシュすると、毎回新しいキャッシュエントリが作られてしまい、再利用されないまま書き込みコストだけがかかります。

これらの属性をサポートしないプロバイダーは単に無視するため、[フェイルオーバー](#フェイルオーバー)使用時でも安全に宣言できます。

キャッシュされた接頭辞はデフォルトで5分間保持されます。Anthropic では属性にTTLを渡すことで1時間まで保持できます。

```php theme={null}
#[CacheInstructions('1h')]
#[CacheToolDefinitions('1h')]
```

また、トップレベルの `cache_control` [プロバイダーオプション](#プロバイダーオプション)によって Anthropic の自動キャッシュを有効化することもできます。これはリクエストの最後のブロックの後に単一のブレークポイントを配置する方式で、会話が進むにつれてブレークポイントも進み、各ターンが前のターンをキャッシュから読み込みます。両方の仕組みを組み合わせることも可能です。

> [!WARNING]
>
> プロバイダーはツール、指示、メッセージの順にプロンプトを構築するため、指示を1時間キャッシュする場合はツール定義も1時間キャッシュする必要があります。この2つを混在させると `InvalidArgumentException` がスローされます。

***

## 人間による承認（Human Tool Approval）

> [!WARNING]
>
> ツール承認を利用するには、会話履歴が永続化される`Conversational`エージェントが必要です。一時停止した呼び出しを再開するために、`RemembersConversations`トレイトが必要な永続化機能を提供します。

ファイルの削除や送金など、機密性の高い操作や取り消せない操作を行うツールには、実行前に人間の承認を要求できます。ツールを承認対象にするには、`Approvable`コントラクトを実装し`InteractsWithApprovals`トレイトを使用します。承認対象のツールはデフォルトで承認が必須になります。

```php theme={null}
<?php

namespace App\Ai\Tools;

use Illuminate\Contracts\JsonSchema\JsonSchema;
use Illuminate\Support\Facades\Storage;
use Laravel\Ai\Concerns\InteractsWithApprovals;
use Laravel\Ai\Contracts\Approvable;
use Laravel\Ai\Contracts\Tool;
use Laravel\Ai\Tools\Request;
use Stringable;

class DeleteFile implements Approvable, Tool
{
    use InteractsWithApprovals;

    /**
     * ツールの目的の説明を取得
     */
    public function description(): Stringable|string
    {
        return 'ストレージからファイルを削除する。';
    }

    /**
     * ツールを実行
     */
    public function handle(Request $request): Stringable|string
    {
        Storage::delete($request['path']);

        return "削除しました：[{$request['path']}]";
    }

    /**
     * ツールのスキーマ定義を取得
     */
    public function schema(JsonSchema $schema): array
    {
        return [
            'path' => $schema->string()->required(),
        ];
    }
}
```

ツール呼び出しの引数に応じて承認の要否を判定したい場合は、ツールに`needsApproval`メソッドを定義します。このメソッドは真偽値か、承認理由を含む`Approval`インスタンスを返せます。

```php theme={null}
use Laravel\Ai\Approvals\Approval;

/**
 * 与えられたリクエストに対してツールが承認を必要とするか判定
 */
protected function needsApproval(Request $request): Approval|bool
{
    return str_starts_with($request['path'], 'temporary/')
        ? false
        : Approval::required('このファイルは完全に削除されます。');
}
```

エージェントの`tools`メソッドからツールを返す際に、承認要件を上書きすることもできます。

```php theme={null}
public function tools(): iterable
{
    return [
        (new SendNotification)->withoutApproval(),
        (new DeleteFile)->requireApproval('削除には確認が必要です。'),
    ];
}
```

承認対象のツールが呼び出されると、エージェントは実行前に一時停止します。レスポンスの`pendingApprovals`を調べることで、各ツール呼び出しのID・ツール名・引数・承認理由を確認できます。

```php theme={null}
$response = (new FileAssistant)
    ->forUser($user)
    ->prompt('古い請求書を削除して。');

if ($response->hasPendingApprovals()) {
    foreach ($response->pendingApprovals as $approval) {
        // $approval->id
        // $approval->tool
        // $approval->arguments
        // $approval->reason
    }
}
```

エージェントを再開するには、会話を継続し、保留中の各ツール呼び出しに対する決定を含む`Decisions`インスタンスを渡します。決定では呼び出しの承認・却下・実行前の引数の編集が行えます。

```php theme={null}
use Laravel\Ai\Approvals\Decision;
use Laravel\Ai\Approvals\Decisions;

$response = (new FileAssistant)
    ->continue($conversationId, as: $user)
    ->prompt(Decisions::from([
        'call_abc' => Decision::approve(),
        'call_ghi' => Decision::reject('この請求書は保管が必要です。'),
    ]));
```

真偽値の`true`・`false`は、それぞれ承認・却下の省略記法として使えます。保留中のすべてのツール呼び出しには決定が必要です。不明・欠落・すでに解決済みのツール呼び出しIDを指定すると`ApprovalMismatchException`がスローされます。明示的な決定がない呼び出しに対しては、`approveRemaining`または`rejectRemaining`メソッドでデフォルトの決定を指定できます。

```php theme={null}
$decisions = Decisions::from([
    'call_abc' => true,
])->rejectRemaining('承認されませんでした。');

$response = (new FileAssistant)
    ->continue($conversationId, as: $user)
    ->prompt($decisions);
```

`Decision::reject('承認されませんでした。')`のように結果付きで却下すると、モデルに返されて応答が継続されます。結果なしで却下すると、却下が記録された時点で生成ループが停止します。

ツール承認は`prompt`・`stream`・`queue`・`broadcast`・`broadcastNow`・`broadcastOnQueue`メソッドでサポートされています。

ストリーミングおよびブロードキャスト中は、一時停止が`tool_approval_request`イベントとして表現されます。[Vercel AI SDK ストリームプロトコル](#vercel-ai-sdk-プロトコル)を使用している場合、承認リクエストと結果はプロトコルのネイティブなツール承認パートとして送出されます。

キューイングされたエージェントの場合、結果のレスポンスは`then`コールバックに渡され、Laravel は`ToolApprovalRequested`イベントもディスパッチします。

Laravel は、モデルに続行を求める前に、承認済みツールの実行結果を保存します。その後に生成が失敗した場合、承認はすでに解決済みです。同じ承認決定を再送するのではなく、通常のテキストプロンプトで会話を継続してください。

### 完全な承認フロー

以下のルートは、完全な承認フローを示します。`GET`ルートはチャット画面を返し、`POST`ルートはチャット画面からの新しいテキストプロンプトまたは承認決定のいずれかを受け取ります。この例では、アプリケーションの`User`モデルが`HasConversations`トレイトを使用していることを前提としています。

```php theme={null}
use App\Ai\Agents\FileAssistant;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Gate;
use Illuminate\Support\Facades\Route;
use Illuminate\Validation\Rule;
use Laravel\Ai\Approvals\Decision;
use Laravel\Ai\Approvals\Decisions;
use Laravel\Ai\Models\Conversation;

Route::get('/chat/{conversation}', function (Request $request, Conversation $conversation) {
    Gate::authorize('view', $conversation);

    return view('chat', [
        'conversation' => $conversation,
    ]);
})->middleware('auth');

Route::post('/chat/{conversation}', function (Request $request, Conversation $conversation) {
    Gate::authorize('view', $conversation);

    $validated = $request->validate([
        'message' => ['nullable', 'string', 'required_without:decisions', 'prohibits:decisions'],
        'decisions' => ['nullable', 'array', 'required_without:message', 'prohibits:message'],
        'decisions.*.action' => ['required_with:decisions', Rule::in(['approve', 'reject'])],
        'decisions.*.result' => ['nullable', 'string'],
    ]);

    $prompt = isset($validated['decisions'])
        ? Decisions::from(collect($validated['decisions'])->map(
            fn (array $decision) => match ($decision['action']) {
                'approve' => Decision::approve(),
                'reject' => Decision::reject($decision['result'] ?? null),
            }
        )->all())
        : $validated['message'];

    $response = (new FileAssistant)
        ->continue($conversation->id, as: $request->user())
        ->prompt($prompt);

    return [
        'conversation_id' => $response->conversationId,
        'status' => $response->hasPendingApprovals() ? 'awaiting_approval' : 'complete',
        'message' => $response->text,
        'approvals' => $response->pendingApprovals,
    ];
})->middleware('auth');
```

レスポンスのステータスが`awaiting_approval`の場合、チャット画面は保留中の承認を表示し、ツール呼び出しIDをキーとしてユーザーの選択を同じエンドポイントに送信する必要があります。

```json theme={null}
{
    "decisions": {
        "call_abc": {
            "action": "approve"
        },
        "call_def": {
            "action": "reject",
            "result": "この請求書は保管が必要です。"
        }
    }
}
```

通常のチャットメッセージの場合は、代わりに`message`の値を送信します。

```json theme={null}
{
    "message": "古い請求書を削除して。"
}
```

> [!TIP]
>
> 承認フローはAIエージェントに強力な操作権限を与えつつ、実行前に人間のチェックを挟める仕組みです。ファイル削除・決済処理・外部APIへの書き込みなど、取り消しの効かない操作を伴うツールでは積極的に活用しましょう。

***

## 画像生成

`Image` クラスで画像を生成できます。OpenAI・Gemini・xAI プロバイダーが対応しています。

```php theme={null}
use Laravel\Ai\Image;

$image = Image::of('A donut sitting on the kitchen counter')->generate();
$rawContent = (string) $image;
```

品質やアスペクト比・タイムアウトを指定できます。

```php theme={null}
$image = Image::of('A donut sitting on the kitchen counter')
    ->quality('high')
    ->landscape()
    ->timeout(120)
    ->generate();
```

参照画像を添付して加工することもできます。

```php theme={null}
use Laravel\Ai\Files;

$image = Image::of('Update this photo to be in the style of an impressionist painting.')
    ->attachments([Files\Image::fromStorage('photo.jpg')])
    ->landscape()
    ->generate();
```

### 画像の保存

```php theme={null}
$path = $image->store();
$path = $image->storeAs('image.jpg');
$path = $image->storePublicly();
$path = $image->storePubliclyAs('image.jpg');
```

### キューで画像生成

```php theme={null}
use Laravel\Ai\Responses\ImageResponse;

Image::of('A donut sitting on the kitchen counter')
    ->portrait()
    ->queue()
    ->then(function (ImageResponse $image) {
        $path = $image->store();
    });
```

***

## 音声合成（TTS）

`Audio` クラスでテキストを音声に変換できます。OpenAI・ElevenLabs プロバイダーが対応しています。

```php theme={null}
use Laravel\Ai\Audio;

$audio = Audio::of('I love coding with Laravel.')->generate();
$rawContent = (string) $audio;
```

声の性別や具体的なボイス ID、話し方の指示も指定できます。

```php theme={null}
$audio = Audio::of('I love coding with Laravel.')->female()->generate();
$audio = Audio::of('I love coding with Laravel.')->voice('voice-id-or-name')->generate();
$audio = Audio::of('I love coding with Laravel.')->female()->instructions('Said like a pirate')->generate();
```

### 音声の保存

```php theme={null}
$path = $audio->store();
$path = $audio->storeAs('audio.mp3');
$path = $audio->storePublicly();
$path = $audio->storePubliclyAs('audio.mp3');
```

### キューで音声生成

```php theme={null}
use Laravel\Ai\Responses\AudioResponse;

Audio::of('I love coding with Laravel.')
    ->queue()
    ->then(function (AudioResponse $audio) {
        $path = $audio->store();
    });
```

***

## 文字起こし（STT）

`Transcription` クラスで音声ファイルをテキストに変換できます。OpenAI・OpenAI Compatible・ElevenLabs・Groq・Mistral・Gemini プロバイダーが対応しています。

```php theme={null}
use Laravel\Ai\Transcription;

$transcript = Transcription::fromPath('/home/laravel/audio.mp3')->generate();
$transcript = Transcription::fromStorage('audio.mp3')->generate();
$transcript = Transcription::fromUpload($request->file('audio'))->generate();

return (string) $transcript;
```

### 話者分離（ダイアリゼーション）

`diarize()` を使うと、話者ごとに分離した文字起こしが得られます。

```php theme={null}
$transcript = Transcription::fromStorage('audio.mp3')->diarize()->generate();
```

### キューで文字起こし

```php theme={null}
use Laravel\Ai\Responses\TranscriptionResponse;

Transcription::fromStorage('audio.mp3')
    ->queue()
    ->then(function (TranscriptionResponse $transcript) { /* ... */ });
```

***

## テキスト要約（Text Summarization）

Laravel の `Stringable` クラスが提供する `summarize` メソッドで、テキストを要約できます。デフォルトでは3文以内に要約され、設定されたプロバイダーの最も安価なテキストモデルが使われます。

```php theme={null}
use Illuminate\Support\Str;

$summary = Str::of($article)->summarize();
```

要約に使う文の最大数・プロバイダー・モデル・タイムアウトを指定することもできます。`Str` クラスには静的メソッド版も用意されています。

```php theme={null}
use Laravel\Ai\Enums\Lab;

$summary = Str::of($article)->summarize(
    sentences: 4,
    provider: Lab::Anthropic,
    model: 'claude-sonnet-5',
    timeout: 30,
);

$summary = Str::summarize($article, sentences: 4);
```

***

## 埋め込み（Embeddings）

テキストをベクター表現に変換して、類似検索などに活用できます。

```php theme={null}
use Illuminate\Support\Str;

// Stringable を使う方法
$embeddings = Str::of('Napa Valley has great wine.')->toEmbeddings();
```

```php theme={null}
use Laravel\Ai\Embeddings;

// 複数のテキストを一度に処理
$response = Embeddings::for(['Napa Valley has great wine.', 'Laravel is a PHP framework.'])->generate();
$response->embeddings; // [[0.123, 0.456, ...], [0.789, 0.012, ...]]
```

プロバイダー・モデル・次元数を指定することもできます。

```php theme={null}
$response = Embeddings::for(['Napa Valley has great wine.'])
    ->dimensions(1536)
    ->generate(Lab::OpenAI, 'text-embedding-3-small');
```

### マルチモーダル埋め込み（Multimodal Embeddings）

`Embeddings::for` メソッドは文字列だけでなく、画像・音声・ドキュメント・動画の入力も受け付けるため、テキスト以外のコンテンツに対しても埋め込みを生成できます。Gemini は画像・音声・ドキュメント・動画の埋め込みに対応し、VoyageAI は画像・動画の埋め込みに対応しています。

```php theme={null}
use Laravel\Ai\Embeddings;
use Laravel\Ai\Enums\Lab;
use Laravel\Ai\Files\Image;
use Laravel\Ai\Files\Video;

$response = Embeddings::for([
    'A vineyard at sunset.',
    Image::fromStorage('vineyard.jpg'),
    Video::fromPath('/home/laravel/tour.mp4'),
])->generate(Lab::Gemini);
```

マルチモーダル入力には[添付ファイルで使われるものと同じファイルクラス](#添付ファイル)を使います。これらのファイルはローカルパス、ファイルシステムディスク、リモート URL、Base64 エンコードされたコンテンツから作成できます。画像・ドキュメント・動画はアップロードされたファイルからも作成でき、ドキュメントは生の文字列コンテンツからも作成できます。

```php theme={null}
use Laravel\Ai\Files\Audio;
use Laravel\Ai\Files\Document;
use Laravel\Ai\Files\Image;
use Laravel\Ai\Files\Video;

Image::fromPath('/home/laravel/photo.jpg');
Image::fromStorage('photo.jpg');
Image::fromUpload($request->file('photo'));

Audio::fromPath('/home/laravel/clip.mp3');
Audio::fromStorage('clip.mp3');

Video::fromPath('/home/laravel/video.mp4');
Video::fromStorage('video.mp4');
Video::fromUpload($request->file('video'));

Document::fromUrl('https://example.com/report.pdf');
Document::fromString('Laravel is a PHP framework.', 'text/plain');
Document::fromUpload($request->file('report'));
```

> [!NOTE]
>
> VoyageAI はリモート URL のメディアと Base64 エンコードされたメディアを同一リクエスト内で混在させることを許可していません。ローカル・ストレージ・アップロードされたファイルは Base64 エンコードされたコンテンツとして送信され、テキスト入力はどちらのメディアソースとも組み合わせられます。利用可能なマルチモーダルモデルと入力については、各プロバイダーのドキュメントを確認してください。

### ベクター検索（pgvector）

PostgreSQL と pgvector 拡張を使ったベクター検索の設定例です。

**1. マイグレーションの作成**

```php theme={null}
Schema::ensureVectorExtensionExists();

Schema::create('documents', function (Blueprint $table) {
    $table->id();
    $table->string('title');
    $table->text('content');
    $table->vector('embedding', dimensions: 1536);
    $table->timestamps();
});

// HNSW インデックスを追加
$table->vector('embedding', dimensions: 1536)->index();
```

**2. モデルの設定**

```php theme={null}
use Illuminate\Database\Eloquent\Casts\AsVector;

protected function casts(): array
{
    return ['embedding' => AsVector::class];
}
```

**3. 類似検索クエリ**

```php theme={null}
// 埋め込みベクターで検索
$documents = Document::query()
    ->whereVectorSimilarTo('embedding', $queryEmbedding, minSimilarity: 0.4)
    ->limit(10)
    ->get();

// 文字列を渡すと自動で埋め込みを生成
$documents = Document::query()
    ->whereVectorSimilarTo('embedding', 'best wineries in Napa Valley')
    ->limit(10)
    ->get();
```

低レベルのメソッドも利用できます。

```php theme={null}
$documents = Document::query()
    ->select('*')
    ->selectVectorDistance('embedding', $queryEmbedding, as: 'distance')
    ->whereVectorDistanceLessThan('embedding', $queryEmbedding, maxDistance: 0.3)
    ->orderByVectorDistance('embedding', $queryEmbedding)
    ->limit(10)
    ->get();
```

### 埋め込みのキャッシュ

同じテキストの埋め込み生成を繰り返さないようにキャッシュできます。

`config/ai.php` でデフォルトのキャッシュ設定を行います。

```php theme={null}
'caching' => [
    'embeddings' => [
        'cache' => true,
        'store' => env('CACHE_STORE', 'database'),
        'individually' => true,
        // ...
    ],
],
```

キャッシュが有効な場合、埋め込みは30日間キャッシュされます。キャッシュキーはプロバイダー、モデル、次元数、入力コンテンツを元に生成されるため、同一のリクエストはキャッシュされた結果を返し、異なる設定では新規に生成されます。

デフォルトでは各入力の埋め込みが個別のキーでキャッシュされるため、入力の集合や順序が変わっても、以前に見た入力に対してはキャッシュがヒットします。入力全体をひとつのキーでキャッシュしたい場合は、`ai.caching.embeddings.individually` 設定を `false` にしてください。

リクエストごとにキャッシュを制御することもできます。

```php theme={null}
$response = Embeddings::for(['Napa Valley has great wine.'])->cache()->generate();
$response = Embeddings::for(['Napa Valley has great wine.'])->cache(seconds: 3600)->generate();

// Stringable でも同様
$embeddings = Str::of('Napa Valley has great wine.')->toEmbeddings(cache: true);
$embeddings = Str::of('Napa Valley has great wine.')->toEmbeddings(cache: 3600);
```

***

## リランキング

検索結果をクエリへの関連度でリランク（並び替え）できます。Cohere・Jina プロバイダーが対応しています。

```php theme={null}
use Laravel\Ai\Reranking;

$response = Reranking::of([
    'Django is a Python web framework.',
    'Laravel is a PHP web application framework.',
    'React is a JavaScript library for building user interfaces.',
])->rerank('PHP frameworks');

$response->first()->document; // "Laravel is a PHP web application framework."
$response->first()->score;    // 0.95
$response->first()->index;    // 1
```

`limit()` で返す件数を絞り込めます。

```php theme={null}
$response = Reranking::of($documents)->limit(5)->rerank('search query');
```

### コレクションのリランキング

Eloquent コレクションを直接リランクできます。

```php theme={null}
// 単一フィールド
$posts = Post::all()->rerank('body', 'Laravel tutorials');

// 複数フィールド（JSON として送信）
$reranked = $posts->rerank(['title', 'body'], 'Laravel tutorials');

// クロージャで独自のテキスト生成
$reranked = $posts->rerank(fn ($post) => $post->title.': '.$post->body, 'Laravel tutorials');

// オプション付き
$reranked = $posts->rerank(
    by: 'content',
    query: 'Laravel tutorials',
    limit: 10,
    provider: Lab::Cohere,
);
```

***

## 分類（Classification）

### Yes / No の判定

単純な yes / no の判定には、Laravelの `Stringable` クラスの `decide` メソッドが使えます。完全なレスポンスではなく boolean を返します。「yes」と「no」の意味を記述したり、回答が満たすべき確率（デフォルトは `0.5`）を `threshold` で指定したりできます。

```php theme={null}
use Illuminate\Support\Str;

$spam = Str::of($message)->decide('Is this spam?');
```

### コレクションから選ぶ

選択肢のリストから1つを選ぶには、`Collection` クラスの `decide` メソッドが使えます。質問と分類するテキストを渡すと、コレクション内から選ばれた要素を返します。

文字列やenumのコレクションはそのまま使えます。それ以外の要素は `by` 引数で名前を指定します。`describe` 引数にフィールド名・フィールド名の配列・クロージャを渡すと、各選択肢の詳細をモデルに伝えられます。

```php theme={null}
$department = collect(['billing', 'technical', 'sales'])
    ->decide('Which team should handle this request?', $ticket->body);

$priority = collect(Priority::cases())
    ->decide('How urgent is this request?', $ticket->body);

$department = Department::all()->decide(
    'Which department should handle this request?',
    $ticket->body,
    by: 'name',
    describe: 'description',
);
```

`describe` で定義した説明は、テキストがその選択肢に該当するかをモデルが判断する基準になります。名前だけでは曖昧な選択肢に有効です。クロージャを渡す場合は各要素を受け取り、説明の文字列か配列を返します。

```php theme={null}
$priority = collect(Priority::cases())->decide(
    'How urgent is this request?',
    $ticket->body,
    describe: fn (Priority $priority) => $priority->description(),
);
```

キーが文字列の文字列コレクションでは、キーが選択肢、値がその説明として使われ、選ばれたキーが返されます。`threshold` を指定して、選ばれた選択肢の確率がそれを下回った場合は `null` が返ります。

```php theme={null}
$department = collect([
    'billing' => 'Payments, invoices, and refunds',
    'technical' => 'Bugs, outages, and integrations',
])->decide('Which team should handle this request?', $ticket->body, threshold: 0.6) ?? 'triage';
```

***

## ファイル管理

AI プロバイダーにファイルをアップロードして、後から参照できます。

```php theme={null}
use Laravel\Ai\Files\Document;
use Laravel\Ai\Files\Image;

// パスから
$response = Document::fromPath('/home/laravel/document.pdf')->put();
$response = Image::fromPath('/home/laravel/photo.jpg')->put();

// ストレージから
$response = Document::fromStorage('document.pdf', disk: 'local')->put();
$response = Image::fromStorage('photo.jpg', disk: 'local')->put();

// URL から
$response = Document::fromUrl('https://example.com/document.pdf')->put();
$response = Image::fromUrl('https://example.com/photo.jpg')->put();

return $response->id;
```

文字列やフォームアップロードからも扱えます。

```php theme={null}
$stored = Document::fromString('Hello, World!', 'text/plain')->put();
$stored = Document::fromUpload($request->file('document'))->put();
```

### 保存済みファイルの参照

アップロード済みのファイル ID でエージェントに添付できます。

```php theme={null}
use Laravel\Ai\Files;

$response = (new SalesCoach)->prompt(
    'Analyze the attached sales transcript...',
    attachments: [Files\Document::fromId('file-id')]
);
```

### ファイルの取得・削除

```php theme={null}
// 取得
$file = Document::fromId('file-id')->get();
$file->id;
$file->mimeType();

// 削除
Document::fromId('file-id')->delete();
```

### プロバイダーの指定

```php theme={null}
$response = Document::fromPath('/home/laravel/document.pdf')->put(provider: Lab::Anthropic);
```

### プロバイダー固有オプションの指定

`withProviderOptions` メソッドでプロバイダー固有のアップロードオプションを渡せます。たとえば OpenAI のファイル `purpose` を設定できます。

```php theme={null}
use Laravel\Ai\Files\Document;

$response = Document::fromPath('/home/laravel/knowledge.txt')
    ->withProviderOptions(['purpose' => 'assistants'])
    ->put();
```

プロバイダーごとに異なるオプションを指定する場合は、クロージャを渡します。

```php theme={null}
use Laravel\Ai\Enums\Lab;
use Laravel\Ai\Files\Document;

$response = Document::fromPath('/home/laravel/training.jsonl')
    ->withProviderOptions(fn (Lab|string $provider) => match ($provider) {
        Lab::OpenAI => ['purpose' => 'fine-tune'],
        default => [],
    })
    ->put();
```

***

## ベクターストア

ベクターストアを使うと、ドキュメントをプロバイダー側で管理できます。

```php theme={null}
use Laravel\Ai\Stores;

// 作成
$store = Stores::create('Knowledge Base');
$store = Stores::create(
    name: 'Knowledge Base',
    description: 'Documentation.',
    expiresWhenIdleFor: days(30),
);
return $store->id;

// 取得
$store = Stores::get('store_id');
$store->id;
$store->name;
$store->fileCounts;
$store->ready;

// 削除
Stores::delete('store_id');
$store->delete();
```

### ストアへのファイル追加

```php theme={null}
$store = Stores::get('store_id');

// さまざまな方法でファイルを追加
$document = $store->add('file_id');
$document = $store->add(Document::fromId('file_id'));
$document = $store->add(Document::fromPath('/path/to/document.pdf'));
$document = $store->add(Document::fromStorage('manual.pdf'));
$document = $store->add($request->file('document'));

$document->id;
$document->fileId;
```

メタデータを付与することもできます。

```php theme={null}
$store->add(
    Document::fromPath('/path/to/document.pdf'),
    metadata: [
        'author' => 'Taylor Otwell',
        'department' => 'Engineering',
        'year' => 2026,
    ]
);
```

### ストアからのファイル削除

```php theme={null}
$store->remove('file_id');

// ファイル自体も削除する場合
$store->remove('file_abc123', deleteFile: true);
```

***

## フェイルオーバー

複数のプロバイダーを配列で指定すると、最初のプロバイダーが失敗した場合に次のプロバイダーへ自動フォールバックします。

```php theme={null}
use App\Ai\Agents\SalesCoach;
use Laravel\Ai\Image;

// エージェントのフェイルオーバー
$response = (new SalesCoach)->prompt(
    'Analyze this sales transcript...',
    provider: [Lab::OpenAI, Lab::Anthropic],
);

// 画像生成のフェイルオーバー
$image = Image::of('A donut sitting on the kitchen counter')
    ->generate(provider: [Lab::Gemini, Lab::xAI]);
```

***

## テスト

Laravel AI SDK はテスト用のフェイク機能を提供しており、実際の API を呼び出さずにテストできます。

キューに入れた画像・音声・文字起こし・埋め込み生成をフェイクすると、生成に登録した `then` コールバックはフェイクレスポンスを受け取って呼び出されます。コールバックも実行したくない場合は、`Queue::fake()` も使用してください。

### エージェントのテスト

```php theme={null}
use App\Ai\Agents\SalesCoach;
use Laravel\Ai\Prompts\AgentPrompt;

// 固定レスポンスのフェイク
SalesCoach::fake();
SalesCoach::fake(['First response', 'Second response']);

// クロージャで動的レスポンス
SalesCoach::fake(function (AgentPrompt $prompt) {
    return 'Response for: '.$prompt->prompt;
});

// アサーション
SalesCoach::assertPrompted('Analyze this...');
SalesCoach::assertPrompted(function (AgentPrompt $prompt) {
    return $prompt->contains('Analyze');
});
SalesCoach::assertPromptedTimes(3);
SalesCoach::assertNotPrompted('Missing prompt');
SalesCoach::assertNeverPrompted();
```

キューイングのアサーションも用意されています。

```php theme={null}
use Laravel\Ai\QueuedAgentPrompt;

SalesCoach::assertQueued('Analyze this...');
SalesCoach::assertQueued(function (QueuedAgentPrompt $prompt) {
    return $prompt->contains('Analyze');
});
SalesCoach::assertNotQueued('Missing prompt');
SalesCoach::assertNeverQueued();
```

`preventStrayPrompts()` を使うと、フェイクで定義していないプロンプトが呼ばれた場合に例外を投げます。

```php theme={null}
SalesCoach::fake()->preventStrayPrompts();
```

構造化出力を返すエージェントをフェイクする場合、配列でレスポンスを指定できます。エージェントは指定したデータを含む構造化レスポンスを返します。

```php theme={null}
SalesCoach::fake([
    ['score' => 87],
]);
```

> [!NOTE]
>
> 構造化出力エージェントに対して `fake()` がフェイクデータを明示的に渡さずに呼ばれた場合、Laravel はエージェントの定義したスキーマに合致するフェイクデータを自動生成します。

匿名エージェントのテストには `AnonymousAgent::fake()` を使います。

```php theme={null}
use Laravel\Ai\AnonymousAgent;

AnonymousAgent::fake(['Test response']);
```

### 画像生成のテスト

```php theme={null}
use Laravel\Ai\Image;
use Laravel\Ai\Prompts\ImagePrompt;

Image::fake();
Image::fake([base64_encode($firstImage), base64_encode($secondImage)]);
Image::fake(function (ImagePrompt $prompt) {
    return base64_encode('...');
});

Image::assertGenerated(function (ImagePrompt $prompt) {
    return $prompt->contains('sunset') && $prompt->isLandscape();
});
Image::assertNotGenerated(
    fn (ImagePrompt $prompt) => $prompt->contains('Missing prompt')
);
Image::assertNothingGenerated();

Image::assertQueued(fn (QueuedImagePrompt $prompt) => $prompt->contains('sunset'));
Image::assertNotQueued(
    fn (QueuedImagePrompt $prompt) => $prompt->contains('Missing prompt')
);
Image::assertNothingQueued();

Image::fake()->preventStrayImages();
```

### 音声合成のテスト

```php theme={null}
use Laravel\Ai\Audio;
use Laravel\Ai\Prompts\AudioPrompt;

Audio::fake();
Audio::fake([base64_encode($firstAudio), base64_encode($secondAudio)]);
Audio::fake(function (AudioPrompt $prompt) {
    return base64_encode('...');
});

Audio::assertGenerated(function (AudioPrompt $prompt) {
    return $prompt->contains('Hello') && $prompt->isFemale();
});
Audio::assertNotGenerated(
    fn (AudioPrompt $prompt) => $prompt->contains('Missing prompt')
);
Audio::assertNothingGenerated();

Audio::assertQueued(fn (QueuedAudioPrompt $prompt) => $prompt->contains('Hello'));
Audio::assertNotQueued(
    fn (QueuedAudioPrompt $prompt) => $prompt->contains('Missing prompt')
);
Audio::assertNothingQueued();

Audio::fake()->preventStrayAudio();
```

### 文字起こしのテスト

```php theme={null}
use Laravel\Ai\Transcription;
use Laravel\Ai\Prompts\TranscriptionPrompt;

Transcription::fake();
Transcription::fake(['First transcription text.', 'Second transcription text.']);
Transcription::fake(function (TranscriptionPrompt $prompt) {
    return 'Transcribed text...';
});

Transcription::assertGenerated(function (TranscriptionPrompt $prompt) {
    return $prompt->language === 'en' && $prompt->isDiarized();
});
Transcription::assertNotGenerated(fn (TranscriptionPrompt $prompt) => $prompt->language === 'fr');
Transcription::assertNothingGenerated();

Transcription::assertQueued(fn (QueuedTranscriptionPrompt $prompt) => $prompt->isDiarized());
Transcription::assertNotQueued(fn (QueuedTranscriptionPrompt $prompt) => $prompt->language === 'fr');
Transcription::assertNothingQueued();

Transcription::fake()->preventStrayTranscriptions();
```

### 埋め込みのテスト

```php theme={null}
use Laravel\Ai\Embeddings;
use Laravel\Ai\Prompts\EmbeddingsPrompt;

Embeddings::fake();
Embeddings::fake([[$firstEmbeddingVector], [$secondEmbeddingVector]]);
Embeddings::fake(function (EmbeddingsPrompt $prompt) {
    return array_map(
        fn () => Embeddings::fakeEmbedding($prompt->dimensions),
        $prompt->inputs
    );
});

Embeddings::assertGenerated(function (EmbeddingsPrompt $prompt) {
    return $prompt->contains('Laravel') && $prompt->dimensions === 1536;
});
Embeddings::assertNotGenerated(fn (EmbeddingsPrompt $prompt) => $prompt->contains('Other'));
Embeddings::assertNothingGenerated();

Embeddings::assertQueued(fn (QueuedEmbeddingsPrompt $prompt) => $prompt->contains('Laravel'));
Embeddings::assertNotQueued(fn (QueuedEmbeddingsPrompt $prompt) => $prompt->contains('Other'));
Embeddings::assertNothingQueued();

Embeddings::fake()->preventStrayEmbeddings();
```

### リランキングのテスト

```php theme={null}
use Laravel\Ai\Reranking;
use Laravel\Ai\Prompts\RerankingPrompt;
use Laravel\Ai\Responses\Data\RankedDocument;

Reranking::fake();
Reranking::fake([[
    new RankedDocument(index: 0, document: 'First', score: 0.95),
    new RankedDocument(index: 1, document: 'Second', score: 0.80),
]]);

Reranking::assertReranked(function (RerankingPrompt $prompt) {
    return $prompt->contains('Laravel') && $prompt->limit === 5;
});
Reranking::assertNotReranked(fn (RerankingPrompt $prompt) => $prompt->contains('Django'));
Reranking::assertNothingReranked();
```

### ファイルのテスト

```php theme={null}
use Laravel\Ai\Files;
use Laravel\Ai\Contracts\Files\StorableFile;
use Laravel\Ai\Files\Document;

Files::fake();

Document::fromString('Hello, Laravel!', mimeType: 'text/plain')->as('hello.txt')->put();

Files::assertStored(fn (StorableFile $file) =>
    (string) $file === 'Hello, Laravel!' && $file->mimeType() === 'text/plain'
);
Files::assertNotStored(fn (StorableFile $file) => (string) $file === 'Hello, World!');
Files::assertNothingStored();

Files::assertDeleted('file-id');
Files::assertNotDeleted('file-id');
Files::assertNothingDeleted();
```

### ベクターストアのテスト

```php theme={null}
use Laravel\Ai\Stores;

Stores::fake(); // ファイル操作もフェイクになる

$store = Stores::create('Knowledge Base');

Stores::assertCreated('Knowledge Base');
Stores::assertCreated(fn (string $name, ?string $description) => $name === 'Knowledge Base');
Stores::assertNotCreated('Other Store');
Stores::assertNothingCreated();

Stores::assertDeleted('store_id');
Stores::assertNotDeleted('other_store_id');
Stores::assertNothingDeleted();
```

ストアに対するファイル操作のアサーションも行えます。

```php theme={null}
$store = Stores::get('store_id');
$store->add('added_id');
$store->remove('removed_id');

$store->assertAdded('added_id');
$store->assertRemoved('removed_id');
$store->assertNotAdded('other_file_id');
$store->assertNotRemoved('other_file_id');

// クロージャでコンテンツを検証
$store->add(Document::fromString('Hello, World!', 'text/plain')->as('hello.txt'));
$store->assertAdded(fn (StorableFile $file) => $file->name() === 'hello.txt');
$store->assertAdded(fn (StorableFile $file) => $file->content() === 'Hello, World!');
```

***

## イベント

Laravel AI SDK は以下のイベントをディスパッチします。これらのイベントをリスニングすることで、ログの記録や監視などに活用できます。

> [accordion] エージェント関連
>
> * `AgentFailed` — エージェント処理の失敗時
> * `AgentFailedOver` — エージェントのフェイルオーバー時
> * `PromptingAgent` — プロンプト送信前
> * `AgentPrompted` — プロンプト送信後
> * `StreamingAgent` — ストリーミング開始時
> * `AgentStreamed` — ストリーミング完了後
> * `InvokingTool` — ツール呼び出し前
> * `ToolInvoked` — ツール呼び出し後
> * `ToolApprovalRequested` — ツール承認要求時
> * `ToolApprovalResolved` — ツール承認解決後
> * `ProviderFailedOver` — プロバイダーのフェイルオーバー時
> * `StartingStep` — ステップ開始時
> * `StepCompleted` — ステップ完了時
> * `StepFailed` — ステップ失敗時
> * `ToolFailed` — ツール実行失敗時

> [accordion] 画像・音声・文字起こし関連
>
> * `GeneratingImage` — 画像生成前
> * `ImageGenerated` — 画像生成後
> * `GeneratingAudio` — 音声生成前
> * `AudioGenerated` — 音声生成後
> * `GeneratingTranscription` — 文字起こし前
> * `TranscriptionGenerated` — 文字起こし後

> [accordion] 埋め込み・リランキング関連
>
> * `GeneratingEmbeddings` — 埋め込み生成前
> * `EmbeddingsGenerated` — 埋め込み生成後
> * `Reranking` — リランキング前
> * `Reranked` — リランキング後

> [accordion] ファイル・ストア関連
>
> * `StoringFile` — ファイル保存前
> * `FileStored` — ファイル保存後
> * `FileDeleted` — ファイル削除後
> * `CreatingStore` — ストア作成前
> * `StoreCreated` — ストア作成後
> * `StoreDeleted` — ストア削除後
> * `AddingFileToStore` — ストアへのファイル追加前
> * `FileAddedToStore` — ストアへのファイル追加後
> * `RemovingFileFromStore` — ストアからのファイル削除前
> * `FileRemovedFromStore` — ストアからのファイル削除後


## Related topics

- [Laravel 13 新機能まとめ](https://kawax.biz/jp/blog/laravel-13-new-features.md)
- [2026年3月 Laravel アップデート](https://kawax.biz/jp/blog/changelog/202603.md)
- [Laravel AI SDK連携](https://kawax.biz/jp/packages/laravel-copilot-sdk/ai-sdk.md)
- [Laravel AI SDK連携 - VOICEVOX for Laravel](https://kawax.biz/jp/packages/laravel-voicevox/ai-sdk.md)
- [Laravel AI SDK 用の Amazon Bedrock ドライバー](https://kawax.biz/jp/packages/laravel-amazon-bedrock.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.