用 Laravel AI SDK 智能体的结构化输出预填 Vue 表单
Gentil Maliyamungu B. · 2026-11-15
使用 Laravel AI SDK 的结构化输出 schema 起草表单字段,在服务器上校验它们,再合并进 Vue 表单,并且不覆盖用户已做的修改。
并非每一项 AI 功能都得是聊天窗口。很多时候,模型能做的最有用的事,是填好一份随后由人核对的表单:根据客户邮件生成支持工单,根据供应商描述生成商品信息,根据收据生成费用记录。
在本教程里,客服人员把客户消息粘贴进 Vue 表单,点击 Draft with AI,就会填好主题、类别、优先级、订单号、摘要和建议回复。人始终保有控制权:
- 模型的输出会在服务器上按与人工提交相同的规则校验,无效字段会被丢掉,而不是显示出来;
- 用户已经输入的字段永远不会被覆盖;
- 由 AI 填写的字段会被标记,直到有人编辑它们;
- 保存时会再跑一遍同样的校验,因此伪造的请求无法跳过它。
测试环境为 laravel/ai 1.4.0、Laravel 13.42、PHP 8.4 和 Vue 3.5。
智能体及其 schema
Laravel AI SDK 允许智能体返回结构化输出:实现 HasStructuredOutput,并用 Laravel 的 JSON schema 构建器描述形状:
php artisan make:agent TicketDraftAgent --structured
<?php
namespace App\Ai\Agents;
use Illuminate\Contracts\JsonSchema\JsonSchema;
use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Contracts\HasStructuredOutput;
use Laravel\Ai\Promptable;
use Stringable;
class TicketDraftAgent implements Agent, HasStructuredOutput
{
use Promptable;
public const CATEGORIES = ['shipping', 'damaged_item', 'refund', 'other'];
public const PRIORITIES = ['low', 'normal', 'high'];
public function instructions(): Stringable|string
{
return <<<'TEXT'
You turn a customer's message into a draft support ticket for a small online shop.
Write the subject and summary in plain English, without inventing facts.
Only fill order_number if the customer wrote one; otherwise use null.
The suggested reply is a first draft for a human agent, not a promise.
TEXT;
}
public function schema(JsonSchema $schema): array
{
return [
'subject' => $schema->string()->max(80)->required(),
'category' => $schema->string()->enum(self::CATEGORIES)->required(),
'priority' => $schema->string()->enum(self::PRIORITIES)->required(),
'order_number' => $schema->string()->nullable()->required(),
'summary' => $schema->string()->required(),
'suggested_reply' => $schema->string()->required(),
];
}
}
类别和优先级是类常量,这样 schema 和校验规则共用一份列表。
order_number 同时是 nullable() 和 required()。意思是“始终包含这个键,没有值时使用 null”,这比省略该键对模型更清楚。这也符合 OpenAI 等提供方的严格结构化输出模式所期望的:每个属性都列为必填,可选值则表示为可空。
提供方实际收到什么
我把它对着一个 OpenAI 兼容端点跑过,并记录了请求。SDK 把 schema 转成了这样的 response_format(已精简):
{
"type": "json_schema",
"json_schema": {
"name": "schema_definition",
"schema": {
"type": "object",
"additionalProperties": false,
"properties": {
"subject": { "type": "string", "maxLength": 80 },
"category": { "type": "string", "enum": ["shipping", "damaged_item", "refund", "other"] },
"priority": { "type": "string", "enum": ["low", "normal", "high"] },
"order_number": { "type": ["string", "null"] },
"summary": { "type": "string" },
"suggested_reply": { "type": "string" }
},
"required": ["subject", "category", "priority", "order_number", "summary", "suggested_reply"]
},
"strict": false
}
}
注意 "strict": false。在该驱动和默认设置下,会向提供方请求这个形状,但并不强制。即便开了严格模式,maxLength 和业务规则(“this order exists”)仍应自己检查。所以服务器把模型的答案当作用户输入来对待。
端点:先 prompt,再校验
起初我打算对流式输出结构化结果,让字段在生成过程中逐渐填上。在 1.4.0 里这还做不到。对带结构化输出的智能体调用 stream() 会抛出:
InvalidArgumentException: Streaming structured output is not currently supported.
因此端点使用 prompt() 并返回 JSON。对于短表单,等待通常只有几秒,一个 “Drafting…” 状态就够了。
<?php
namespace App\Http\Controllers;
use App\Ai\Agents\TicketDraftAgent;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Validator;
use Illuminate\Validation\Rule;
class TicketController extends Controller
{
/**
* The rules a ticket must pass, whether a human or the model filled it in.
*/
protected function rules(): array
{
return [
'subject' => ['required', 'string', 'max:80'],
'category' => ['required', Rule::in(TicketDraftAgent::CATEGORIES)],
'priority' => ['required', Rule::in(TicketDraftAgent::PRIORITIES)],
'order_number' => ['nullable', 'digits:4', 'exists:orders,number'],
'summary' => ['required', 'string', 'max:2000'],
'suggested_reply' => ['nullable', 'string', 'max:2000'],
];
}
public function draft(Request $request)
{
$validated = $request->validate([
'message' => ['required', 'string', 'max:5000'],
]);
$draft = (new TicketDraftAgent)->prompt($validated['message'])->toArray();
$errors = Validator::make($draft, $this->rules())->errors()->toArray();
return response()->json([
// Cast so an empty draft is still a JSON object, not [].
'draft' => (object) array_diff_key($draft, $errors),
'rejected' => array_keys($errors),
]);
}
public function store(Request $request)
{
$ticket = $request->validate($this->rules());
// A real app would create a Ticket model here.
return response()->json(['ticket' => $ticket], 201);
}
}
Route::view('/tickets/new', 'tickets');
Route::post('/tickets/draft', [TicketController::class, 'draft'])->middleware('throttle:ai');
Route::post('/tickets', [TicketController::class, 'store']);
几点说明:
- 对结构化响应调用
->toArray() 会得到解码后的字段。该响应也支持数组访问($response['subject'])。
- 无效字段会被丢掉,而不是被“修正”。 如果模型编造了一个不存在的类别或订单号,客户端永远看不到那个值,只会在
rejected 里看到它的名字。由人来填写。
exists:orders,number 这条规则最重要。 schema 可以保证 order_number 是字符串。只有你的数据库能告诉你这笔订单是否存在。
throttle:ai 是给会花钱的端点用的命名限流器(按用户或 IP 使用 Limit::perMinute(30),写在 AppServiceProvider 里)。
当模型无视 schema 时
我想知道模型如果不用 JSON、而是用散文作答会怎样,于是让测试服务器回复 “Sure! Here is a ticket for you.” 在 1.4.0 里,网关会宽松地解码结构化输出:先尝试普通 JSON,再尝试带围栏的代码块,如果都不行就返回一个空数组,而不会抛错。于是我的端点返回了:
{"draft":{},"rejected":["subject","category","priority","summary"]}
什么也没坏。表单会让人看出这份草稿被忽略了。也正因为这个空数组,我才把 draft 转成对象:若不转换,PHP 的空数组在 JSON 里会变成 []。
Vue 一侧:只让最新一次草稿请求生效
// resources/js/composables/useTicketDraft.js
import { ref } from 'vue';
const csrf = () => document.querySelector('meta[name="csrf-token"]')?.content ?? '';
export function useTicketDraft() {
const loading = ref(false);
const error = ref(null);
let controller = null;
async function requestDraft(message) {
controller?.abort(); // a new request replaces an old one
controller = new AbortController();
loading.value = true;
error.value = null;
try {
const response = await fetch('/tickets/draft', {
method: 'POST',
headers: { 'Content-Type': 'application/json', Accept: 'application/json', 'X-CSRF-TOKEN': csrf() },
body: JSON.stringify({ message }),
signal: controller.signal,
});
if (!response.ok) throw new Error(`Draft failed with ${response.status}`);
return await response.json(); // { draft, rejected }
} catch (e) {
if (e.name !== 'AbortError') error.value = e;
return null;
} finally {
loading.value = false;
}
}
return { loading, error, requestDraft, cancel: () => controller?.abort() };
}
合并草稿且不覆盖人工输入
表单保留两个集合:touched 是用户输入过的字段,aiFilled 是模型填过、且还没人编辑的字段。
<script setup>
import { reactive, ref } from 'vue';
import { useTicketDraft } from '../composables/useTicketDraft';
const fields = ['subject', 'category', 'priority', 'order_number', 'summary', 'suggested_reply'];
const customerMessage = ref('');
const form = reactive({ subject: '', category: '', priority: 'normal', order_number: '', summary: '', suggested_reply: '' });
const touched = reactive(new Set());
const aiFilled = reactive(new Set());
const rejected = ref([]);
const errors = ref({});
const saved = ref(false);
const { loading, error, requestDraft } = useTicketDraft();
function edit(field) {
touched.add(field);
aiFilled.delete(field);
}
async function draft() {
const result = await requestDraft(customerMessage.value);
if (!result) return;
for (const field of fields) {
// Never overwrite what the human already typed.
if (touched.has(field) || !(field in result.draft)) continue;
form[field] = result.draft[field] ?? '';
aiFilled.add(field);
}
rejected.value = result.rejected;
}
async function save() {
errors.value = {};
const response = await fetch('/tickets', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
Accept: 'application/json',
'X-CSRF-TOKEN': document.querySelector('meta[name="csrf-token"]')?.content ?? '',
},
body: JSON.stringify({ ...form, order_number: form.order_number || null }),
});
if (response.status === 422) {
errors.value = (await response.json()).errors;
return;
}
saved.value = response.ok;
}
</script>
Vue 3 会让响应式 Set 按你期望的方式工作:模板里的 aiFilled.has('subject') 会在集合变化时更新。
edit() 处理函数在 @input 和 @change 上运行。这些事件只在有人与字段交互时触发。当代码根据草稿设置 form.subject 时,不会触发 input 事件,因此 AI 填写的值不会被算作编辑。
模板(精简到两个字段):
<template>
<form class="space-y-3" @submit.prevent="save">
<label>
Customer message
<textarea v-model="customerMessage" name="message" rows="3" />
</label>
<button type="button" name="draft" :disabled="loading || !customerMessage.trim()" @click="draft">
{{ loading ? 'Drafting…' : 'Draft with AI' }}
</button>
<p v-if="error">Could not draft this ticket. Fill it in by hand.</p>
<p v-if="rejected.length">Ignored suggestions for: {{ rejected.join(', ') }}</p>
<fieldset :disabled="loading">
<label>
Subject <span v-if="aiFilled.has('subject')">AI draft</span>
<input v-model="form.subject" name="subject" @input="edit('subject')" />
</label>
<label>
Category <span v-if="aiFilled.has('category')">AI draft</span>
<select v-model="form.category" name="category" @change="edit('category')">
<option value="" disabled>Choose…</option>
<option value="shipping">Shipping</option>
<option value="damaged_item">Damaged item</option>
<option value="refund">Refund</option>
<option value="other">Other</option>
</select>
</label>
<!-- priority, order_number, summary, suggested_reply follow the same pattern -->
</fieldset>
<ul v-if="Object.keys(errors).length">
<li v-for="(messages, field) in errors" :key="field">{{ field }}: {{ messages[0] }}</li>
</ul>
<button type="submit" :disabled="loading">Create ticket</button>
<p v-if="saved">Ticket created.</p>
</form>
</template>
在草稿请求进行时禁用 fieldset,可以避免一种令人困惑的情况:用户正在某个字段里打字,随后草稿到达并填上周围的字段。如果希望草稿运行时人们仍能继续输入,就去掉 disabled。touched 检查仍然会保护他们的修改。
值得照做的设计选择
在有人改动之前,给 AI 内容打上标签。 当用户编辑该字段时,“AI draft” 徽章会消失。它告诉审查的人,哪些值还没有人核对过。
把建议回复保持为草稿。 schema 把它称为建议,指令里写的是 “not a promise”。这个流程里没有任何一步会把它发给客户。在真正的工单系统里,仍需有人复制它或点击 Send。
校验两次。 draft() 会过滤模型输出,避免表单显示无效值。store() 会再次校验全部内容,因为浏览器可以发送任何东西。两者使用同一个 rules() 方法。
不要编造缺失的数据。 指令告诉模型在没有订单号时使用 null,而 exists 规则会抓住它仍然编造出来的那些情况。
如何测试
SDK 可以伪造结构化智能体:按每次预期的提示传入一组字段值。下面这些 Pest 测试覆盖该端点:
use App\Ai\Agents\TicketDraftAgent;
it('returns the structured draft from the agent', function () {
TicketDraftAgent::fake([[
'subject' => 'Cracked screen',
'category' => 'damaged_item',
'priority' => 'high',
'order_number' => '1002',
'summary' => 'Phone arrived cracked.',
'suggested_reply' => 'Sorry! Can you send a photo?',
]])->preventStrayPrompts();
$this->postJson('/tickets/draft', ['message' => 'My phone from order 1002 is cracked'])
->assertOk()
->assertJsonPath('draft.category', 'damaged_item')
->assertJsonPath('draft.order_number', '1002')
->assertJsonPath('rejected', []);
TicketDraftAgent::assertPrompted(fn ($prompt) => $prompt->contains('cracked'));
});
it('drops fields that fail validation', function () {
TicketDraftAgent::fake([[
'subject' => 'Broken item',
'category' => 'complaint', // not an allowed category
'priority' => 'high',
'order_number' => '7777', // no such order
'summary' => 'Arrived broken.',
'suggested_reply' => 'Sorry!',
]])->preventStrayPrompts();
$this->postJson('/tickets/draft', ['message' => 'Order 7777 arrived broken'])
->assertOk()
->assertJsonMissingPath('draft.category')
->assertJsonMissingPath('draft.order_number')
->assertJsonPath('rejected', ['category', 'order_number']);
});
如果代码向智能体发起的提示次数多于你伪造的次数,preventStrayPrompts() 会让测试失败。再配合 Http::preventStrayRequests()(位于 tests/Pest.php),就不会有测试意外打到真正的提供方。
四个端点测试(包括空草稿的情况)都通过了。我还用 Vitest 和 happy-dom,对着正在运行的 Laravel 应用和一个脚本化的 OpenAI 兼容测试服务器跑了 Vue 组件。测试会输入一个主题、请求一份草稿,并检查主题保持原样、其他字段被填上,以及保存时显示 “Ticket created.” 第二个测试检查订单 7777 被列为忽略,且该字段保持为空。
接下来可以做什么
- 如果你的表单很长,希望字段逐步出现,请关注 SDK 的 changelog 是否支持流式结构化输出。在此之前,
prompt() 加上加载状态是可靠的做法。
- 对于耗时更长的草稿,使用 SDK 的
queue() 方法,再通过广播把结果推到浏览器。
- 记录
rejected 列表。如果某个字段经常被拒绝,就改进该字段的指令或 schema 描述。
模型起草,由人来决定。让这种分工成立的,正是那些校验规则。