用 useChat 将 Laravel AI SDK 智能体流式输出到 Vue 聊天界面
Gentil Maliyamungu B. · 2026-11-15
用 Laravel AI SDK 构建带查单工具的客服智能体,并用 @ai-sdk/vue 的 useChat 把它的回复流式输出到 Vue 3 聊天界面。
一个要等完整答案出来才显示任何内容的聊天,用起来像坏了一样。用户盯着加载动画五到十秒,然后一整墙文字突然出现。流式输出能解决这个问题:回复会逐词出现;如果模型调用了工具,你也可以把这一步显示出来。
Laravel AI SDK(laravel/ai)已经会做流式输出。文档里有一个 Vercel::chat() 辅助方法,使用的协议和 Vercel AI SDK 的 useChat 相同。网上大多数例子用的是 React 版 useChat、Livewire,或手写的 EventSource 客户端。本教程会把 Vue 版本从头到尾做完:
- 一个回答小商店客户问题的 Laravel 智能体,
- 一个智能体会调用的、在数据库里查找订单的工具,
- 一个 Vue 3 组件,负责流式输出回复,并在工具调用发生时把它显示出来。
下面全部内容是在 laravel/ai 1.4.0、Laravel 13.42 和 PHP 8.4 上编写并运行的,同时使用 ai 7.0.173、@ai-sdk/vue 4.0.173 和 Vue 3.5。这些库的 JavaScript 部分变化很快,如果和本文不完全一致,请先核对已安装的版本。
我们要做的是什么
演示是一个虚构商店的客服聊天。预先写入三笔订单:1001(已发货)、1002(延误)和 1003(已退款)。当用户问 “Where is order 1001?” 时,智能体调用 LookupOrder 工具,读取结果,再流式输出一段简短答复。
一共有三部分:
SupportAgent,一个带有指令和一个工具的 PHP 类。
POST /chat,一条把 useChat 请求转换成智能体调用并流式返回响应的路由。
SupportChat.vue,一个用 useChat 发送消息并渲染流式分段的组件。
本文不涵盖:需要人工批准的工具(见下一篇文章)、把对话存进数据库,以及 RAG。
安装 Laravel AI SDK
从全新的 Laravel 应用开始,并按照文档的安装部分操作:
composer require laravel/ai
php artisan vendor:publish --provider="Laravel\Ai\AiServiceProvider"
php artisan migrate
发布步骤会创建 config/ai.php,以及 SDK 会话表的迁移。本文不会用到这些表,但现在就跑迁移,以后不会突然踩坑。
在 .env 里加上提供方密钥,例如 OPENAI_API_KEY=... 或 OPENROUTER_API_KEY=...。默认提供方在 config/ai.php 中设置。
在没有 API 密钥的情况下运行
写这篇文章时,我希望演示能在完全没有密钥的机器上运行,于是把默认提供方改成可配置的,并指向一个会讲 OpenAI Chat Completions 格式的小型脚本服务器(在仓库里是 mock-llm/server.mjs)。SDK 的 openai-compatible 驱动需要一个 url,文本生成还需要一个默认模型:
// config/ai.php
'default' => env('AI_DEFAULT_PROVIDER', 'openai'),
'providers' => [
// ...
'openai-compatible' => [
'driver' => 'openai-compatible',
'url' => env('OPENAI_COMPATIBLE_URL'),
'key' => env('OPENAI_COMPATIBLE_API_KEY'),
'models' => [
'text' => [
'default' => env('OPENAI_COMPATIBLE_MODEL'),
],
],
],
],
AI_DEFAULT_PROVIDER=openai-compatible
OPENAI_COMPATIBLE_URL=http://127.0.0.1:4010/v1
OPENAI_COMPATIBLE_MODEL=mock-model
这个模拟器不是模型。它只遵循几条写死的规则(如果消息里包含四位数,就调用 LookupOrder)。它的唯一作用,是让 HTTP、流式输出和界面代码能被真正跑起来测试。当你需要真实答案时,再换成真正的提供方。
数据
订单表故意做得很小:
Schema::create('orders', function (Blueprint $table) {
$table->id();
$table->string('number')->unique();
$table->string('customer_name');
$table->string('status'); // shipped, delayed, delivered, refunded
$table->date('eta')->nullable();
$table->unsignedInteger('total_cents');
$table->timestamp('refunded_at')->nullable();
$table->timestamps();
});
OrderSeeder 会创建这三笔订单。Order 模型把 eta 转成日期。到这里还没有 AI SDK 的内容。
创建智能体
php artisan make:agent SupportAgent
生成的类实现了 Agent、Conversational 和 HasTools,并带有一个空的 messages() 方法。我们打算用 withMessages() 从浏览器传入聊天历史,而 SDK 不允许两者并用:调用 withMessages() 作用在 Conversational 智能体上会抛出 LogicException(“Ad-hoc message history may not be combined with a conversational agent.”)。所以要去掉 Conversational 和 messages() 方法:
<?php
namespace App\Ai\Agents;
use App\Ai\Tools\LookupOrder;
use Laravel\Ai\Attributes\MaxSteps;
use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Contracts\HasTools;
use Laravel\Ai\Promptable;
use Stringable;
#[MaxSteps(5)]
class SupportAgent implements Agent, HasTools
{
use Promptable;
public function instructions(): Stringable|string
{
return <<<'TEXT'
You are the support assistant for a small online shop.
Use the LookupOrder tool whenever the customer mentions an order number.
Never guess an order status or delivery date: if the tool finds nothing, say so.
Keep answers short and friendly.
TEXT;
}
public function tools(): iterable
{
return [
new LookupOrder,
];
}
}
#[MaxSteps(5)] 限制一轮里最多能和模型往返多少次。一次工具调用至少要两步(调用,然后回答),所以设成五步既留有余地,又不会让困惑的模型永远循环。
创建工具
php artisan make:tool LookupOrder
一个工具有三个方法:模型会读的描述、参数的 JSON schema,以及 handle():
<?php
namespace App\Ai\Tools;
use App\Models\Order;
use Illuminate\Contracts\JsonSchema\JsonSchema;
use Laravel\Ai\Contracts\Tool;
use Laravel\Ai\Tools\Request;
use Stringable;
class LookupOrder implements Tool
{
public function description(): Stringable|string
{
return 'Look up a customer order by its order number and return its status and estimated delivery date.';
}
public function handle(Request $request): Stringable|string
{
$validated = $request->validate([
'order_number' => 'required|string|digits:4',
]);
$order = Order::firstWhere('number', $validated['order_number']);
if (! $order) {
return "No order found with number {$validated['order_number']}.";
}
return json_encode([
'number' => $order->number,
'status' => $order->status,
'eta' => $order->eta?->toDateString(),
]);
}
public function schema(JsonSchema $schema): array
{
return [
'order_number' => $schema->string()
->description('The four-digit order number, without the # sign.')
->required(),
];
}
}
这里有两个细节很重要。
第一,schema 会约束模型发送的内容,但这不是校验。校验是 $request->validate()。校验失败时,SDK 会把校验信息作为工具结果发回给模型,让它可以自行纠正(Validating Tool Arguments)。
第二,工具的名称。除非你定义 name() 方法,否则 SDK 会使用类的短名,于是模型看到的函数名是 LookupOrder。这个名字也会出现在浏览器里,成为分段类型 tool-LookupOrder,我们会在 Vue 模板里用到它。
聊天路由
文档在 Frontend Integration 里讲的就是这一部分:
<?php
namespace App\Http\Controllers;
use App\Ai\Agents\SupportAgent;
use Illuminate\Http\Request;
use Laravel\Ai\Vercel\Vercel;
class ChatController extends Controller
{
public function store(Request $request)
{
$request->validate([
'messages' => ['required', 'array', 'max:50'],
]);
$chat = Vercel::chat($request);
return (new SupportAgent)
->withMessages($chat->history())
->stream($chat)
->usingProtocol($chat->protocol());
}
}
// routes/web.php
Route::post('/chat', [ChatController::class, 'store'])
->middleware('throttle:ai');
// app/Providers/AppServiceProvider.php, in boot()
RateLimiter::for('ai', function (Request $request) {
return Limit::perMinute(30)->by($request->user()?->id ?: $request->ip());
});
下面是每一行在做什么,依据是我阅读包里的 Laravel\Ai\Vercel\Chat:
Vercel::chat($request) 读取 messages 数组,也就是 useChat 提交的内容。
$chat->history() 把最新用户消息 之前 的每一条消息转成 SDK 的 Message 对象,包括更早的工具调用和结果。
- 把
$chat 本身传给 stream(),智能体就会把最新的用户消息当作提示。 (之后当工具需要批准时,同一个对象还会携带用户的决定。)
$chat->protocol() 返回 Vercel 数据协议,这样响应就是 useChat 能解析的流。
throttle:ai 是我在 AppServiceProvider 里定义的命名限流器,让所有调用模型的路由按用户或 IP 共享同一份配额。如果在多条路由上只用普通的 throttle:20,1,Laravel 会按已登录用户或 IP 而不是按路由来做键,于是这些路由最终还是共用一个计数器。测试时这点让我吃了一惊。
如果你对这条路由执行 curl,就能看到浏览器收到的内容。下面是精简后的样子:
data: {"type":"start","messageId":"01a1deba-..."}
data: {"type":"start-step"}
data: {"type":"tool-input-available","toolCallId":"call_1","toolName":"LookupOrder","input":{"order_number":"1001"}}
data: {"type":"tool-output-available","toolCallId":"call_1","output":"{\"number\":\"1001\",\"status\":\"shipped\",\"eta\":\"2026-11-17\"}"}
data: {"type":"finish-step"}
data: {"type":"start-step"}
data: {"type":"text-delta","id":"01a1deba-...","delta":"Order "}
data: {"type":"text-delta","id":"01a1deba-...","delta":"#1001 "}
...
data: {"type":"finish","finishReason":"stop","messageMetadata":{"usage":{...}}}
data: [DONE]
响应还会带上 x-vercel-ai-ui-message-stream: v1 和 X-Accel-Buffering: no 这两个头。第二个是告诉 Nginx 不要缓冲这条流。
Vue 组件
安装客户端包:
npm install vue ai @ai-sdk/vue
npm install -D @vitejs/plugin-vue
在 @ai-sdk/vue 的第 4 版里,useChat 是一个组合式函数,返回 refs(messages、status、error)以及 sendMessage、stop 等方法。旧的 Chat 类仍然会导出,但已被标记为弃用。端点通过 transport 来配置:
<script setup>
import { ref, computed } from 'vue';
import { useChat } from '@ai-sdk/vue';
import { DefaultChatTransport } from 'ai';
const csrfToken = document.querySelector('meta[name="csrf-token"]')?.content ?? '';
const { messages, status, error, sendMessage, stop } = useChat({
transport: new DefaultChatTransport({
api: '/chat',
headers: { 'X-CSRF-TOKEN': csrfToken },
}),
});
const input = ref('');
const busy = computed(() => status.value === 'submitted' || status.value === 'streaming');
function submit() {
const text = input.value.trim();
if (!text || busy.value) return;
sendMessage({ text });
input.value = '';
}
</script>
因为 /chat 是 web 路由,会走 Laravel 的 CSRF 中间件。Blade 布局会输出 <meta name="csrf-token" content="{{ csrf_token() }}">,transport 则在每次请求里把它作为 X-CSRF-TOKEN 发送。
status 会经过 submitted(请求已发出,尚未收到任何内容)、streaming,然后是 ready,或 error。这已经够用来显示 “Thinking…” 提示,并把 Send 按钮换成 Stop 按钮:
<template>
<main class="mx-auto max-w-xl p-6">
<ul class="space-y-3">
<li v-for="message in messages" :key="message.id"
:class="message.role === 'user' ? 'text-right' : 'text-left'">
<template v-for="(part, index) in message.parts" :key="index">
<p v-if="part.type === 'text'" class="inline-block whitespace-pre-wrap rounded-lg bg-white px-3 py-2 shadow-sm">
{{ part.text }}
</p>
<div v-else-if="part.type === 'tool-LookupOrder'" class="my-1 rounded border border-dashed px-3 py-2 text-sm text-gray-600">
<span v-if="part.state === 'output-available'">Checked order #{{ part.input.order_number }}</span>
<span v-else-if="part.state === 'output-error'">Lookup failed: {{ part.errorText }}</span>
<span v-else>Looking up order…</span>
</div>
</template>
</li>
</ul>
<p v-if="status === 'submitted'" class="mt-3 text-sm text-gray-500">Thinking…</p>
<p v-if="error" class="mt-3 text-sm text-red-600">Something went wrong. Please try again.</p>
<form class="mt-4 flex gap-2" @submit.prevent="submit">
<input v-model="input" class="flex-1 rounded border px-3 py-2" placeholder="Where is order 1001?" :disabled="busy" />
<button v-if="busy" type="button" class="rounded border px-3" @click="stop">Stop</button>
<button v-else type="submit" class="rounded bg-black px-3 text-white">Send</button>
</form>
</main>
</template>
每条消息都有一个 parts 数组,而不是单独的 content 字符串。带工具调用的一轮结束后是这样的(我从正在运行的应用里记下来的):step-start,tool-LookupOrder(状态为 output-available),再一个 step-start,然后是 text 分段。按分段而不是按压平后的字符串来渲染,才能在用户的问题和答案之间显示 “Checked order #1001”。
除非你想在步骤之间加视觉分隔,否则可以忽略 step-start 分段。
多轮对话
useChat 每次请求都会提交完整的对话记录。在第二个问题(“And order 9999?”)里,请求包含四条消息,Vercel::chat()->history() 会把前三条变成上下文,包括先前的工具调用及其结果。在我的这次运行中,第二个答案是 “No order found with number 9999.”,直接来自工具的未找到分支。
这种方式简单且无状态,对只读工具是合适的。但要记住,历史来自浏览器,用户可以改它。绝不要让这份历史来决定是否允许发生敏感操作。在下一篇文章里,RefundOrder 工具需要人工批准,我会说明为什么那必须把对话存在服务器上。
我是如何确认它能工作的
我不想发布只读过、没跑过的代码,所以这个演示有三层检查:
- 一个 Pest 测试,伪造智能体并对流式响应体做断言。
SupportAgent::fake() 接受一组响应。在 1.4.0 的源码里,伪造网关还接受 Laravel\Ai\Responses\Data\ToolCall 对象,这样循环就会对测试数据库运行真正的 LookupOrder 工具。文档里没有写这一点,请把它当作实现细节:
SupportAgent::fake([
new ToolCall('call_1', 'LookupOrder', ['order_number' => '1001']),
'Order #1001 has shipped.',
])->preventStrayPrompts();
$body = $this->postJson('/chat', ['messages' => [
['id' => 'u1', 'role' => 'user', 'parts' => [['type' => 'text', 'text' => 'Where is order 1001?']]],
]])->assertOk()->streamedContent();
expect($body)
->toContain('"toolName":"LookupOrder"')
->toContain('\"status\":\"shipped\"')
->toContain('"type":"text-delta"');
- 一个 Node 脚本,在组件之外运行真正的
useChat 组合式函数,对接 php artisan serve 和模拟提供方。
- 一个 Vitest 测试,在 happy-dom 中挂载
SupportChat.vue,输入问题、提交表单,在文本流式输出时看到 Stop 按钮,然后检查最终答案和 “Checked order #1001” 这一行。
本系列第五篇文章 会更深入地介绍用 Pest 测试智能体。
生产环境注意事项
有几件事很容易漏掉:
- 缓冲。 SDK 会设置
X-Accel-Buffering: no,但 CDN 或负载均衡器仍可能把响应一直攒到结束。如果生产环境里 token 是一次性到达的,而本地却是流式的,先查这里。
- 错误会到达浏览器。 当提供方在流的中途返回错误时,我看到的 Vercel 协议分段把提供方的消息放在
errorText 里。我的组件会显示一条通用提示,而不是把原文打印出来。
- 身份验证。 为了让教程尽量短,我的演示路由是公开的,只做了限流。真正的应用应把它放在
auth 后面(session 或 Sanctum)。
- 没有原始响应。 流式响应不会暴露提供方的原始 HTTP 响应,因此像速率限制计数这样的头在这条路径上不可用(Raw HTTP Responses)。
- 密钥留在服务器上。 浏览器始终只和你的 Laravel 路由通信。
小结
代码量很小:一个智能体类、一个工具、一个三行的控制器方法,再加上一个 Vue 组件。大部分工作是弄清线路上流动的是什么。Vercel::chat() 读取 useChat 发送的内容,usingProtocol() 写出它所期望的返回格式,你的模板则渲染 parts。
配套演示包含模拟提供方、Pest 测试和 Vitest 测试。下一篇:添加一个会暂停、直到有人点击 Approve 的 RefundOrder 工具,以及我在构建时差点犯下的安全错误。