Laravel 13で正式安定版になったAI SDKの全体像と導入判断の前提知識

Laravel 13で正式安定版になったAI SDKの全体像と導入判断の前提知識

2026年3月17日にリリースされたLaravel 13は、PHPフレームワークとしてのAI対応を本格化させた歴史的なバージョンです。最大の注目点は、それまでベータ版として提供されていたLaravel AI SDKがファーストパーティパッケージとして正式安定版に昇格したことにあります。テキスト生成、画像生成、音声合成、Embedding、ベクトルストアなど、AI開発に必要な機能群がひとつの統一APIのもとに集約されました。この章では、Laravel 13におけるAI SDKの位置づけと、導入を検討するうえで押さえておくべき前提知識を整理します。

2026年3月17日リリースのLaravel 13で変わったAI開発の位置づけ

Laravel 13は、Laracon EU 2026でTaylor Otwell氏によって発表され、2026年3月17日に正式リリースされました。最低動作要件はPHP 8.3に引き上げられましたが、破壊的変更はゼロという方針が貫かれており、Laravel 12からのアップグレードは多くのアプリケーションで10分程度と公式に案内されています。フレームワーク本体の変更が最小限に抑えられた分、開発者体験の改善に注力されたリリースといえます。

なかでも最も大きな変化は、AI SDKがフレームワークの公式エコシステムに組み込まれた点です。それ以前はOpenAIのPHPクライアントやサードパーティの抽象レイヤーを自前で組み合わせる必要がありましたが、Laravel 13ではAI機能がルーティングやEloquentと同じレベルのファーストクラス市民として扱われます。これにより、AIを使った機能開発はもはや特別な外部統合ではなく、フレームワーク標準のワークフローの一部になりました。

composer require laravel/aiから始まる導入手順と初期設定3ステップ

AI SDKの導入は、Composerによるパッケージインストールから始まります。ターミナルでcomposer require laravel/aiを実行すると、SDKの本体と必要な依存パッケージが自動的にインストールされます。この1コマンドだけでSDK自体の導入は完了するため、追加の設定ファイル編集やサービスプロバイダの手動登録は不要です。

インストール後に行うのは3つの手順です。まずphp artisan vendor:publish --provider="Laravel\Ai\AiServiceProvider"で設定ファイルとマイグレーションを公開します。次にphp artisan migrateを実行して、会話履歴を永続化するためのagent_conversationsテーブルとagent_conversation_messagesテーブルを作成します。最後に.envファイルまたはconfig/ai.phpにOpenAIやAnthropicなどのAPIキーを設定すれば、AI機能を呼び出す準備が整います。既存のLaravelプロジェクトの構造を変更する必要がないため、段階的な導入が可能です。

AI SDKが提供する7機能カテゴリとそれぞれの対応プロバイダ一覧

Laravel AI SDKは、AIアプリケーション開発で必要となる主要な機能を7つのカテゴリに整理して提供しています。それぞれのカテゴリごとに対応するプロバイダが異なるため、導入前に自社のユースケースとプロバイダの組み合わせを確認することが重要です。

すべての機能が全プロバイダで使えるわけではない点に注意が必要です。テキスト生成は9社のプロバイダが対応していますが、Rerankingに対応しているのはCohereとJinaの2社のみです。プロバイダごとの対応状況はconfig/ai.phpの設定時に確認し、フォールバック先を含めた設計を事前に行う必要があります。

ベータ版から正式版への移行で解消された本番運用上の3つの課題

Laravel AI SDKは2026年2月にベータ版として公開され、約1か月半後のLaravel 13リリースと同時に正式安定版となりました。ベータ期間中に報告された課題のうち、本番運用に直結する3つの問題が正式版で解消されています。

1つ目は、APIの安定性です。ベータ期間中はメソッドシグネチャやインターフェース名が変更される可能性があり、プロダクションコードに組み込むにはリスクがありました。正式版ではセマンティックバージョニングが適用され、マイナーバージョンアップで破壊的変更が入らないことが保証されます。2つ目は、エラーハンドリングの正規化です。プロバイダごとに異なっていたエラー形式がSDK内部で統一され、アプリケーション側で個別のtry-catchロジックを書く必要がなくなりました。3つ目は、キュー統合の安定化です。重い処理をキュー経由で非同期実行する際のシリアライズとデシリアライズの挙動が安定し、ジョブの失敗率が大幅に低下しています。

AI SDK・Boost・MCPの役割分担を誤ると起きる設計上の典型的混乱

Laravel 13のAIエコシステムは、AI SDK・Boost・MCPという3つのファーストパーティコンポーネントで構成されています。この3者の役割を正しく理解しないまま導入すると、責務の重複や設計の混乱が生じます。

AI SDKは、アプリケーション内にAI機能を組み込むためのパッケージです。ユーザーが操作するプロダクトの中で、テキスト要約やセマンティック検索、チャットインターフェースなどを構築する場合に使います。一方、Boostは開発者向けのツールであり、Claude CodeやCursorなどのAIコーディングアシスタントに対してLaravelアプリのコンテキスト（ルート情報・スキーマ・ログなど）を提供するMCPサーバーです。MCPはModel Context Protocolの略で、外部のAIクライアントからLaravelアプリケーションの機能を呼び出すためのオープンスタンダードです。たとえば、ChatGPTのインターフェースから「Acme Corp宛に請求書を作成して」と指示し、LaravelアプリのCreateInvoiceツールを実行するような使い方が想定されています。AI SDKはプロダクト機能、Boostは開発効率、MCPは外部連携と、レイヤーが異なることを意識して設計する必要があります。

PHPエンジニアが理解すべきAgent設計思想とクラス構造の基本原則

Laravel AI SDKの中核を担うのがAgentという概念です。Agentは単なるAPIラッパーではなく、システムプロンプト・会話コンテキスト・使用ツール・出力スキーマを1つのPHPクラスに集約した設計単位として機能します。この章では、Agentクラスの構造と設計思想を掘り下げ、PHPエンジニアが効率的にAI機能を設計するための原則を解説します。

make:agentコマンドで生成されるクラス構成と4つの責務の分離

Agentクラスの作成は、Artisanコマンドphp artisan make:agent SalesCoachで行います。このコマンドを実行すると、App\Ai\Agentsディレクトリ配下に専用のPHPクラスが生成されます。構造化出力が必要な場合は--structuredオプションを付けることで、スキーマ定義メソッドが含まれたテンプレートが出力されます。

生成されるAgentクラスには、4つの明確な責務が分離されています。第1にinstructions()メソッドで定義するシステムプロンプト、第2にmessages()メソッドで管理する会話コンテキスト、第3にtools()メソッドで登録する外部ツール、第4にschema()メソッドで指定する出力スキーマです。この4つがそれぞれ独立したメソッドとして定義されるため、責務ごとの変更やテストが容易になります。コントローラやサービスクラスにAIロジックを散在させるのではなく、Agent単位でカプセル化する設計思想がLaravel AI SDKの根幹です。

instructionsメソッドで定義するシステムプロンプト設計の実務指針

Agentクラスのinstructions()メソッドは、そのエージェントがどのような役割を果たすのかをLLMに伝えるシステムプロンプトを返します。戻り値はstringまたはStringableインターフェースの実装クラスで、動的なプロンプト生成にも対応しています。

実務上のプロンプト設計で重要なのは、役割の明確化と制約条件の具体化です。たとえば「あなたは営業コーチです」だけでは範囲が広すぎるため、「営業トランスクリプトを分析し、改善ポイントと総合スコアを返す営業コーチです」のように、入力形式と出力形式の両方を含めた記述が望まれます。また、プロンプトは不変である必要はなく、コンストラクタで受け取ったユーザー情報や業務データに応じて動的に組み立てることが可能です。Bladeテンプレートのように外部ファイルからプロンプトを読み込む設計にすれば、プロンプトの変更時にPHPコードを修正する必要がなくなり、運用中の調整が容易になります。

Conversationalインターフェース実装による会話履歴の永続化手順

Agentに会話の記憶を持たせるには、Conversationalインターフェースを実装し、messages()メソッドで過去のメッセージ一覧を返す必要があります。AI SDKのマイグレーションで作成されるagent_conversationsテーブルとagent_conversation_messagesテーブルがこの永続化基盤として機能します。

会話の継続はcontinue()メソッドで実現します。たとえば(new SalesCoach)->continue($conversationId, as: $user)->prompt('前回の分析結果を踏まえて改善案を提示してください')のように、会話IDとユーザーを指定して前回の文脈を引き継ぎます。この仕組みにより、カスタマーサポートのチャットボットや段階的なタスク実行など、ステートフルなAI機能をデータベースベースで構築できます。セッションやキャッシュに依存しないため、水平スケーリングやサーバー間でのリクエスト分散にも対応しやすい設計です。保持するメッセージ数はクエリのlimit()で制御でき、コンテキストウィンドウの制約に応じた調整が可能です。

agent()ヘルパー関数と専用クラスの使い分けが必要になる判断基準

Laravel AI SDKでは、Agentクラスを定義せずにagent()ヘルパー関数で匿名エージェントを即座に生成する方法も提供されています。たとえばagent(instructions: 'あなたはソフトウェア開発の専門家です。')->prompt('Laravelについて教えてください')のように、1行でプロンプトを実行できます。

この2つの方式の使い分けは、再利用性と複雑性を基準に判断します。ワンショットの変換処理やスクリプト内での一時的なAI呼び出しであれば、agent()ヘルパー関数で十分です。一方、ツールの登録、構造化出力の定義、会話の永続化、ミドルウェアの適用など、複数の設定を組み合わせる場合は専用クラスとして定義すべきです。また、テストの観点からも、専用クラスはFakeによるモック化やユニットテストが容易であるのに対し、ヘルパー関数はインラインで使われるため分離が難しくなります。プロトタイプ段階ではagent()関数で素早く検証し、プロダクション投入時に専用クラスへ移行する段階的なアプローチが実用的です。

Promptableトレイトが担う役割とプロンプト実行時の内部処理の流れ

すべてのAgentクラスはPromptableトレイトを使用しており、このトレイトがprompt()メソッドの実体を提供しています。prompt()を呼び出すと、内部では以下の処理が順番に実行されます。まずAgentのinstructions・messages・toolsが収集され、プロバイダに送信するリクエストペイロードが構築されます。次にミドルウェアチェーンが適用され、リクエストの加工やロギングが行われます。そのうえでプロバイダのAPIが呼び出され、レスポンスが正規化されて返却されます。

Toolを登録しているAgentの場合、LLMがツール呼び出しを要求するとSDKが自動的にツールを実行し、その結果をLLMに返して次のステップを進めます。この繰り返しの最大回数は#[MaxSteps(10)]のようなPHP属性で制御できます。ストリーミング応答が必要な場合はstream()メソッドを使い、SSE経由でリアルタイムにレスポンスを返すことも可能です。重い処理であればqueue()メソッドでキューに投入し、完了後にコールバックを実行する非同期パターンも利用できます。このように、Promptableトレイトは同期・非同期・ストリーミングという3つの実行モードを統一的に提供しています。

Tool・Structured Output・会話永続化を組み合わせた実装設計の要点

Agentの基本構造を理解したうえで、次に押さえるべきはTool・Structured Output・会話永続化という3つの機能の組み合わせ方です。これらはそれぞれ独立して使うことも可能ですが、実際のプロダクトでは複数を同時に活用するケースが大半です。この章では、各機能の実装方法と、組み合わせ時に注意すべき設計上のポイントを解説します。

make:toolコマンドで作成するカスタムToolの実装例と命名規則

AgentにLLMの推論能力だけでなく外部のアクションを実行させるのがToolの役割です。カスタムToolはphp artisan make:tool SearchProductsのようにArtisanコマンドで生成します。生成されたクラスには、ツールの名前・説明・パラメータ定義・実行ロジックを記述するメソッドが用意されています。

実装の具体例として、EC サイトの商品検索ツールを考えます。ツールクラス内でEloquentクエリを実行し、検索結果をJSON形式で返却すれば、AgentはLLMの判断に基づいてこのツールを自動的に呼び出します。命名規則としては、動詞＋名詞の形式（SearchProducts、CreateInvoice、RetrieveTranscriptsなど）が推奨されます。ツール名はLLMがどのツールを呼び出すかを判断する際の重要な手がかりになるため、機能が一目で分かる具体的な命名を心がける必要があります。また、SDKにはSimilaritySearchのような組み込みツールも用意されており、ベクトル検索をAgentに統合する場合はカスタム実装なしで利用できます。

HasStructuredOutputで定義するJSONスキーマ設計時の5つの注意点

エージェントの出力を自由形式のテキストではなく、アプリケーションが処理可能な構造化データとして受け取るには、HasStructuredOutputインターフェースを実装し、schema()メソッドでJSONスキーマを定義します。定義されたスキーマに基づき、LLMは指定された形式でレスポンスを返します。

スキーマ設計時に押さえるべき注意点は5つあります。第1に、フィールドには必ずrequired()を明示的に指定することです。省略するとプロバイダによっては値が返されない場合があります。第2に、整数値にはmin()とmax()で範囲制約を付けることで、スコアリングなどの出力精度が向上します。第3に、enum的な選択肢がある場合は文字列型にバリデーション説明を添えるか、instructionsで選択肢を明示する方法が有効です。第4に、ネストの深いスキーマはLLMの出力精度を下げるため、できるだけフラットな構造を維持すべきです。第5に、レスポンスは配列風にアクセスできるため、$response['score']のようにキー指定で値を取り出す前提で設計します。

agent_conversationsテーブルを使った会話状態管理の設計パターン

AI SDKのマイグレーションで作成されるagent_conversationsテーブルとagent_conversation_messagesテーブルは、エージェントとユーザー間の会話履歴をリレーショナルデータベースに保存する仕組みです。セッションやRedisではなくRDBを使うことで、トランザクション管理や既存のバックアップ運用との統合が容易になります。

設計パターンとして最も一般的なのは、ユーザーごとに会話IDを発行し、リクエストのたびにcontinue($conversationId, as: $user)で会話を再開する方式です。カスタマーサポートのチャットボットであれば、問い合わせチケットと会話IDを紐づけることで、担当者の引き継ぎ時にも文脈が失われません。一方、ワンショットの分析タスクでは会話永続化は不要であり、Conversationalインターフェースを実装しない方がパフォーマンス面で有利です。永続化する会話のメッセージ数が増えるとトークン消費量も増加するため、limit()による上限設定やサマリーの挿入といった工夫が長期運用では必要になります。

MaxSteps・Temperature・Modelの3属性によるエージェント動作制御

Laravel AI SDKでは、エージェントの動作パラメータをPHP 8の属性（Attributes）で宣言的に設定できます。コードの可読性を高めつつ、実行時の挙動を細かく制御できる仕組みです。

#[MaxSteps(10)]は、ツールを使用するエージェントがLLMとツールの間で行き来するループの最大回数を制限します。設定しない場合、ツール呼び出しが無限に繰り返されるリスクがあるため、必ず上限を設定すべきです。#[Temperature(0.3)]は出力のランダム性を制御し、0.0に近いほど決定論的な応答になります。スコアリングや分類タスクでは低い値が適切です。#[Model('gpt-4o')]はエージェントが使用するモデルを指定します。config/ai.phpで定義したデフォルトモデルを上書きする形で動作するため、エージェントごとにコストと性能のバランスを調整できます。#[Provider(['openai', 'anthropic'])]のように配列で指定すれば、プライマリが利用不可のときに自動でフォールバックする設定も属性1つで完結します。

ToolとStructured Outputを同時に使う場合に発生しやすい設計矛盾

ToolとStructured Outputはそれぞれ強力な機能ですが、同時に使用する場合には設計上の注意が必要です。ToolはLLMが外部アクションを実行するための仕組みであり、Structured OutputはLLMの最終レスポンスを型付きデータとして返す仕組みです。両者を併用すると、LLMはまずツールを呼び出して必要な情報を収集し、最終ステップでスキーマに準拠したJSONを返します。

ここで発生しやすいのが、ツールの戻り値とスキーマの不整合です。たとえば、ツールが返すデータにスキーマが期待するフィールドが含まれていない場合、LLMが欠損データを推測で埋めてしまうことがあります。この問題を防ぐには、ツールの戻り値にスキーマが要求するフィールドの元データが含まれていることを設計段階で確認しておく必要があります。また、MaxStepsの設定が小さすぎると、ツール呼び出しだけでステップ数を消費し、最終的なStructured Outputを返す前にエージェントが停止するケースも報告されています。ツール呼び出し回数＋最終出力で最低1ステップを見込んだ余裕のあるMaxSteps設定が求められます。

OpenAI・Anthropic・Gemini対応のプロバイダ切替とフェイルオーバー戦略

Laravel AI SDKの大きな強みのひとつが、複数のAIプロバイダを統一APIで扱えるマルチプロバイダ対応です。設定変更だけでプロバイダを切り替えられるため、ベンダーロックインを回避しつつ、障害時の可用性を確保できます。この章では、プロバイダ管理の具体的な設定方法と、本番環境で安定運用するためのフェイルオーバー戦略を解説します。

config/ai.phpで設定する複数プロバイダの認証情報と優先順位の管理

AI SDKのプロバイダ設定はconfig/ai.phpに集約されています。このファイルでは、使用するプロバイダごとにAPIキー、デフォルトモデル、タイムアウト値などを定義します。環境変数経由での設定にも対応しており、.envファイルでAI_PROVIDER=openaiのように指定すれば、コードを変更せずに環境ごとのプロバイダ切替が可能です。

複数のプロバイダを併用する場合は、config/ai.php内で各プロバイダの接続情報を並列に定義します。デフォルトプロバイダは環境変数で指定し、個別のエージェントクラスでは#[Provider('anthropic')]属性を使って上書きします。この設計により、テキスト生成はAnthropicのClaude、画像生成はOpenAIのDALL-Eというように、機能ごとに最適なプロバイダを選択しつつ、設定の一元管理を維持できます。APIキーの管理にはLaravelの暗号化機能やVaultとの連携を検討し、本番環境でのキー漏洩リスクを最小化することが重要です。

provider配列指定で実現する自動フェイルオーバーの仕組みと発動条件

Laravel AI SDKのフェイルオーバー機能は、エージェントのProvider属性に配列を渡すだけで有効化されます。たとえば#[Provider(['openai', 'anthropic'])]と指定した場合、OpenAIへのリクエストが失敗すると自動的にAnthropicにフォールバックします。アプリケーション側でリトライロジックやフォールバック分岐を書く必要はありません。

フェイルオーバーが発動する条件は、プロバイダのAPIがタイムアウトした場合、レートリミットに到達した場合、またはサービス障害でHTTPエラーが返された場合です。SDKはこれらのエラーを内部で検知し、配列の次のプロバイダに自動的にリクエストを再送します。この仕組みはエージェント単位で設定できるため、コスト重視のエージェントにはGemini→OpenAIの順を、品質重視のエージェントにはAnthropic→OpenAIの順を設定するといった柔軟な運用が可能です。テキスト生成は9社が対応しておりフェイルオーバーの選択肢が豊富ですが、Rerankingのように対応プロバイダが2社のみの機能では選択肢が限定されます。フェイルオーバー先のプロバイダで同じツールやStructured Outputが正しく動作するかは事前のテストが必須です。

テキスト生成・画像・音声で異なるプロバイダ対応状況の比較整理

マルチプロバイダ対応とはいえ、すべての機能がすべてのプロバイダで利用できるわけではありません。機能ごとのプロバイダ対応状況を正確に把握しておかないと、フェイルオーバー設定が意味をなさないケースが生じます。

テキスト生成は9社が対応しておりフェイルオーバーの選択肢が豊富です。画像生成もOpenAI・Gemini・xAIの3社が対応しているため、プロバイダ障害時の切り替えが可能です。一方、Rerankingに対応しているのはCohereとJinaのみであり、この機能に依存する場合はフェイルオーバー先が限定される点を考慮した設計が必要です。プロバイダの対応状況は今後のアップデートで拡大する可能性があるため、定期的な確認が推奨されます。

レートリミット発生時にサービスを止めないためのフォールバック設計例

AIプロバイダのAPIにはリクエスト数やトークン数に基づくレートリミットが設けられており、トラフィックが集中するとサービスが一時的に利用不可になります。Laravel AI SDKのフェイルオーバー機能はこのケースにも対応していますが、フェイルオーバーだけに依存するとコストが想定外に膨らむリスクがあります。

実運用で推奨されるフォールバック設計は、3段階の防御層を設けることです。第1層はSDK標準のフェイルオーバーで、プライマリプロバイダのレートリミット到達時にセカンダリへ切り替えます。第2層はLaravelのキュー機構を活用し、即時応答が不要な処理を遅延実行することでリクエストの集中を分散させます。第3層はアプリケーションレベルでのキャッシュ活用で、同一プロンプトに対する応答をRedisやデータベースに一定時間キャッシュし、API呼び出し自体を削減します。これら3層を組み合わせることで、単一プロバイダの障害やリミット到達がエンドユーザーの体験に影響しない設計が実現できます。

プロバイダ変更がコード修正ゼロで済むケースと改修が必要なケースの違い

Laravel AI SDKのプロバイダ抽象化は強力ですが、すべてのケースでコード修正がゼロになるわけではありません。プロバイダ変更の影響範囲を正しく見極めることが、移行計画の精度を左右します。

コード修正なしで切り替えられるのは、テキスト生成とStructured Outputを標準的に使用しているケースです。これらはSDKの抽象レイヤーが差異を吸収するため、config/ai.phpの設定変更だけで動作します。一方、プロバイダ固有のパラメータや機能に依存している場合は改修が必要です。たとえばOpenAIのDALL-Eに特化した画像生成パラメータを使っている場合、Geminiに切り替えるとそのパラメータが無視される可能性があります。また、トークン数やレスポンス形式の微妙な違いがテスト結果に影響することもあります。プロバイダ変更を想定するなら、SDK標準のメソッドとパラメータのみを使い、プロバイダ固有の拡張は使わないという設計方針を初期段階から徹底することが重要です。

5つのマルチエージェントパターンをLaravelで実装する際の設計判断基準

単一のエージェントで対応しきれない複雑なタスクには、複数のエージェントを連携させるマルチエージェントワークフローが有効です。Laravel AI SDKでは、Anthropicが提唱する5つの代表的なパターンをすべてPHPコードで実装できます。この章では、各パターンの構造と、どのようなユースケースでどのパターンを選択すべきかの判断基準を解説します。

Prompt Chainingの実装にPipelineを使う場合のペイロード設計例

Prompt Chainingは、あるエージェントの出力を次のエージェントの入力として連鎖させるパターンです。工場の組み立てラインのように、各ステップが1つの処理に特化し、結果を次のステップに渡します。Laravel AI SDKでは、フレームワーク標準のPipelineクラスを活用してこのパターンを実装できます。

実装のポイントはペイロードの設計です。パイプラインの各ステップは連想配列のペイロードを受け取り、自分の処理結果を追加して次のステップに渡します。たとえばコールドメール生成のワークフローでは、初期ペイロードに会社名と役職を含め、第1ステップ（下書きエージェント）がメール本文を追加し、第2ステップ（レビューエージェント）がスコアとフィードバックを追加し、第3ステップ（改善エージェント）がスコア不足の場合にのみメール本文を書き替えるという流れを構築します。レビューエージェントにはStructured Outputを適用し、パーソナライゼーションの有無やトーンスコアを数値で返させることで、改善ステップの実行判定を自動化できます。

分類エージェントで入力を振り分けるRoutingパターンの適用条件

Routingパターンは、最初に分類用のエージェントが入力の種類や複雑度を判定し、その結果に基づいて適切な専門エージェントにリクエストを振り分ける構成です。カスタマーサポートのように、問い合わせ内容が返金・技術サポート・一般質問と多岐にわたるケースで特に有効に機能します。

Laravel AI SDKでの実装は、分類エージェントにStructured Outputを持たせ、typeとcomplexityの2軸で入力を判定させる方式が標準的です。typeの値に応じてPHPのmatch式で専門エージェントのインストラクションを切り替え、complexityに応じて使用するモデルのグレードを変更します。単純な問い合わせには低コストのモデルを割り当て、複雑な問い合わせには高性能モデルを使うことで、品質とコストのバランスを最適化できます。Routingパターンが適しているのは、入力のバリエーションが広く、単一のプロンプトでは品質にばらつきが出るケースです。逆に、入力パターンが限定的な場合は分類ステップのコストが無駄になるため、Prompt Chainingの方が適切です。

Concurrency::runで並列実行するParallelizationの効果と制約

Parallelizationパターンは、互いに依存関係のないエージェントを同時に実行することで、処理時間を短縮するパターンです。LaravelのConcurrency::run()メソッドを使えば、JavaScriptのPromise.all()に相当する並列実行をPHPで実現できます。

代表的なユースケースはコードレビューです。セキュリティ観点・パフォーマンス観点・保守性観点の3つの専門エージェントを並列に実行し、すべての結果が揃った段階で統合エージェントが総合レポートを生成します。3つのレビューが直列実行では合計30秒かかるところ、並列実行なら最も遅いエージェントの実行時間（約10秒）で完了するため、体感速度が大幅に改善されます。ただし、並列実行にはいくつかの制約があります。各エージェントは独立したプロセスで動作するため、エージェント間でメモリを共有できません。また、全エージェントが同時にAPIリクエストを送信するため、レートリミットに到達しやすくなる点にも注意が必要です。並列数はプロバイダのレートリミットとサーバーのプロセス数上限を考慮して決定すべきです。

Orchestrator-Workersで動的にサブタスクを生成する構成の注意点

Orchestrator-Workersパターンは、オーケストレーターとなるエージェントがタスクを動的に分解し、ワーカーエージェントにサブタスクを割り当てる構成です。事前に処理ステップが固定されているPrompt Chainingとは異なり、入力の内容に応じてサブタスクの数や種類が変わるのが特徴です。

Laravel AI SDKでの実装では、オーケストレーターにツール呼び出し機能を持たせ、各ワーカーをツールとして登録します。オーケストレーターのLLMが入力を解析し、必要なワーカー（ツール）を判断して順次呼び出す仕組みです。たとえばドキュメント処理ワークフローでは、オーケストレーターが入力文書の種類を判定し、要約ワーカー・翻訳ワーカー・フォーマット変換ワーカーから必要なものだけを呼び出します。このパターンの注意点は、MaxStepsの設定です。サブタスクの数が動的に増えるため、MaxStepsが不足するとワーカーの呼び出し途中でエージェントが停止します。想定される最大サブタスク数の1.5倍程度をMaxStepsに設定するのが実務上の目安です。

Evaluator-Optimizerループで品質を担保する際の終了条件の決め方

Evaluator-Optimizerパターンは、生成エージェントが出力した結果を評価エージェントが採点し、基準を満たさなければ生成エージェントが再生成するというループ構造です。人間が原稿を校正して修正指示を出すプロセスをAIで再現するパターンといえます。

Laravel AI SDKでは、評価エージェントにStructured Outputを持たせ、スコアや承認フラグ、具体的な改善項目をJSONで返させます。生成エージェントはこのフィードバックを受けて再生成を行い、再び評価エージェントに提出するサイクルを繰り返します。このパターンで最も重要な設計判断は終了条件の設定です。スコアが一定値以上になったら終了する方式と、最大ループ回数に到達したら終了する方式の2つを併用するのが安全です。スコアだけで判定すると、LLMの評価が常に厳しい場合に無限ループに陥るリスクがあります。実務では最大3〜5回のループを上限とし、到達しなかった場合は最もスコアが高い出力を採用するフォールバック処理を組み込むことが推奨されます。

ベクトル検索・Embedding・RAG構築をLaravel単体で完結させる手順と制約

Laravel 13では、AI SDKのEmbedding機能とクエリビルダのベクトル検索サポートが組み合わさり、外部の検索エンジンを使わずにセマンティック検索やRAGパイプラインを構築できるようになりました。PostgreSQLとpgvector拡張を基盤としたこの仕組みは、Laravel単体で完結するAI検索の新しい選択肢です。この章では、実装手順と運用上の制約を整理します。

pgvectorとベクトル類似検索メソッドで実装するセマンティック検索の手順

Laravel 13のベクトル検索は、PostgreSQLのpgvector拡張と連携して動作します。まず、PostgreSQLにpgvector拡張をインストールし、テーブルにembeddingカラム（vector型）を追加するマイグレーションを作成します。データの挿入時にはAI SDKのEmbeddingクラスで文字列をベクトル化し、そのベクトルをembeddingカラムに保存します。

検索時には、クエリビルダのwhereVectorSimilarTo()メソッドを使用します。たとえばDB::table('documents')->whereVectorSimilarTo('embedding', 'ナパバレーのおすすめワイナリー')->limit(10)->get()のように記述すると、検索クエリの文字列が内部的にベクトル化され、embeddingカラムとのコサイン類似度に基づいて最も関連性の高いレコードが返されます。キーワードの完全一致ではなく意味的な近さで検索できるため、表記ゆれや類義語に強いのが特徴です。Eloquentのクエリスコープと組み合わせれば、ユーザー権限やカテゴリによる絞り込みとセマンティック検索を同時に実行することも可能です。

AI SDKのEmbeddingクラスで文字列からベクトルを生成する具体的な方法

文字列からベクトルを生成するには、AI SDKのEmbeddingクラスを使用します。基本的な呼び出しは非常にシンプルで、対象の文字列を渡すだけでベクトル値の配列が返されます。生成されたベクトルはfloat配列として取得でき、Eloquentモデルのembeddingカラムに直接保存できます。

Embeddingの生成にはAPIコールが発生するため、大量のドキュメントを一括処理する場合はバッチ処理の設計が必要です。LaravelのキューとJobを組み合わせ、ドキュメントの保存イベントにフックしてEmbedding生成Jobをディスパッチする設計が一般的です。この方式であれば、ユーザーの操作を待たせることなく非同期でベクトル化が完了します。なお、Embeddingの対応プロバイダはOpenAI・Gemini・Azure・Cohere・Mistral・Jina・VoyageAIの7社と選択肢が豊富です。ただし、プロバイダによってベクトルの次元数やモデルの性能が異なるため、途中でプロバイダを変更するとすべてのEmbeddingを再生成する必要がある点に留意が必要です。

SimilaritySearchツールをAgentに組み込むRAG構成の設計パターン

RAG（Retrieval-Augmented Generation）は、LLMが回答を生成する前に関連情報をデータベースから検索し、その情報を文脈として付与することで回答精度を向上させる手法です。Laravel AI SDKにはSimilaritySearchという組み込みツールが用意されており、エージェントのToolとして登録するだけでRAG構成を実現できます。

実装方法は、エージェントのtools()メソッドでSimilaritySearch::usingModel(Document::class, 'embedding')のように対象モデルとembeddingカラムを指定してツールを返すだけです。エージェントがプロンプトを受けると、LLMの判断でSimilaritySearchツールが呼び出され、関連ドキュメントが検索されます。検索結果はLLMのコンテキストに自動的に追加され、その情報を踏まえた回答が生成されます。社内ナレッジベースの検索や、商品カタログからの推薦システムなど、独自データに基づく回答が必要なユースケースで特に効果的です。検索結果の件数はSimilaritySearchの設定で制御でき、取得件数が多いほど文脈は豊かになりますがトークン消費も増加するため、用途に応じたバランス調整が求められます。

ファイルストア・ベクトルストアを使ったドキュメント検索の構築手順

Laravel AI SDKは、ローカルデータベースのベクトル検索に加え、OpenAIやGeminiが提供するクラウドベースのファイルストアとベクトルストアにも対応しています。大量のPDFや画像を含むドキュメントコレクションを扱う場合、プロバイダのクラウドストレージにファイルをアップロードし、複数の会話で再利用できる仕組みが提供されています。

構築手順は、まずFilesクラスでドキュメントをプロバイダにアップロードし、次にベクトルストアを作成してアップロード済みファイルを関連付けます。検索時にはSDK組み込みのFileSearchプロバイダツールをエージェントに登録することで、エージェントがベクトルストア内のドキュメントを意味検索できるようになります。メタデータによるフィルタリングにも対応しており、ドキュメントの種類やカテゴリで検索範囲を絞り込むことが可能です。この方式はpgvectorを使うローカル方式と比較して、インフラの管理負荷が低い反面、プロバイダのAPI料金が別途発生する点と、データが外部サービスに保存される点を考慮する必要があります。

外部検索サービス不要で済む範囲と専用エンジンが必要になる境界の判断

Laravel 13のベクトル検索機能は多くのユースケースをカバーしますが、すべてのケースで外部検索エンジンが不要になるわけではありません。適用範囲の見極めが、インフラコストと検索品質のバランスを左右します。

pgvectorとLaravelのクエリビルダによるセマンティック検索が十分に機能するのは、レコード数が数十万件以内で、検索のレイテンシ要件が100ミリ秒前後まで許容される場合です。社内ナレッジベース、商品カタログ、FAQデータベースなど、多くの業務アプリケーションはこの範囲に収まります。一方、数百万件を超えるデータセットでのミリ秒単位の応答が求められるケースや、ハイブリッド検索（キーワード検索とセマンティック検索の組み合わせ）が必要なケースでは、ElasticsearchやPineconeのような専用検索エンジンの導入を検討すべきです。また、マルチテナント環境でテナントごとにベクトルインデックスを分離する必要がある場合も、pgvector単体では管理が煩雑になるため、専用サービスの方が運用効率で優れることがあります。

画像生成・音声合成・文字起こしを含むマルチモーダル機能の活用条件

Laravel AI SDKはテキスト処理だけでなく、画像・音声・ドキュメントを扱うマルチモーダル機能を統一APIで提供しています。プロダクト内でビジュアルコンテンツや音声インターフェースを構築する際に、サードパーティのSDKを個別に統合する必要がなくなるのが大きな利点です。この章では、各マルチモーダル機能の実装方法と、活用にあたっての制約条件を整理します。

Image::ofで画像を生成する際のプロンプト指定とサイズ制御の方法

画像生成はAI SDKのImageクラスを使用して実行します。基本的な呼び出しはImage::of('キッチンカウンターに置かれたドーナツ')->generate()のように、テキストプロンプトを渡すだけで画像が生成されます。生成された画像はオブジェクトとして返され、文字列キャストすることで生のバイナリコンテンツを取得できます。

サイズや品質の制御には、メソッドチェーンで追加パラメータを指定します。landscape()で横長フォーマット、quality('high')で高品質モードを指定でき、タイムアウト値もtimeout(120)で秒単位に設定可能です。既存画像のリミックスにも対応しており、添付ファイルとして元画像を渡しつつプロンプトで変換指示を出す使い方が可能です。たとえば商品写真を印象派風に変換するといった処理を、数行のコードで実装できます。2026年3月時点で画像生成に対応しているプロバイダはOpenAI・Gemini・xAIの3社です。フェイルオーバー設定で複数プロバイダを指定すれば、1社が障害でも画像生成機能を維持できます。

Audio::ofによる音声合成とTranscriptionによる文字起こしの実装例

音声合成はAudioクラス、文字起こしはTranscriptionクラスで実行します。音声合成の基本コードはAudio::of('Laravelでコーディングするのが大好きです。')->generate()のように、テキストを渡すだけで自然な音声データが生成されます。文字起こしはTranscription::fromStorage('audio.mp3')->generate()のように、Laravelのストレージに保存された音声ファイルを指定して実行します。

音声合成の用途としては、アプリケーション内のアクセシビリティ機能、AIアシスタントの音声応答、ナレーション付きレポートの自動生成などが挙げられます。文字起こしは、会議録の自動テキスト化やカスタマーサポートの通話記録分析に活用できます。どちらの機能も戻り値はオブジェクト形式で、ストレージへの保存やレスポンスとしての返却が標準的なLaravelの方法で行えます。なお、音声合成はOpenAIとElevenLabsの2社、文字起こしはOpenAI・ElevenLabs・Mistralの3社が対応しています。処理時間が長くなる傾向があるため、ユーザー向け機能で使用する場合はキュー経由の非同期実行を検討すべきです。

エージェントへのPDF・画像添付で実現するマルチモーダル入力の手順

エージェントにテキストだけでなくPDFや画像を入力として渡すことで、マルチモーダルなAI処理が実現できます。Laravel AI SDKでは、prompt()メソッドのattachmentsパラメータにファイルを指定する形式で実装します。

具体的には、Files\Document::fromStorage('transcript.pdf')でストレージ上のPDFを添付したり、Files\Image::fromStorage('photo.jpg')で画像を添付したりできます。営業トランスクリプトの分析エージェントにPDFを渡して要約させる、商品画像をエージェントに渡して説明文を自動生成させるといったユースケースが典型的です。複数のファイルを同時に添付することも可能で、配列形式で複数のFiles\DocumentやFiles\Imageを指定します。ただし、添付ファイルのサイズが大きいとAPIリクエストの処理時間とトークン消費量が増加するため、大容量ファイルの場合はファイルストアにアップロードしてからFileSearchツール経由で参照する方式が効率的です。

マルチモーダル機能ごとに異なるプロバイダ制約と料金差の比較整理

マルチモーダル機能の活用を検討する際には、プロバイダごとの対応状況と料金体系の違いを正確に把握しておく必要があります。テキスト生成と異なり、マルチモーダル機能はプロバイダ間の対応差が大きく、選択の自由度が限定される領域です。

画像生成は3社、音声合成は2社が対応しており、フェイルオーバーによる可用性確保が可能です。一方、Rerankingは対応プロバイダが2社のみと選択肢が限定されるため、この機能に依存する設計ではリトライ戦略を慎重に検討する必要があります。プロダクトの収益モデルにAI機能のコストを織り込む際は、テキスト生成よりもマルチモーダル機能の方が単価が高い傾向にあることを考慮し、利用頻度と課金の関係を事前にシミュレーションしておくことが重要です。

音声・画像処理をキュー経由で非同期実行する場合のタイムアウト設計

マルチモーダル処理は、テキスト生成と比較してAPIの応答時間が長くなる傾向があります。画像生成では5〜15秒、音声合成や文字起こしではファイルサイズに応じてさらに長い処理時間が発生します。このため、ユーザーが操作するWebリクエスト内で同期的に実行すると、タイムアウトやUX悪化の原因になります。

推奨されるのは、Laravelのキュー機構を活用した非同期実行です。AI SDKはqueue()メソッドでキュー投入をサポートしており、(new ImageGenerator)->queue('商品のプロモーション画像を生成')->then(fn ($response) => ...)のように、完了後のコールバックを指定できます。キューワーカーのタイムアウト設定は、処理対象に応じて調整が必要です。画像生成であれば30秒、長い音声の文字起こしであれば120秒以上を設定します。Laravelのretry_after設定も連動して調整しないと、処理中のジョブが「失敗」と判定されて重複実行されるリスクがあります。キューの接続先にはRedisやSQSなどの信頼性の高いドライバーを使用し、失敗時のリトライ回数も明示的に設定しておくことが安定運用の基本です。

既存Laravel 12アプリからAI SDK導入へ移行する際の工数見積もりと注意点

Laravel 13へのアップグレードとAI SDKの導入は、多くの既存アプリケーションにとって現実的な選択肢です。Laravel 13自体は破壊的変更がゼロと公式に表明されていますが、PHPバージョンの引き上げや既存AIパッケージとの競合など、事前に確認すべき項目が存在します。この章では、移行の工数を最小化するための計画立案と、本番デプロイ前に完了すべきテスト戦略を解説します。

PHP 8.3必須化に伴うランタイム更新とComposer依存解決の確認手順

Laravel 13はPHP 8.3を最低動作要件としており、PHP 8.2以下では動作しません。そのため、現在PHP 8.2でLaravel 12を運用している場合は、まずPHPランタイムの更新が必要です。PHP 8.3はLTSではありませんが、2027年11月までセキュリティサポートが提供されるため、Laravel 13のサポート期間（セキュリティ修正2028年3月17日まで）と整合する期間で運用できます。

ランタイム更新後の確認手順は3ステップです。まずphp -vでバージョンが8.3以上であることを確認します。次にcomposer updateを実行し、既存の依存パッケージがPHP 8.3と互換性があるかを確認します。互換性のないパッケージがある場合はComposerがエラーを出力するため、該当パッケージのアップデートまたは代替パッケージへの切替を行います。最後に、PHP 8.3でパラメータ名が変更された箇所がないかを確認します。名前付き引数を使用しているコードがある場合、フレームワーク内部のパラメータ名変更によって動作が変わる可能性があるため、テストスイートの実行で問題がないことを検証します。

openai-php/laravelやPrismなど既存パッケージとの競合リスク評価

Laravel 13以前からopenai-php/laravelやecholabs/prismなどのサードパーティAIパッケージを使用していた場合、AI SDK導入時に競合が発生する可能性があります。Laravel公式のアップグレードガイドでも、これらのパッケージとの関係を事前に評価するよう注意喚起されています。

競合リスクの評価には、まず現在のコードベースでAI関連パッケージがどの範囲で使われているかを棚卸しします。特定のAPIラッパーとしてのみ使用している場合は、AI SDKへの移行で完全に置き換えられる可能性が高いです。一方、パッケージ固有の機能（プロバイダ独自のパラメータ調整やカスタムミドルウェアなど）に依存している場合は、AI SDKが同等の機能を提供しているかを個別に確認する必要があります。両方のパッケージを一時的に共存させることも技術的には可能ですが、サービスコンテナのバインディングやConfig名の衝突が起きる場合があるため、共存よりも段階的な置換の方がリスクが低い方針です。

AI SDK用マイグレーション追加時に既存テーブルと衝突しない確認方法

AI SDKのvendor:publishコマンドで公開されるマイグレーションは、agent_conversationsテーブルとagent_conversation_messagesテーブルを作成します。既存のデータベースにこれらと同名のテーブルが存在しない限り、衝突は発生しません。

確認手順としては、まずphp artisan migrate --pretendを実行し、マイグレーションが実行するSQL文を事前に確認します。このコマンドは実際にはデータベースを変更せず、実行予定のSQL文を出力するだけなので、安全にチェックできます。同名テーブルが既に存在する場合は、マイグレーションファイルを編集してテーブル名にプレフィックスを付与するか、既存テーブルの用途を確認して統合の可否を判断します。また、マルチデータベース構成で運用している場合は、AI SDKのテーブルがどの接続先に作成されるかをconfig/ai.phpで確認し、意図しないデータベースに作成されないよう設定を調整することが重要です。

段階的導入で工数を最小化するための3フェーズ移行計画の立て方

AI SDKの導入は、全機能を一度に移行するのではなく、3つのフェーズに分けて段階的に進めることで工数とリスクを最小化できます。この段階的アプローチは、既存機能の動作保証とAI機能の品質検証を並行して進められるのが利点です。

1. フェーズ1（1〜2日）：Laravel 13へのフレームワークアップグレードとAI SDKのインストール。この段階ではAI機能はまだ使用せず、既存機能の動作確認に集中します。composer require laravel/aiとマイグレーションの実行まで完了させ、テストスイートが全件パスすることを確認します。
2. フェーズ2（3〜5日）：新規のAI機能を1つ選び、AI SDKで実装します。たとえばテキスト要約や問い合わせの自動分類など、失敗時の影響が小さい機能から着手します。この段階でエージェント設計・ツール実装・テストの一連の流れを習得します。
3. フェーズ3（1〜2週間）：既存のサードパーティAIパッケージをAI SDKに段階的に置換します。パッケージごとに移行・テスト・デプロイのサイクルを回し、問題が発生した場合は個別にロールバックできる粒度を維持します。

この3フェーズ計画の合計は2〜3週間程度であり、チームの規模やAI機能の複雑さに応じて調整が可能です。各フェーズの完了基準を事前に明確にしておくことで、スケジュールの遅延を早期に検知できます。

本番デプロイ前に実施すべきFakeによるエージェントテストの網羅範囲

Laravel AI SDKは、テスト環境でAPIを実際に呼び出すことなくエージェントの動作を検証するFake機能を標準で提供しています。エージェント・画像・音声・文字起こし・Embedding・Reranking・ファイルストアのすべてに対応するFakeが用意されており、本番デプロイ前のテストカバレッジを効率的に確保できます。

テストで網羅すべき範囲は、大きく4つに分類できます。

• エージェントのプロンプト応答テスト：Fakeで期待するレスポンスを設定し、アプリケーションコードが正しくレスポンスを処理するかを検証
• Structured Outputのスキーマ検証テスト：返却されるJSONが定義したスキーマに準拠しているかを確認
• ツール呼び出しのテスト：エージェントが正しいタイミングで正しいツールを呼び出すことを検証
• フェイルオーバーのテスト：プライマリプロバイダのFakeでエラーを返し、セカンダリプロバイダに正しく切り替わるかを確認

これらのテストはCI/CDパイプラインに組み込み、毎回のデプロイ前に自動実行される体制を構築することが推奨されます。APIのモック化によりテスト実行速度が高速かつ無料に保たれるため、テスト数を増やしても開発サイクルに影響しません。