你可能只用 Zod 校验 LLM 输出。但在一个完整的 Agent 系统里,Zod 至少出现在 6 个环节——从 API 入参到环境变量,从 Tool 参数到 Handoff 状态传递。漏掉任何一个,就是一道敞开的门。

为什么 Zod 不只是”LLM 输出质检员”

大多数人认识 Zod,是通过 Vercel AI SDK 的 generateObject({ schema }) 或 OpenAI SDK 的 zodResponseFormat。但这只是 Zod 6 个角色中的 1 个。

Zod 的本质是运行时数据校验库——它不关心数据从哪来,只关心数据符不符合你定义的结构。在 Agent 全链路中,动态数据来自四面八方:用户输入、LLM 输出、Tool 参数、环境变量、Agent 间传递的上下文。每一处都需要校验。

6 个角色逐个拆解

角色 1:API 入参校验(后端防伪门卫)

import { z } from 'zod';
 
// Next.js Route Handler 的第一道防线
const CreateNoteSchema = z.object({
  title: z.string().min(1).max(200),
  content: z.string().min(1),
  category: z.enum(['study', 'work', 'personal']).default('study'),
});
 
export async function POST(req: Request) {
  const body = await req.json();
  const parsed = CreateNoteSchema.safeParse(body);
  if (!parsed.success) {
    return Response.json({ error: parsed.error.issues }, { status: 400 });
  }
  // parsed.data 已是类型安全的数据
}

职责:拦截客户端传来的非法 Payload——空标题、超长内容、非法枚举值。确保进入业务逻辑和写库的数据 100% 安全。

角色 2:LLM 输出约束(定义预期返回结构)

import { generateObject } from 'ai';
import { openai } from '@ai-sdk/openai';
 
const { object } = await generateObject({
  model: openai('gpt-4o'),
  schema: StudyDiagnosisSchema,  // Zod Schema 被 SDK 转为 JSON Schema 传给 LLM
  system: '你是一位学习导师...',
  prompt: `笔记内容:${notes}`,
});

职责:提供 TypeScript 强类型的字段定义,被 AI SDK 转换为 JSON Schema 注入给 LLM。底层触发 Grammar-Guided Sampling,物理层保证输出合规。详见 Structured Output。

角色 3:LLM 输出二次校验(运行期兜底)

大模型返回 JSON 文本后,Zod 在运行期执行 schema.parse(llmOutput)。即使大模型偶发性地漏写字段,Zod 能第一时间抛出明确错误,防止脏数据进入系统后台。

// generateObject 内部已自动执行 parse,但如果手动调用 LLM API:
const raw = await openai.chat.completions.create({...});
const result = StudyDiagnosisSchema.parse(JSON.parse(raw.choices[0].message.content));
// 不合规直接抛 ZodError,不会静默放行

职责:二次防线。Grammar-Guided Sampling 已经物理层保证合规,Zod parse 是”信任但验证”的兜底机制。

角色 4:Tool / Function Calling 参数

import { tool } from 'ai';
import { z } from 'zod';
 
const createStudyPlanTool = tool({
  description: '为用户创建学习计划',
  parameters: z.object({
    days: z.number().min(1).max(365).describe('学习天数'),
    topic: z.string().describe('学习主题'),
  }),
  execute: async ({ days, topic }) => {
    // days 一定是 1-365 的数字,LLM 传 "五天" 会被拦截
    return generatePlan(topic, days);
  },
});

职责:定义 Agent 可调用工具的参数格式。LLM 决定调用 Tool 时,参数必须先过 Zod 校验,脏参数直接拒绝。

角色 5:环境变量校验

import { z } from 'zod';
 
const envSchema = z.object({
  OPENAI_API_KEY: z.string().startsWith('sk-'),
  DATABASE_URL: z.string().url(),
  NODE_ENV: z.enum(['development', 'production', 'test']),
});
 
const env = envSchema.parse(process.env);
// 应用启动时立即校验,避免线上运行到一半才发现配置缺失

职责:应用启动时校验 process.env 是否存在且格式正确。如果 OPENAI_API_KEY 缺失或格式不对,应用直接拒绝启动,而不是运行到第一次调用 LLM 时才崩溃。

角色 6:Handoff 状态传递

import { z } from 'zod';
 
// 多 Agent 架构中,主 Agent 向子 Agent 传递上下文
const HandoffContextSchema = z.object({
  userId: z.string(),
  conversationSummary: z.string(),
  currentTopic: z.string(),
  pendingTasks: z.array(z.string()),
  metadata: z.record(z.unknown()).optional(),
});
 
function handoffToSpecialist(context: unknown) {
  const ctx = HandoffContextSchema.parse(context);
  // 上下文数据包完整,可以安全传递给专家 Agent
}

职责:多 Agent 架构中,主 Agent 向子 Agent 传递 Context 时校验数据包是否完整。Handoff 是状态所有权的交接,上下文残缺会导致子 Agent 无法正常工作。

6 个角色全览

flowchart TD
    User["用户输入"] --> R1["① API 入参校验"]
    R1 --> R2["② LLM 输出约束"]
    R2 --> R3["③ LLM 输出二次校验"]
    R3 --> R4["④ Tool 参数校验"]
    R4 --> DB["数据库落库"]
    Env["环境变量"] --> R5["⑤ 启动时校验"]
    Router["路由 Agent"] -->|"上下文传递"| R6["⑥ Handoff 状态校验"]
    R6 --> Specialist["专家 Agent"]

跨生态映射:每个语言生态都有自己的 Zod

Zod 是 TypeScript 生态的方案,但不是唯一的方案。每种语言生态都有自己的运行时数据校验库:

生态Schema 方案对应角色典型用法
TypeScript / Node.jsZod(同类:Valibot, TypeBox)运行时校验 + 类型推导z.object({...}).parse(data)
PythonPydantic数据模型 + 校验class Model(BaseModel): ...
JavaHibernate Validator / JSR-303注解式校验@NotNull @Size(min=1)

三者做的事情本质相同:在运行时拦截不符合 Schema 的数据。差异在于语言范式——Zod 是声明式 API,Pydantic 是类继承,Hibernate Validator 是注解装饰。

Zod vs Drizzle Schema:职责边界

这是最容易混淆的一组。两者都叫”Schema”,但管的东西完全不同:

ZodDrizzle Table Schema
约束对象动态数据(LLM 输出、用户输入、API 参数)数据库表结构(每条数据的字段类型)
角色比喻门卫 / 质检员建模师 / 施工图
生效时机运行时,每次数据通过都校验定义时,决定表结构
类型来源Zod 定义 → z.infer<typeof Schema> 推导Drizzle 定义 → TS 类型自动生成
关心什么数据”形状”对不对数据”怎么存”

两者的结合:LLM 生成 → Zod 校验通过 → Drizzle db.insert(...) 写入 PostgreSQL,实现端到端类型安全(End-to-End Type Safety)。

flowchart LR
    LLM["LLM 输出 JSON"] -->|"Zod parse"| Valid["类型安全数据"]
    Valid -->|"Drizzle insert"| DB["PostgreSQL 落库"]
    DB -->|"Drizzle select"| Query["查询结果"]
    Query -->|"前端渲染"| UI["React 组件"]

性能注意事项

Zod 的 parse() 是同步操作,对于大多数 Schema(几十个字段以内)性能开销可忽略。但在以下场景需要注意:

  • 超大 Schema(几百个字段嵌套):parse() 可能耗费数毫秒,在高 QPS 场景下需要评估
  • 流式输出:Vercel AI SDK 的 streamObject 在流式过程中增量校验,不会等全部生成完才 parse
  • safeParse vs parse:safeParse 不抛异常,返回 { success, data, error },适合需要自定义错误处理的场景

适用边界

场景用 Zod?原因
LLM 输出✅LLM 是概率性的,必须校验
用户 API 输入✅不可信数据源
Tool 参数✅LLM 决定调用参数,可能不合规
环境变量✅启动时一次性校验,成本极低
数据库查询结果❌Drizzle 已保证类型安全,不需要 Zod 再校验
内部函数间传参❌可信数据源,Zod 校验是多余的
Handoff 上下文✅Agent 间传递的上下文可能不完整

一句话带走

Zod 是动态数据的门卫——不管数据来自用户输入、LLM 输出、Tool 参数还是环境变量,只要是动态生成的,就需要 Zod 在边界做校验。

参考来源

相关