--- title: "Laravel 13のAI SDK入門｜1.x対応の導入手順・Agent実装・Skills・ベクトル検索" url: "https://www.issoh.co.jp/tech/details/11482/" published: 2026-03-23 updated: 2026-10-18 categories: ["Laravel"] publisher: "株式会社一創" --- # Laravel 13のAI SDK入門｜1.x対応の導入手順・Agent実装・Skills・ベクトル検索 Laravel AI SDK（`laravel/ai`）は、OpenAI・Anthropic・Geminiなどのプロバイダを1つのAPIで扱うLaravel公式のパッケージです。2026年2月に0.x系のベータとして公開され、[2026年9月23日にv1.0がリリース](https://laravel.com/blog/introducing-laravel-ai-sdk-v1)されました。2026年10月18日時点の最新は v1.2.3 です。 この記事では、導入の3手順、Agent・ミドルウェア・Skills・人手承認の書き方、0.xから1.0へ上げるときの破壊的変更、ベクトル検索の対応データベースを扱います。コードと挙動は Laravel 13.37.0 に v1.2.3 を入れ、fakeを使ったテストで確かめた結果です。Laravel本体のバージョン選びやサポート期限は[Laravelの最新バージョンは13｜対応PHPバージョン・サポート期限一覧とアップグレード判断](/tech/details/5637/)で扱っています。 ## まとめ｜Laravel AI SDK 1.xの要点 - `laravel/ai` は2026年9月23日の v1.0.0 で安定版になり、その後3週間で v1.1.0（Skills・Cohereのテキスト生成）、v1.2.0、v1.2.3 と更新されています。分類（Classification）だけは experimental 扱いで、マイナー更新でも仕様が変わります。 - 導入は `composer require laravel/ai`、`vendor:publish`、`migrate` の3手順です。依存は `illuminate/*: ^12.0|^13.0` なので、Laravel 12.62以降・PHP 8.3以上なら13へ上げずに使えます。 - 0.11から1.0への移行ガイドは24項目あり、影響度Highが6件です。会話テーブルの `tool_calls`・`tool_results` 列が `steps` 列へ置き換わるため、既存データのバックフィルが要ります。 - 1.0でミドルウェアはプロンプト1回ではなく生成ステップごとに走るようになり、1.1でエージェントにSkillsを渡せるようになりました。 - `continue()` は会話の持ち主を検証しません。別ユーザーの会話IDを渡しても続きが書き込めることを実測で確認したので、再開の前に認可を挟みます。 - ベクトル検索の `whereVectorSimilarTo` はPostgreSQL＋pgvector・MariaDB 11.7以上が対象です。MySQLで呼ぶと `RuntimeException` になります。 ## AI SDKの現在地と、Boost・Laravel MCPとの役割分担 ### v1.0で安定版になった時期とその後の更新 初版の v0.1.0 は2026年2月5日に公開され、0.x系のあいだはマイナー更新ごとに破壊的変更が入っていました（0.9と0.10の移行ガイドには影響度Highの項目があります）。2026年9月23日の v1.0.0 で、会話の保存形式・ミドルウェア・トークン集計・ストリーミングのプロトコルが固まりました。 | 版 | 公開日 | 主な追加 | | ------------ | ------------- | ------------------------------------------------- | | v1.0.0 | 2026-09-23 | 分類、AG-UI／Vercel Chat対応、ステップ単位のミドルウェア、`ToolSearch` | | v1.0.1 | 2026-09-29 | `Ai::build()`（テナントごとの認証情報） | | v1.1.0 | 2026-10-05 | Agent Skills、Cohereのテキスト生成、組み込みツールの承認 | | v1.2.0 | 2026-10-07 | OpenAIでの画像付き分類、Anthropicの既定モデル更新 | | v1.2.1〜1.2.3 | 2026-10-12〜15 | Stopミドルウェア、Retry-After待ちの再試行、Laravel 12向け修正 | 1.x系ではマイナー更新に破壊的変更を入れない前提ですが、例外があります。[公式のUPGRADE.md](https://github.com/laravel/ai/blob/1.x/UPGRADE.md)は1.2の項で「Classification is an experimental API, so this change ships in a minor release」と書き、分類APIのシグネチャをマイナー更新で変えています。分類を独自プロバイダで実装している場合は、`^1.0` のままでも更新のたびに差分を確認します。 ### AI SDK・Boost・Laravel MCPの3層 | パッケージ | 担当 | 使う場面 | | -------------- | --------- | --------------------------------- | | Laravel AI SDK | アプリ内のAI機能 | 要約・分類・チャット・検索など利用者が触る機能 | | Laravel Boost | 開発者の手元 | Claude CodeやCursorにルート・スキーマ・ログを渡す | | Laravel MCP | 外部AIへの公開 | 自社アプリの機能をMCPツールとして見せる | `laravel/ai` の依存に `laravel/mcp` は含まれず、手元のインストールでも入りませんでした。ただしアプリが `laravel/mcp` を直接使っている場合、AI SDK 1.0は1.0未満の `laravel/mcp` と共存できないため、先に `^1.0` へ上げます。Boostが提供するMCPツールの一覧は[Laravel Boostとは？2系のMCPツール10種と対応エディタ・laravel/mcpとの違い](/tech/details/8419/)にまとめています。 ## 導入の3手順と、Laravel 12で使える範囲 ### インストールから環境変数までの流れ ``` composer require laravel/ai php artisan vendor:publish --provider="Laravel\Ai\AiServiceProvider" php artisan migrate ``` `vendor:publish` で `config/ai.php`、マイグレーション、4種類のスタブ（agent・structured-agent・tool・agent-middleware）が公開されます。認証情報は `.env` に置き、公式ドキュメントが挙げる変数は `ANTHROPIC_API_KEY`・`OPENAI_API_KEY`・`TYPESAFE_API_KEY` など17種類です。マルチテナントでテナントごとのAPIキーを使うなら、v1.0.1で入った `Ai::build(['driver' => 'anthropic', 'key' => $user->anthropic_key])` を、`provider: [Ai::build([...])]` のように配列で包んで渡します。 ### マイグレーションで作られる会話テーブルの列 `migrate` で `agent_conversations` と `agent_conversation_messages` の2表ができます。1.xのメッセージ表は `steps`（longText）と `status` を持ち、0.x系の `tool_calls`・`tool_results`・`approval_state` はありません。fakeで1往復させると、userとassistantの2行が入り、assistant行の中身は次のとおりでした。 ``` role=assistant status=completed steps=[{"content":"VPNはCiscoのクライアントで接続します。","tool_calls":[],"reasoning":"","replay_blocks":[],"provider_tool_calls":[]}] usage={"input_tokens":0,"output_tokens":0,"cache_read_input_tokens":null,"cache_write_input_tokens":null,"reasoning_tokens":null} ``` `steps` はモデルとの往復1回につき1要素で、ツールの実行結果は呼び出しの要素の中に入ります。会話ログをSQLで集計している場合、0.x時代のクエリは列名から書き直しになります。マイグレーションの基本操作は[Laravelマイグレーションの使い方｜php artisan migrateとrollback・freshの挙動を13.xで検証](/tech/details/7253/)で扱っています。 ### Laravel 12で動く範囲と、13でしか使えない機能 Packagist上の v1.2.3 が要求するのは `php: ^8.3`、`illuminate/*: ^12.0|^13.0`、`illuminate/json-schema: ^12.62|^13.15` です。Laravel 12.62以降でPHP 8.3以上なら導入でき、v1.2.3でも「Keep conversation models non-incrementing on Laravel 12」という12系向けの修正が入っています。 クエリビルダの `whereVectorSimilarTo`、`vector()` カラム、`Schema::ensureVectorExtensionExists()` は v12.47.0（2026年1月13日）から12系にもあります。13系にしか無いのは、配列とベクトル形式を相互変換する `AsVector` キャストです。12系でベクトル列を扱うならキャストを自作します。 ## Agentクラスの構造と、属性・ミドルウェアによる制御 ### make:agentで生成される3つのメソッド `php artisan make:agent SupportAgent` を実行すると、`app/Ai/Agents` に `Agent`・`Conversational`・`HasTools` を実装したクラスができ、メソッドは `instructions()`・`messages()`・`tools()` の3つです。`--structured` を付けると `HasStructuredOutput` と `schema()` が加わります。 ``` namespace App\Ai\Agents; use Laravel\Ai\Concerns\RemembersConversations; use Laravel\Ai\Contracts\Agent; use Laravel\Ai\Contracts\Conversational; use Laravel\Ai\Contracts\HasTools; use Laravel\Ai\Promptable; class SupportAgent implements Agent, Conversational, HasTools { use Promptable, RemembersConversations; public function instructions(): string { return '社内ヘルプデスクとして、社内規程に沿って回答します。'; } public function tools(): iterable { return [new \App\Ai\Tools\LookupOrder]; } } ``` 会話履歴をデータベースに任せるなら、生成された `messages()` を消して `RemembersConversations` トレイトを使います。`messages()` を残すとトレイトより優先され、履歴が読み込まれません。ワンショットの変換なら `use function Laravel\Ai\{agent};` で読み込む匿名エージェントで足ります。ツール・ミドルウェア・fakeを使うものはクラスにします。 ### 動作を決める属性 | 属性 | 役割 | | ---------------------------------------- | --------------------------------- | | Provider ／ Model | プロバイダとモデル（Providerは複数指定でフェイルオーバー） | | MaxSteps ／ MaxTokens | ツール利用時のステップ上限 ／ 生成トークン上限 | | Temperature ／ TopP | サンプリング（0.0〜1.0） | | Timeout | HTTPタイムアウト秒（既定60） | | UseCheapestModel ／ UseSmartestModel | プロバイダの最安 ／ 最上位モデルを自動選択 | | CacheInstructions ／ CacheToolDefinitions | AnthropicとBedrockでキャッシュ位置を指定 | `UseCheapestModel` と `UseSmartestModel` が選ぶモデルはSDKの更新で変わります。実際に v1.1.0 で多くのプロバイダの既定モデルが新しくなり、v1.2.0 でAnthropicの既定が更新されました。SDK更新による使用モデルの切り替わりを避けたい本番のエージェントでは、`#[Model('...')]` でモデルを明示します。 ### ミドルウェアの実行単位と生成ステップの制御 1.0から、ミドルウェアはプロンプト1回ではなく生成ステップ（モデルとの往復）ごとに呼ばれます。モデルとの往復が3回の実行なら3回です。1回の往復で複数のツールを呼ぶこともあるので、ツールの呼び出し回数とは一致しません。`php artisan make:agent-middleware TrimTools` で雛形ができ、`handle()` は `PendingStep` を受け取ります。 ``` use Closure; use Laravel\Ai\PendingStep; class TrimTools { public function handle(PendingStep $step, Closure $next) { if (! $step->isFirstStep()) { $step = $step->withoutTools('SearchDocumentation'); } return $next($step); } } ``` この例は、高価な検索ツールを2ステップ目以降で外します。`PendingStep` には `withModel()`・`withMessages()`・`withMaxTokens()` などがあり、途中でモデルを安いものに替えたり、長い履歴を要約に差し替えたりできます。エージェント側は `HasMiddleware` を実装して `middleware()` で配列を返します。0.x時代の `AgentPrompt` を受け取るミドルウェアは、そのままでは動きません。 ## Tool・Skills・会話の永続化・人手承認 ### make:toolで作るツールと、ツール定義の遅延読み込み `php artisan make:tool LookupOrder` で `app/Ai/Tools` にクラスができ、`description()` で用途を、`schema()` で引数を、`handle()` で処理を書きます。スキーマで縛ってもモデルの出力は外れることがあるため、`handle()` 内で `$request->validate([...])` を呼んで再検証できます。 ツールが30個あると、30個分の定義が毎リクエスト送られます。使う頻度の低いツールは `new ToolSearch(tools: [...])` で包むと、プロバイダが必要なときだけ読み込みます。対応はOpenAI・Azure・Anthropicで、Anthropicでは包まないツールを最低1つ残す必要があります。 ### Skillsによる手順書の登録と遅延読み込み v1.1.0で、[Agent Skillsとは？SKILL.md仕様と46製品で動かす移植性の実装手順](/tech/details/17685/)で解説している `SKILL.md` 形式の手順書を、アプリのエージェントにも読ませられるようになりました。`resources/skills/<名前>/SKILL.md` を置き、エージェントに `HasSkills` を実装します。 ``` namespace App\Ai\Agents; use Laravel\Ai\Concerns\RemembersConversations; use Laravel\Ai\Contracts\Agent; use Laravel\Ai\Contracts\Conversational; use Laravel\Ai\Contracts\HasSkills; use Laravel\Ai\Promptable; class HelpDesk implements Agent, Conversational, HasSkills { use Promptable, RemembersConversations; public function instructions(): string { return '社内ヘルプデスクとして、社内規程に沿って回答します。'; } public function skills(): iterable { return [resource_path('skills')]; } } ``` エージェントには `LoadSkill` ツールが1つ足され、ツールの説明文にスキル名とdescriptionの一覧が並びます。本文は呼ばれたときだけ読み込まれます。frontmatterに `description` の無いスキルを置いて試すと一覧に出ず、名前を指定しても「Skill \[no-desc\] does not exist.」が返りました。同梱ファイルは256KBを超えるものとバイナリは返されません。`base_path('.agents/skills')` を足せば、コーディングエージェントと同じスキルをアプリでも使えます。 ### 会話の永続化と、再開時の認可 新しい会話は `(new HelpDesk)->forUser($user)->prompt('...')` で始め、返り値の `conversationId` を保存します。続きは `continue($id, as: $user)`、IDが無ければ新規にする `continueOrStart()` は1.0で入りました。参加者はポリモーフィックで保存されるため、UserのID 1とTeamのID 1の履歴は混ざりません。 注意したいのは、`continue()` が会話の持ち主を確かめない点です。ユーザーAが始めた会話のIDを使い、ユーザーBで `continue($id, as: $b)` を呼ぶテストを書いたところ、例外にならず同じ会話に participant\_id=2 の行が追記されました。会話IDをURLやフォームから受け取る画面では、`ConversationStore` の `conversationBelongsTo($id, $user->getMorphClass(), $user->id)` で持ち主を確かめてから再開します（同じテストでAはtrue、Bはfalseでした）。 ### 破壊的な操作に承認を挟む仕組み ファイル削除や返金のような操作は、ツールに `Approvable` を実装し `InteractsWithApprovals` トレイトを使うと、実行前にエージェントが一時停止します。再開時は `Decisions::from(['call_abc' => Decision::approve(), 'call_ghi' => Decision::reject('請求書は保管が必要です')])` のように、保留中の呼び出しすべてに判断を渡します。判断が欠けたIDがあると `ApprovalMismatchException` です。理由付きの拒否はモデルに返って応答が続き、理由なしの拒否はその場で生成を止めます。v1.1.0からは、MCP・ファイル操作・類似検索などの組み込みツールにも `requireApproval()` を付けられます。 ## 対応プロバイダとフェイルオーバーの条件 ### 機能別の対応プロバイダ一覧（2026年10月） - **テキスト（13）**：OpenAI、OpenAI互換、Anthropic、Gemini、Azure、Bedrock、Groq、xAI、DeepSeek、Mistral、Ollama、OpenRouter、Cohere - **画像**：OpenAI、Gemini、xAI、Azure、Bedrock、OpenRouter - **音声合成**：OpenAI、ElevenLabs、Gemini、Mistral、OpenRouter - **文字起こし**：OpenAI、OpenAI互換、ElevenLabs、Groq、Mistral、Gemini、OpenRouter - **Embedding**：OpenAI、OpenAI互換、Gemini、Azure、Bedrock、Cohere、Mistral、Jina、VoyageAI、Ollama、OpenRouter - **Reranking**：Cohere、Jina、VoyageAI、Bedrock、OpenRouter - **分類**：OpenAI、TypeSafe、OpenRouter - **ファイル**：OpenAI、Anthropic、Gemini、Azure、OpenRouter 出典は[公式ドキュメントのProvider Support表](https://laravel.com/framework/docs/13.x/ai-sdk)です。Ollamaはテキスト生成とEmbeddingだけで、画像・音声・文字起こしには使えません。Bedrockを使う場合、1.0から `aws/aws-sdk-php` が同梱されなくなったので、自分で `composer require aws/aws-sdk-php` を実行します。 ### フェイルオーバーが発動する例外の範囲 ``` $response = (new SupportAgent)->prompt( '注文の配送状況を教えてください', provider: [Lab::OpenAI, Lab::Anthropic], ); ``` 2社目へ切り替わるのは `FailoverableException` のときだけで、レート制限（`RateLimitedException`）、過負荷・利用不可（`ProviderOverloadedException`）、クレジット不足（`InsufficientCreditsException`）が該当します。バリデーションエラーや不正なリクエストでは切り替わりません。v1.2.1からは、レート制限や過負荷の応答に10秒以下の `Retry-After` が付いていれば、その秒数だけ待って同じプロバイダへ1回だけ再試行し、それでも失敗したら切り替えます（`HandlesFailoverErrors` の `retry(2, ...)`）。プロバイダごとにモデルを指定する配列のキーには `Lab::Gemini->value` のように列挙型の値を使います。 ## 分類（Classification）とプロバイダツール ### Classificationによる問い合わせ分類と判定しきい値 1.0で、自由文ではなく型の決まった答えと確率を返す分類が加わりました。問い合わせの振り分けやモデレーションで、しきい値と比べる処理に向いています。 ``` use Laravel\Ai\Classification; use Laravel\Ai\Classification\Boolean; use Laravel\Ai\Classification\Choice; $result = Classification::of($ticket)->questions([ 'urgent' => new Boolean('すぐに返答が必要か'), 'team' => new Choice('担当チームはどこか', [ 'billing' => '支払い・請求・返金', 'technical' => '不具合・障害・連携', ]), ])->classify(); $result['urgent']->isTrue(threshold: 0.8); $result['team']->choice; ``` Yes／Noを1問だけ聞くなら `Str::of($message)->decide('Is this spam?')` が真偽値を返します。分類は公式ドキュメントでも experimental と明記されており、v1.2.0で実際にシグネチャが変わりました。業務の判定ロジックに組み込むなら、判定結果をテストで固定し、更新のたびに通るかを確かめます。 ### Web検索・コード実行などのプロバイダツール プロバイダ側で実行されるツールは `tools()` に並べるだけで使えます。対応はツールごとに違います。 | ツール | 対応プロバイダ | | --------------- | ------------------------------------------------------------- | | `WebSearch` | Anthropic ／ OpenAI ／ Azure ／ Gemini ／ xAI ／ Groq ／ OpenRouter | | `WebFetch` | Anthropic ／ Gemini ／ OpenRouter | | `CodeExecution` | Anthropic ／ OpenAI ／ Azure ／ Gemini ／ xAI ／ Groq（GPT-OSSのみ） | Anthropicのストリーミングでサーバー側のWeb検索を使うと、1.0以降は `message_delta` の累計値を読むため、0.x時代より入力トークンが多く報告されます。コスト計算を `promptTokens` に単価を掛ける方式で組んでいた場合は、次章の集計変更とあわせて見直します。 ## ベクトル検索とRAG構築の要件 ### 対応データベースと、MySQLで呼んだときのエラー 公式ドキュメントの検索ページは、ベクトル検索の対応をpgvector拡張を入れたPostgreSQL、MariaDB 11.7以上、Laravel MongoDBパッケージを入れたMongoDBとしています（クエリビルダとAI SDKのページはPostgreSQLとMariaDBの2種類のみ）。手元で接続ごとに `whereVectorSimilarTo` のSQLを組み立てると、結果は次のとおりでした。 ``` pgsql: select * from "documents" where ("embedding" <=> ?) <= ? order by ("embedding" <=> ?) asc limit 10 mariadb: select * from `documents` where vec_distance_cosine(`embedding`, vec_fromtext(?)) <= ? ... mysql: RuntimeException: Vector distance queries are only supported by Postgres and MariaDB. sqlite: RuntimeException: Vector distance queries are only supported by Postgres and MariaDB. ``` MySQLのまま実装するなら、OpenAIやGeminiのベクトルストアへファイルを預ける `FileSearch` 構成か、外部の検索サービスを使う構成になります。全文検索の `whereFullText` はMySQLでも動くので、要件の違いに注意します。 ### カラム定義とHNSWインデックスの張り方 ``` Schema::ensureVectorExtensionExists(); Schema::create('documents', function (Blueprint $table) { $table->id(); $table->text('content'); $table->vector('embedding', dimensions: 1536)->index(); $table->timestamps(); }); ``` 次元数は埋め込みモデルの出力に合わせます。`index()` でHNSWインデックスが作られます（パラメータの考え方は[HNSWとは？階層グラフの仕組みとM・ef\_constructionの決め方を実装目線で解説【2026年版】](/tech/details/16468/)）。`whereVectorSimilarTo` の `minSimilarity` は既定0.6で、SQLには「距離が1−0.6＝0.4以下」として渡ります。`minSimilarity: 0.4` を指定すると距離0.6以下まで広がることを、上のSQLのバインド値で確認しました。第2引数に文字列を渡すと、AI SDKが `Stringable` に登録する `toEmbeddings()` マクロで埋め込みが自動生成されます。 ### 検索ツールをエージェントに組み込む手順 ``` public function tools(): iterable { return [ SimilaritySearch::usingModel(Document::class, 'embedding'), ]; } ``` エージェントが必要と判断したときに類似検索を実行し、結果を文脈へ取り込みます。埋め込みをまとめて作るなら `Embeddings::for([...])->generate()` で1回のAPIコールに収め、並べ替えを詰めたいときは `Reranking::of([...])->rerank('PHP frameworks')` を重ねます。 ## 画像・音声・文字起こしとテストの書き方 ### Image・Audio・Transcriptionとキュー ``` $image = Image::of('キッチンカウンターに置かれたドーナツ')->generate(); $audio = Audio::of('Laravelでのコーディングが好きです。')->generate(); $transcript = Transcription::fromStorage('audio.mp3')->generate(); ``` 画像生成や長い音声の文字起こしは `queue()` でバックグラウンドへ回し、`then()` と `catch()` に完了時と例外時の処理を登録します。キューワーカーの `--timeout` と `retry_after` の関係は通常のジョブと同じで、`--timeout` は `retry_after` より数秒短く設定します。この大小関係が逆転すると、処理中のジョブが再試行され、二重実行につながる可能性があります（[Laravel Queueの使い方｜ジョブ定義からworker常駐と失敗ジョブ運用まで](/tech/details/17154/)）。 ### fakeによる無課金のテスト ``` HelpDesk::fake(['VPNはCiscoのクライアントで接続します。']); $response = (new HelpDesk)->forUser($user)->prompt('VPNの接続方法は？'); HelpDesk::assertPrompted('VPNの接続方法は？'); ``` エージェント・画像・音声・文字起こし・Embedding・Reranking・分類・ファイル・ベクトルストアのそれぞれにfakeがあります。fakeでも `RemembersConversations` は実際のテーブルに書き込むので、上の `steps` 列の確認はこのテストで行いました。構造化出力のエージェントに値を渡さずfakeすると、スキーマに沿ったダミー値が入ります。手元では `{"value":"fq"}` のような無意味な文字列だったので、値で分岐する処理のテストでは返り値を明示します。 ## 0.xから1.0へ上げるときの破壊的変更 ### Likelihood Of Impact: Highの6項目 UPGRADE.mdの「Upgrading To 1.0 From 0.11」は24項目あり、影響度はHigh 6・Medium 9・Low 9です（2026年10月18日時点の1.xブランチで数えた値）。Highは次の6件です。 1. **laravel/mcp 1.0が必須**：1.0未満とは競合します。直接使っているなら `^1.0` へ。 2. **会話メッセージが steps を保存**：`tool_calls`・`tool_results`・`approval_state` を `steps`・`status` へ移すバックフィルのマイグレーションを自分で作って流します。承認待ちの会話は移行前に片付けておかないと再開できません。 3. **ミドルウェアがステップ単位**：`handle(AgentPrompt $prompt, ...)` を `handle(PendingStep $step, ...)` に書き換えます。 4. **Geminiのベクトルストアへの取り込みが完了待ち**：`addFile()` の戻り値が操作名からドキュメント名に変わり、5分で終わらなければ `AiException` です。 5. **AWS SDKが既定で入らない**：Bedrock利用時は `aws/aws-sdk-php` を直接追加します。 6. **トークン数が全量に**：`promptTokens`・`completionTokens` が `inputTokens`・`outputTokens` に改名され、キャッシュ分と推論分を含む値になりました。既存の `usage` 列の行は旧キーのままです。 課金の集計をしているなら6番目が最も効きます。入力トークンに単価を1つ掛けていた計算は、`uncachedInputTokens()`・`cacheReadInputTokens`・`cacheWriteInputTokens` に分けて単価を掛ける形へ変えます。旧キーと新キーの行が同じ列に混在するので、レポートは両方を読めるようにします。 ### Boostの/upgrade-ai-sdk-v1で進める手順 ``` composer require laravel/boost:^2.10 --dev -W php artisan boost:install ``` Boost 2.10.0以上を入れると、Claude Code・Cursor・OpenCode・VS Codeなどで `/upgrade-ai-sdk-v1` が使え、移行ガイドを1項目ずつ当てていきます。ただしバックフィルのマイグレーションは本番データに触るので、ステージングで行数と `status` の分布を確かめてから流します。Boostの導入時の選択肢は[Laravel Boostの使い方｜boost:installの選択肢とSkills・エージェント別設定【v2.10対応】](/tech/details/10856/)にまとめています。 ## Laravel 12から13へ上げる判断と破壊的変更 ### 影響度Highの項目とインストーラーの更新 AI SDKは12系でも動くので、13へ上げる理由はAI SDK以外で決めます。[Laravel 13のアップグレードガイド](https://laravel.com/framework/docs/13.x/upgrade)は想定所要時間を10分としています。本文で「Likelihood Of Impact: High」と明記されるのは2件ですが、目次の「High Impact Changes」にはインストーラー更新を含む3項目が掲載されています。 - **依存の更新**：`laravel/framework` を `^13.0`、`laravel/boost` を `^2.0`、`laravel/tinker` を `^3.0`、`phpunit/phpunit` を `^12.0`、`pestphp/pest` を `^4.0` へ。 - **CSRFミドルウェアの改称**：`VerifyCsrfToken` が `PreventRequestForgery` になり、`Sec-Fetch-Site` ヘッダによるオリジン検証が加わりました。旧名は非推奨エイリアスとして残りますが、テストの `withoutMiddleware()` は書き換えます。 Laravelインストーラーを使っている場合は `composer global update laravel/installer` も必要です。この項目は本文に影響度のラベルが無く、目次でHigh Impact Changesに入っています。Laravel 12のアプリにBoost ^2.0を入れると `/upgrade-laravel-v13` で移行を任せられます。 ### 影響度Mediumの2項目（serializable\_classes・upsert） キャッシュ設定に `serializable_classes` が加わり、既定は `false` です。`APP_KEY` が漏れたときのデシリアライズ攻撃を防ぐための変更で、キャッシュにPHPオブジェクトを入れているアプリは許可するクラスを列挙するか、配列で保存する形に変えます。もう1件は `upsert` で、MySQLとMariaDBでは `uniqueBy` の値が使われないにもかかわらず、空だと `InvalidArgumentException` になりました。 ## よくある質問 ### Laravel AI SDKは正式版（安定版）ですか？ はい。2026年9月23日の v1.0.0 で安定版になり、2026年10月18日時点の最新は v1.2.3 です。ただし分類（Classification）は experimental で、マイナー更新でもシグネチャが変わります。2026年9月以前の記事に「0.x系」「ベータ」とあるのは当時の情報です。 ### Laravel 12のままAI SDKを使えますか？ 使えます。v1.2.3の依存は `illuminate/*: ^12.0|^13.0`、`illuminate/json-schema: ^12.62|^13.15`、`php: ^8.3` で、Laravel 12.62以降でPHP 8.3以上なら導入できます。`AsVector` キャストだけは13系にしか無いため、12系でベクトル列を扱う場合は自作します。 ### MySQLでベクトル検索は使えますか？ 使えません。MySQL接続で `whereVectorSimilarTo` を呼ぶと「Vector distance queries are only supported by Postgres and MariaDB.」の `RuntimeException` になります。PostgreSQL＋pgvectorかMariaDB 11.7以上に移すか、プロバイダ側のベクトルストアを使う `FileSearch` で代替します。 ### Ollamaでローカルモデルを使えますか？ テキスト生成とEmbeddingでは使えます。画像・音声合成・文字起こしの対応表にOllamaは含まれていません。v1.2.1からは、次元数を設定しないとOllamaのモデルが持つ次元数をそのまま使います。 ### Laravel 13にLTS版はありますか？ 現在のLaravelにLTSという区分はありません。Laravel 13はバグ修正が2027年第3四半期まで、セキュリティ修正が2028年3月17日までで、対応PHPは8.3から8.5です（[公式リリースノート](https://laravel.com/framework/docs/13.x/releases)）。 ### openai-php/laravelやPrismから移行する必要はありますか？ 必須ではありません。Laravel 13のアップグレードガイドにこれらのパッケージへの言及は無く、共存もできます。AI SDKへ寄せる利点は、fake・会話の永続化・人手承認・フェイルオーバーがフレームワークの流儀で揃う点です。移すなら機能単位で置き換え、まずテストをAI SDKのfakeで書き直すと切り戻しやすくなります。社内チャットボットやRAGの設計から相談したい場合は、[AIチャットボット開発](https://www.issoh.co.jp/service/ai/chatbot/)の支援も行っています。 ## 関連記事 - [Laravelの最新バージョンは13｜対応PHPバージョン・サポート期限一覧とアップグレード判断](/tech/details/5637/) - [Laravel Boostとは？2系のMCPツール10種と対応エディタ・laravel/mcpとの違い](/tech/details/8419/) - [Agent Skillsとは？SKILL.md仕様と46製品で動かす移植性の実装手順](/tech/details/17685/) - [Laravel Queueの使い方｜ジョブ定義からworker常駐と失敗ジョブ運用まで](/tech/details/17154/) - [Laravelの将来性を2026年のデータで判断する｜サポート期限・求人単価・AI対応](/tech/details/5469/) --- 出典: [Laravel 13のAI SDK入門｜1.x対応の導入手順・Agent実装・Skills・ベクトル検索]()（株式会社一創）