CatchAdmin PHP 后台管理框架 Logo CatchAdmin

Laravel AI SDK v1.0 正式发布 ​

Laravel AI SDK v1.0 已正式发布：通过一套 Laravel 原生 API 接入所有提供商，并支持对话存储、流式聊天、智能体、工具审批和 Jev 分类。

Laravel AI SDK v1.0 于今日正式发布。

今年早些时候，Laravel AI SDK 进入 Beta 测试阶段，并承诺通过一套优雅的 Laravel 原生 API 接入所有提供商。

为了推出 v1.0，开发团队进行了充分打磨，修复了数百个错误，推出了极为强大的功能，并为 SDK 加入了全新的 AI 形态。

首先，使用 Composer 安装 Laravel AI SDK：

bash
composer require laravel/ai

如需了解更多信息，可观看这个展示真实应用场景的视频：

一种全新的模型 ​

有些 AI 工作完全不涉及写作。分派工单、标记评论、选择工作流中的分支：这些都属于需要快速且低成本完成的分类决策。

Jev 的创建者 TypeSafe 将这类模型称为“系统一模型”（System One models）。如今，Laravel AI SDK 已将分类作为一项独立能力，与文本、图像、音频和嵌入并列。Jev 能在几毫秒内回答分类问题，成本仅为传统 LLM 的一小部分：

php
use Laravel\Ai\Classification;
use Laravel\Ai\Classification\Boolean;
use Laravel\Ai\Classification\Choice;
use Laravel\Ai\Classification\Score;

$response = Classification::of($ticket->body)->questions([
    'is_urgent' => new Boolean('Does this message convey urgency?'),
    'department' => new Choice('Which team should handle this?', [
        'billing' => 'Payments, invoicing, refunds',
        'technical' => 'Bugs, outages, integrations',
        'sales' => 'Pricing, plans, upgrades',
    ]),
    'frustration' => new Score('How frustrated is the customer?', [
        'Calm, stating facts', 'Frustrated but civil', 'Very angry',
    ]),
])->classify();

$response['is_urgent']->isTrue();
$response['department']->choice;         // 'technical'
$response['department']->probabilities;  // every option, scored
$response['frustration']->score;         // 0.0 to 1.0

对于更加简单的分类，Str 类新增的 decide 宏用于询问一个只能回答“是”或“否”的问题，并返回布尔值。通过 threshold 参数，可以控制分类结果应达到的置信度：

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

Str::decide($message, 'Is this spam?', criteria: ['true' => 'Unsolicited bulk mail.'], threshold: 0.9);

目前，分类功能可在 TypeSafe 和 OpenRouter 上运行。随着其他提供商推出此类模型，Laravel AI SDK 将通过同一套 API 接入这些模型。

直接使用前端协议 ​

Laravel AI SDK 还进一步增强了对 Vercel Chat 和 AG-UI 协议标准的支持。它能够使用这些协议读取请求并以流式方式返回响应，便于结合主流前端库和工具，快速构建功能丰富的用户界面体验。

首先，将请求交给 Vercel::chat，再把结果直接传给智能体：

php
use Illuminate\Http\Request;
use Laravel\Ai\Vercel\Vercel;

Route::post('/chat', function (Request $request) {
    $chat = Vercel::chat($request);

    return (new SupportAgent)
        ->withMessages($chat->history())
        ->stream($chat)
        ->usingProtocol($chat->protocol());
});

这一个路由即可处理新消息、更新数据库中的对话历史记录，并检查用户提交的所有工具审批决定。

Laravel AI SDK 现在也支持 CopilotKit 等客户端采用的智能体用户交互（AG-UI）协议：

php
return (new SupportAgent)
    ->stream($request->string('prompt'))
    ->usingAgentUserInteractionProtocol();

需要在页面重新加载后重建聊天界面？将存储的消息转换回客户端所需的结构即可：

php
return ['messages' => Vercel::toUiMessages($conversation->messages)];

中间件现已支持自定义智能体循环 ​

此前，智能体中间件会针对每个提示词运行一次。现在，它会包裹每一个生成步骤。因此，智能体在回答前调用三次工具时，中间件也会运行三次。每个步骤都会以 PendingStep 对象的形式传入，可以检查该对象，也可以创建包含修改的副本。

这项改动使中间件能够更有效地控制成本和上下文，还可以在智能体处理提示词期间，自定义其消息、工具等内容。例如，某个成本高昂的工具一旦被智能体使用过，便可在后续步骤中将其移除：

php
use Closure;
use Laravel\Ai\PendingStep;

public function handle(PendingStep $step, Closure $next)
{
    if (! $step->isFirstStep()) {
        $step = $step->withoutTools('SearchDocumentation');
    }

    return $next($step);
}

甚至可以在处理同一个提示词的过程中替换整个模型、总结冗长的消息历史，或者直接返回缓存的答案，省去对提供商的调用。withModel、withInstructions、withMessages、withTools、onlyTools、withToolChoice、withMaxTokens 和 withProviderOptions 方法可以在执行过程中自定义提示词的各个部分。

可审批的工具调用 ​

有些工具只有获得明确的人工批准才能运行。现在，可以在工具上实现 Approvable 契约，并使用 InteractsWithApprovals trait。当智能体遇到 Approvable 工具时，它会先暂停并等待审批，审批通过后才调用该工具：

php
use Laravel\Ai\Concerns\InteractsWithApprovals;
use Laravel\Ai\Contracts\Approvable;
use Laravel\Ai\Contracts\Tool;

class DeleteFile implements Approvable, Tool
{
    use InteractsWithApprovals;

    // ...
}

响应会说明正在等待审批的内容，其中包括模型选择的参数：

php
$response = (new FileAssistant)
    ->forUser($user)
    ->prompt('Delete the old invoice.');

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

恢复执行时，可继续对话，并为每个待审批调用给出处理决定：批准调用、拒绝调用并向模型说明理由，或在工具运行前修改参数：

php
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('The invoice must be retained.'),
    ]));

审批功能适用于 prompt、stream、queue 和 broadcast 方法。

对话现可存储每一个步骤 ​

开发团队意识到，Laravel AI SDK 发布 v1.0 后，conversations 表将成为最难修改的部分，因此在发布前对其最终结构进行了更周全的考量。

过去，一个轮次会将工具调用和工具结果分别存储为两个扁平列表，并将重放状态存储在 meta 列中。这种方式会丢失特定工具调用所属的往返轮次，因此在为提供商重建历史记录时只能进行推测，部分提供商还会拒绝所得结果。它还会让从未运行的调用与正在等待审批的调用看起来完全相同。

现在，消息记录包含一个 steps JSON 列，每次往返对应一个条目，每项结果都与产生该结果的调用一同存储：

json
[
  {"content": "Read a", "tool_calls": [{"id": "toolu_1", "name": "read_file", "result": "..."}]},
  {"content": "now deleting b", "tool_calls": [{"id": "toolu_2", "name": "delete_file"}]}
]

对话仍以每个轮次一行的方式存储，因此分页以及 toolCalls 和 toolResults 访问器仍会像以前一样工作。

直接查询 tool_calls 或 tool_results 的原始 SQL 都需要改为使用 steps 列。此外，升级指南还包含一项数据回填迁移，必须在部署 v1.0 前运行一次。

按需加载工具以减少请求开销 ​

拥有 30 个工具的智能体会在每个请求中描述全部 30 个工具，这既会消耗 token，也会随着列表变长而降低模型选择的准确性。现在，可以将不常使用的工具封装进 ToolSearch，提供商只会在提示词需要这些工具时加载它们：

php
use Laravel\Ai\Providers\Tools\ToolSearch;

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

被封装的工具无需作出任何改动；工具加载后，智能体会像调用其他工具一样调用它们。OpenAI 和 Anthropic 支持工具搜索。

让智能体运行代码 ​

新增的提供商工具 CodeExecution 会在提供商自有的沙箱中运行代码，让负责数据分析或计算的智能体获得更准确的结果：

php
use Laravel\Ai\Providers\Tools\CodeExecution;

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

Anthropic、OpenAI、Azure、Gemini 和 xAI 支持代码执行。

跨提供商统一用量报告 ​

现在，所有提供商的用量报告都采用一致格式。promptTokens 和 completionTokens 属性已分别更名为 inputTokens 和 outputTokens，并包含提供商报告的全部计数：

php
$response->usage->inputTokens;   // includes cached and cache-written tokens
$response->usage->outputTokens;  // includes reasoning tokens
$response->usage->uncachedInputTokens();
$response->usage->totalTokens();

缓存 token、写入缓存的 token 和推理 token 现在都是这些总数的子集。

升级到 v1.0 ​

Laravel AI SDK v1.0 确实包含破坏性变更，主要涉及对话存储、智能体中间件、token 用量和流式协议。

Laravel AI SDK 升级指南针对每一项破坏性变更提供了变更前后的代码和受影响的可能性，用户只需处理与自身项目相关的内容。

使用 AI 升级 ​

建议让 AI 助手完成大部分升级工作。Laravel Boost 是 Laravel 官方的模型上下文协议（MCP）服务器，并随附适用于 AI SDK 的引导式升级提示词。

首先，将 Boost 作为应用程序的开发依赖安装，然后安装其 MCP 服务器和指南：

bash
composer require laravel/boost --dev

php artisan boost:install

安装完成后，在 Claude Code、Cursor、OpenCode、Gemini 或 VS Code 中运行 /upgrade-ai-sdk-v1 斜杠命令，开始升级。Boost 会自动引导 AI 助手逐项完成升级指南中的变更。

开始构建 ​

Laravel AI SDK 为应用程序中的 AI 功能提供了一个简洁、可测试的统一接入层。v1.0 使这一接入层具备了投入生产环境的条件。

请阅读完整文档，查看智能体、工具、流式传输、对话等主题的指南。

CatchAdmin
后端开发工程师，前端入门选手，略知相关服务器知识，偏爱❤️ Laravel & Vue
CatchAdmin 是一个功能强大、易于扩展的现代化 PHP 后台管理系统。它采用前后端分离架构：后端基于强大的 PHP 框架 Laravel，纯粹提供 API 接口；前端则拥抱现代技术栈，使用 Vue 3 和 Element Plus 构建用户界面。 通过精心的模块化设计，CatchAdmin 极大地降低了后台管理系统中各个模块的耦合度，为开发者提供了灵活、高效的二次开发体验。无论您是需要快速搭建一个 PHP 后台系统，还是寻找一个坚实的 PHP 后台框架 作为项目起点，CatchAdmin 是一个理想的选择
本作品采用《CC 协议》，转载必须注明作者和本文链接