AI SDK Agents：让大模型应用像搭积木一样简单

想象你正在开发一个智能客服系统。用户随口问了一句："帮我算一下北京到上海的距离，再查查明天北京的天气。"传统开发模式下，你需要分别接入两个 API、写两套调用逻辑、处理两种响应格式——代码量翻倍，维护成本翻倍。而有了 AI SDK Agents，你只需要把"数学专家 Agent"和"天气查询 Agent"定义成两个工具，然后告诉主 Agent："你需要的时候调用这些工具就行"。剩下的推理和编排，交给框架处理。

这就是 AI SDK Agents 解决的核心问题：把 AI 应用开发从"写死了的调用逻辑"升级成"动态组合的工具集"。

项目背景：站在巨人肩膀上

AI SDK Agents 由独立开发者 Iaroslav Sobolev（sslava） 创建，是一个基于 Vercel AI SDK 的扩展库。Vercel AI SDK 本身已经是连接各大 LLM 提供商（OpenAI、Anthropic、Google 等）的事实标准，而 AI SDK Agents 则在此基础上加入了 Agent（智能体）编排能力——让多个 AI 模型之间可以互相调用、协同工作。

项目的灵感来源包括：

• OpenAI 的 Agent Framework（Python 版本）
• Anthropic 发布的《Building effective agents》工程实践指南
• Vercel 在 AI 应用基础设施上的深厚积累

目前项目在 GitHub 上拥有约 43 颗星、5 个 Fork，属于早期但活跃的个人开源项目。

核心能力：Agent 到底是什么？

在 AI SDK Agents 的世界观里，Agent（智能体） 是一个有明确角色的 AI 实例。你可以这样理解：

// 定义一个数学专家 Agent
const mathAgent = agent({
  model: openai('gpt-4o'),
  description: '数学专家',
  system: '你是一个数学专家',
  output: z.object({
    answer: z.string()
  }),
  // 把这个 Agent 暴露为工具，供其他 Agent 调用
  asTool: {
    input: z.object({ question: z.string() }),
    getPrompt: ({ question }) => ({ prompt: `Solve: ${question}` })
  }
});

// 定义一个主助手 Agent，内置数学工具
const assistantAgent = agent({
  model: openai('gpt-4o'),
  system: '你是一个有帮助的助手',
  tools: { math: mathAgent },  // 注入工具
  maxSteps: 5
});

这里的"工具"（tool）概念尤为关键。不仅可以是函数/API，还可以是另一个 Agent——这意味着你可以构建多层的 Agent 嵌套结构：主 Agent 调用专家 Agent，专家 Agent 再调用更细分的工具。这种设计让复杂任务的拆解变得极为自然。

关键特性一览

特性	说明
流式响应	支持实时流式输出，适合对话类应用
上下文管理	可在每次调用中注入自定义上下文（如当前时间、用户信息）
多步推理	maxSteps 控制 Agent 最大思考步数，避免无限循环
工具选择策略	支持 auto（自动选择）、required（必须使用）、none（不使用）三种工具调用策略
类型安全	全程 TypeScript + Zod Schema 校验，IDE 自动补全友好

快速上手：10 分钟跑通示例

环境要求

• Node.js ≥ 22.0.0
• 支持 npm / yarn / pnpm（推荐 pnpm）

安装

npm install ai-sdk-agents ai zod
# 或
pnpm add ai-sdk-agents ai zod

第一个示例：带工具调用的对话流

项目提供了开箱即用的 ChatFlow，可以快速构建流式对话 API。以下是一个完整的 Express 示例：

import { z } from 'zod';
import { generateId } from 'ai';
import { openai } from '@ai-sdk/openai';
import { agent, ChatFlow } from 'ai-sdk-agents';

// 数学 Agent
const mathAgent = agent({
  model: openai('gpt-4o'),
  description: 'Math expert',
  system: 'You are a math expert.',
  output: z.object({ answer: z.string() }),
  asTool: {
    input: z.object({ question: z.string() }),
    getPrompt: ({ question }) => ({ prompt: `Solve: ${question}` })
  }
});

// 主助手 Agent，内置数学工具
const assistantAgent = agent({
  model: openai('gpt-4o'),
  system: 'You are a helpful assistant.',
  tools: { math: mathAgent },
  maxSteps: 5,
  toolChoice: 'auto'
});

// 创建对话流
const chat = new ChatFlow({ agent: assistantAgent });

// 运行对话
const { result } = await chat.run({
  history: [{ role: 'user', content: 'What is 25 * 17?' }]
});

项目还提供了两个完整示例：

• examples/contexts：演示如何注入自定义上下文（日期、用户信息等）
• examples/express：完整的 Express 流式对话 API 实现

技术架构：简洁但有深度

项目结构

src/
├── agent.ts        # 核心 Agent 定义
├── context.ts      # 上下文管理
├── flow.ts         # 流控制基类
├── flows/
│   └── chat-flow.ts  # ChatFlow 实现
├── tools.ts        # 工具系统
├── prompt.ts       # Prompt 处理
├── memory.ts       # 记忆管理
└── stream.ts       # 流式响应处理

核心类型设计

项目大量使用 TypeScript 泛型来保证类型安全：

• LlmAgent<C, P>：Agent 的类型定义，C 为上下文类型，P 为工具参数类型
• GenericToolSet<C>：工具集合，支持 Tool / LlmAgent / IToolFactory 三种类型
• toolChoiceSchema：通过 Zod 定义工具选择策略的枚举

整个架构遵循 组合优于继承 的原则：Agent 由模型、系统提示、工具集组合而成，而非通过复杂类继承实现。

代码质量与工程实践

作为个人项目，代码质量令人印象深刻：

• 测试：使用 Vitest，覆盖率报告通过 @vitest/coverage-v8 生成
• 代码风格：ESLint + Prettier + Husky Git Hooks，提交前自动检查格式
• 发布管理：使用 Changesets 进行语义化版本控制和 CHANGELOG 管理
• 构建：TypeScript 编译 + tsup 打包，输出兼容 ESM / CJS / UMD 三种格式
• 文档：README 完整，提供了多个可运行的示例

当前不足与局限性

• Node.js 版本要求较高：需要 ≥22.0.0，部分生产环境可能受限
• 文档不够完善：README 示例有限，复杂的嵌套 Agent 场景缺乏指导
• 无开箱即用的 Web UI：需要自己基于 Express/Next.js 搭建
• 缺少生产级部署配置：无 Docker 支持，不适合纯容器化部署场景
• Agent 间内存尚未实现（TODO 中）

行业意义：Agent 编排的轻量级方案

当前主流的 Agent 编排框架（如 LangGraph、CrewAI）往往面向 Python 生态，且学习曲线陡峭。AI SDK Agents 的价值在于：为 JavaScript/TypeScript 生态提供了一个轻量、类型安全、上手极快的 Agent 编排方案。

对于已经在使用 Vercel AI SDK 的团队，迁移成本几乎为零；对于新项目，这是一个值得优先考虑的 Agent 基础设施选择。随着 AI 应用从"单次调用"走向"多步推理"，这类编排层工具的需求会持续增长。