Laravel AI SDK - Knowledge of Laravel

はじめに

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

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
音声認識（STT）	OpenAI, ElevenLabs, Mistral, Gemini
埋め込み	OpenAI, Gemini, Azure, Bedrock, Cohere, Mistral, Jina, VoyageAI, Ollama, OpenRouter
リランキング	Cohere, Jina, VoyageAI
ファイル	OpenAI, Anthropic, Gemini, Azure

インストール

パッケージのインストール

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

composer require laravel/ai

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

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

php artisan vendor:publish --provider="Laravel\Ai\AiServiceProvider"

マイグレーションの実行

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

php artisan migrate

設定

環境変数

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

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 を設定できます。

'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 トークンとして送信されます。

'providers' => [
    'local' => [
        'driver' => 'openai-compatible',
        'url' => env('LOCAL_AI_URL'),
        'key' => env('LOCAL_AI_API_KEY'),
    ],
],

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

agent()->prompt('What is Laravel?', provider: 'local', model: 'local-model');

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

'local' => [
    'driver' => 'openai-compatible',
    'url' => env('LOCAL_AI_URL'),
    'key' => env('LOCAL_AI_API_KEY'),
    'models' => [
        'text' => [
            'default' => env('LOCAL_AI_MODEL'),
        ],
    ],
],

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

Lab enum

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

use Laravel\Ai\Enums\Lab;

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

エージェント

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

php artisan make:agent SalesCoach

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

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

<?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(),
        ];
    }
}

プロンプト

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

$response = (new SalesCoach)->prompt('Analyze this sales transcript...');
return (string) $response;

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

$agent = SalesCoach::make(user: $user);

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

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

会話コンテキスト

Conversational インターフェースを実装して messages() メソッドを定義すると、過去の会話履歴を AI に渡せます。 RemembersConversations トレイトを使うと、会話履歴をデータベースに自動保存・取得できます。

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() で続きの会話ができます。

$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 のレスポンスを構造化されたデータとして受け取れます。

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

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

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

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(),
    ];
}

オブジェクトの配列

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 メソッドを使います。

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 引数でドキュメントや画像をエージェントに渡せます。

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'),
    ]
);

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

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

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

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

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...
        });
});

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

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

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

Vercel AI SDK プロトコル

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

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

ブロードキャスト

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

use Illuminate\Broadcasting\Channel;

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

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

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

(new SalesCoach)->broadcastOnQueue(
    'Analyze this sales transcript...',
    new Channel('channel-name'),
);

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

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

<?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() メソッドでプロンプトをキューに積んで非同期処理できます。

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 コマンドでツールクラスを生成できます。

php artisan make:tool RandomNumberGenerator

<?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() メソッドでツールを登録します。

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

類似検索ツール

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

use App\Models\Document;
use Laravel\Ai\Tools\SimilaritySearch;

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

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

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

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

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

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

SimilaritySearch::usingModel(Document::class, 'embedding')
    ->withDescription('Search the knowledge base for relevant articles.'),

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

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

use Laravel\Ai\Tools\FileStorage;

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

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

return FileStorage::readOnly('local');

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

use Laravel\Ai\Tools\Filesystem\DeleteFile;

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

MCP ツール

アプリケーションで Laravel MCP を使っている場合、Model Context Protocol サーバーが公開するツールをエージェントに提供できます。Laravel MCP クライアントを使って、リモートまたはローカルの MCP サーバーに接続し、そのツールをエージェントに直接渡すことができます。

MCP ツールを使用するには、アプリケーションに Laravel MCP パッケージがインストールされている必要があります。

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

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 クライアントを使うこともできます。

use Laravel\Mcp\Facades\Mcp;

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

または、ローカル MCP サーバーに接続することも可能です。

use Laravel\Mcp\Client;

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

MCP クライアントの作成と認証（Bearer トークンや OAuth など）については、MCP クライアントのドキュメントを参照してください。

プロバイダーツール

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

Web 検索

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

use Laravel\Ai\Providers\Tools\WebSearch;

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

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

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

Web フェッチ

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

use Laravel\Ai\Providers\Tools\WebFetch;

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

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

ファイル検索

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

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 を使った複雑なフィルターも指定できます。

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'])
);

サブエージェント

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

<?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

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 はクラス名をツール名として使用し、汎用的な説明文を自動で生成します。各サブエージェントの呼び出しは独立して行われ、親エージェントの会話履歴は引き継ぎません。

ミドルウェア

エージェントにミドルウェアを追加して、プロンプトやレスポンスをインターセプトできます。

php artisan make:agent-middleware LogPrompts

エージェントに HasMiddleware インターフェースを実装し、middleware() メソッドでミドルウェアを登録します。

<?php

namespace App\Ai\Agents;

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

class SalesCoach implements Agent, HasMiddleware
{
    use Promptable;

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

ミドルウェアクラスの実装例です。

<?php

namespace App\Ai\Middleware;

use Closure;
use Laravel\Ai\Prompts\AgentPrompt;

class LogPrompts
{
    public function handle(AgentPrompt $prompt, Closure $next)
    {
        Log::info('Prompting agent', ['prompt' => $prompt->prompt]);
        return $next($prompt);
    }
}

then() を使うと、レスポンス後の処理も追加できます。

public function handle(AgentPrompt $prompt, Closure $next)
{
    return $next($prompt)->then(function (AgentResponse $response) {
        Log::info('Agent responded', ['text' => $response->text]);
    });
}

匿名エージェント

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

use function Laravel\Ai\{agent};

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

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

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

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 も用意されています。

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

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

プロバイダーオプション

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

<?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 => [],
        };
    }
}

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

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

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

<?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インスタンスを返せます。

use Laravel\Ai\Approvals\Approval;

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

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

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

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

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

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

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

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メソッドでデフォルトの決定を指定できます。

$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 ストリームプロトコルを使用している場合、承認リクエストと結果はプロトコルのネイティブなツール承認パートとして送出されます。キューイングされたエージェントの場合、結果のレスポンスはthenコールバックに渡され、Laravel はToolApprovalRequestedイベントもディスパッチします。 Laravel は、モデルに続行を求める前に、承認済みツールの実行結果を保存します。その後に生成が失敗した場合、承認はすでに解決済みです。同じ承認決定を再送するのではなく、通常のテキストプロンプトで会話を継続してください。

完全な承認フロー

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

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', 'prohibited_with:decisions'],
        'decisions' => ['nullable', 'array', 'required_without:message', 'prohibited_with:message'],
        'decisions.*.action' => ['required_with:decisions', Rule::in(['approve', 'reject'])],
        'decisions.*.result' => ['nullable', 'string'],
    ]);

    $prompt = isset($validated['decisions'])
        ? Decisions::from($validated->collect('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をキーとしてユーザーの選択を同じエンドポイントに送信する必要があります。

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

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

{
    "message": "古い請求書を削除して。"
}

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

画像生成

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

use Laravel\Ai\Image;

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

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

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

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

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();

画像の保存

$path = $image->store();
$path = $image->storeAs('image.jpg');
$path = $image->storePublicly();
$path = $image->storePubliclyAs('image.jpg');

キューで画像生成

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 プロバイダーが対応しています。

use Laravel\Ai\Audio;

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

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

$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();

音声の保存

$path = $audio->store();
$path = $audio->storeAs('audio.mp3');
$path = $audio->storePublicly();
$path = $audio->storePubliclyAs('audio.mp3');

キューで音声生成

use Laravel\Ai\Responses\AudioResponse;

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

文字起こし（STT）

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

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() を使うと、話者ごとに分離した文字起こしが得られます。

$transcript = Transcription::fromStorage('audio.mp3')->diarize()->generate();

キューで文字起こし

use Laravel\Ai\Responses\TranscriptionResponse;

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

埋め込み（Embeddings）

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

use Illuminate\Support\Str;

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

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, ...]]

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

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

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

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

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 エンコードされたコンテンツから作成できます。画像・ドキュメント・動画はアップロードされたファイルからも作成でき、ドキュメントは生の文字列コンテンツからも作成できます。

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');
Audio::fromUpload($request->file('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'));

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

ベクター検索（pgvector）

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

マイグレーションの作成

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();

モデルの設定

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

類似検索クエリ

// 埋め込みベクターで検索
$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();

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

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

埋め込みのキャッシュ

同じテキストの埋め込み生成を繰り返さないようにキャッシュできます。 config/ai.php でデフォルトのキャッシュ設定を行います。

'caching' => [
    'embeddings' => [
        'cache' => true,
        'store' => env('CACHE_STORE', 'database'),
    ],
],

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

$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 プロバイダーが対応しています。

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() で返す件数を絞り込めます。

$response = Reranking::of($documents)->limit(5)->rerank('search query');

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

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

// 単一フィールド
$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,
);

ファイル管理

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

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;

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

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

保存済みファイルの参照

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

use Laravel\Ai\Files;

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

ファイルの取得・削除

// 取得
$file = Document::fromId('file-id')->get();
$file->id;
$file->mimeType();

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

プロバイダーの指定

$response = Document::fromPath('/home/laravel/document.pdf')->put(provider: Lab::Anthropic);

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

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

use Laravel\Ai\Files\Document;

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

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

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();

ベクターストア

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

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();

ストアへのファイル追加

$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;

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

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

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

$store->remove('file_id');

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

フェイルオーバー

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

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 を呼び出さずにテストできます。

エージェントのテスト

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::assertNotPrompted('Missing prompt');
SalesCoach::assertNeverPrompted();

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

use Laravel\Ai\QueuedAgentPrompt;

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

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

SalesCoach::fake()->preventStrayPrompts();

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

SalesCoach::fake([
    ['score' => 87],
]);

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

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

use Laravel\Ai\AnonymousAgent;

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

画像生成のテスト

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('Missing prompt');
Image::assertNothingGenerated();

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

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

音声合成のテスト

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('Missing prompt');
Audio::assertNothingGenerated();

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

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

文字起こしのテスト

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();

埋め込みのテスト

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();

リランキングのテスト

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();

ファイルのテスト

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();

ベクターストアのテスト

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();

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

$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 は以下のイベントをディスパッチします。これらのイベントをリスニングすることで、ログの記録や監視などに活用できます。

エージェント関連

PromptingAgent — プロンプト送信前
AgentPrompted — プロンプト送信後
StreamingAgent — ストリーミング開始時
AgentStreamed — ストリーミング完了後
InvokingTool — ツール呼び出し前
ToolInvoked — ツール呼び出し後
ToolApprovalRequested — ツール承認要求時
ToolApprovalResolved — ツール承認解決後

画像・音声・文字起こし関連

GeneratingImage — 画像生成前
ImageGenerated — 画像生成後
GeneratingAudio — 音声生成前
AudioGenerated — 音声生成後
GeneratingTranscription — 文字起こし前
TranscriptionGenerated — 文字起こし後

埋め込み・リランキング関連

GeneratingEmbeddings — 埋め込み生成前
EmbeddingsGenerated — 埋め込み生成後
Reranking — リランキング前
Reranked — リランキング後

ファイル・ストア関連

StoringFile — ファイル保存前
FileStored — ファイル保存後
FileDeleted — ファイル削除後
CreatingStore — ストア作成前
StoreCreated — ストア作成後
AddingFileToStore — ストアへのファイル追加前
FileAddedToStore — ストアへのファイル追加後
RemovingFileFromStore — ストアからのファイル削除前
FileRemovedFromStore — ストアからのファイル削除後

最終更新日 2026年7月24日

​はじめに

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

​インストール

​設定

​環境変数

​カスタムベース URL

​OpenAI-Compatible プロバイダー

​Lab enum

​エージェント

​プロンプト

​会話コンテキスト

​構造化出力

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

​オブジェクトの配列

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

​添付ファイル

​ストリーミング

​Vercel AI SDK プロトコル

​ブロードキャスト

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

​キュー

​ツール

​類似検索ツール

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

​MCP ツール

​プロバイダーツール

​Web 検索

​Web フェッチ

​ファイル検索

​サブエージェント

​ミドルウェア

​匿名エージェント

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

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

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

​完全な承認フロー

​画像生成

​画像の保存

​キューで画像生成

​音声合成（TTS）

​音声の保存

​キューで音声生成

​文字起こし（STT）

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

​キューで文字起こし

​埋め込み（Embeddings）

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

​ベクター検索（pgvector）

​埋め込みのキャッシュ

​リランキング

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

​ファイル管理

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

​ファイルの取得・削除

​プロバイダーの指定

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

​ベクターストア

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

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

​フェイルオーバー

​テスト

​エージェントのテスト

​画像生成のテスト

​音声合成のテスト

​文字起こしのテスト

​埋め込みのテスト

​リランキングのテスト

​ファイルのテスト

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

​イベント

はじめに

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

インストール

設定

環境変数

カスタムベース URL

OpenAI-Compatible プロバイダー

Lab enum

エージェント

プロンプト

会話コンテキスト

構造化出力

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

オブジェクトの配列

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

添付ファイル

ストリーミング

Vercel AI SDK プロトコル

ブロードキャスト

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

キュー

ツール

類似検索ツール

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

MCP ツール

プロバイダーツール

Web 検索

Web フェッチ

ファイル検索

サブエージェント

ミドルウェア

匿名エージェント

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

プロバイダーオプション

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

完全な承認フロー

画像生成

画像の保存

キューで画像生成

音声合成（TTS）

音声の保存

キューで音声生成

文字起こし（STT）

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

キューで文字起こし

埋め込み（Embeddings）

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

ベクター検索（pgvector）

埋め込みのキャッシュ

リランキング

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

ファイル管理

保存済みファイルの参照

ファイルの取得・削除

プロバイダーの指定

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

ベクターストア

ストアへのファイル追加

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

フェイルオーバー

テスト

エージェントのテスト

画像生成のテスト

音声合成のテスト

文字起こしのテスト

埋め込みのテスト

リランキングのテスト

ファイルのテスト

ベクターストアのテスト

イベント