别人开发的 Agent 用久了,肯定会有想法自己也开发一个,而且,这个开发过程能使我们更深一步理解 Agent 的实现原理。
本文是一系列文章的第一篇,介绍使用前端技术栈从零开发一个 Agent。
路线图不是固定死的,后续可能会不断调整。
实现方式:直接基于本项目(本项目是一个 Next.js 全栈项目),开发一个类似于 Manus 的在线版网页 Agent。
功能清单:
当然,技术选型也不是固定死的,如果某些库不好用,后续随时会换掉,并更新此列表。
已有的库: 目前,PaperPlane.cc 使用了 Next.js、Prisma、Redis、tRPC、Shadcn/UI、Zod 等工具; 也就是说,数据请求、ORM、缓存、数据验证这些方面不需要准备额外的库。
AI 核心 SDK:
使用 Vercel AI SDK v7 来调度 AI 大模型,这包含了 ai 和 @ai-sdk/* 等一系列包;
当然,也可以使用 LangGraph。
UI 组件库: 使用 Vercel AI Elements 作为组件库,它专为开发 Agent 而创立,而且是基于 Shadcn/UI 的,易于定制。 在 Shadcn/UI 的 第三方库目录 页面搜索 “ai”,可以找到很多专门为 AI 准备的 UI 组件库,例如:LobeHub UI、LiveKit Agents UI、WebLLM、Assistant UI 等;当然也可以使用普通的不基于 Shadcn/UI 的组件库,例如 Ant DesIgn X。
还可以使用 LobeIcons,它提供了大量 AI 大模型和对应厂商的矢量格式图标。
Markdown 渲染: 使用 Vercel Streamdown,它可以流式渲染 Markdown。
网络搜索: 使用 Tavily 即可,它也有对应的 SDK。
杂项: 使用 Vercel 的 resuamable-stream 实现可恢复流;使用 TokenLens 实现 Token 消耗统计;使用 ai-stream-utils 处理流式输出。
首先,安装几个最基础的包:
pnpm add ai @ai-sdk/reactVercel AI SDK 内置了对他们自家的 AI Gateway 的适配,可以零配置对接; 但是,如果你不使用他们的服务,那么需要额外安装适配器。
Vercel AI Gateway 添加付款方式后,只要从未充值过,每个月有 5 美金的免费赠金。但只要充值过任意金额后,就不再有赠金了。
而且,现在免费政策收紧,这笔赠金只能用最高 GPT-5.2 这种模型,每个模型还有用量限制,差不多用 2.5 美元就必须换别的模型了,免费赠金意义不大。
在这个项目中,为了节约成本,我使用支持 1M 上下文且兼容 OpenAI 请求格式的 DeepSeek v4 Flash 模型,因此需要安装以下适配器:
pnpm add @ai-sdk/openai-compatible然后,我们添加一些 AI 大模型的 Endpoint 环境变量:
# AI 主模型 服务商请求 Endpoint URL
AI_MAIN_MODEL_ENDPOINT =
# AI 主模型 服务商请求 API Key
AI_MAIN_MODEL_API_KEY =因为后续还会有类似于 “辅助模型” 等设定,因此,现在添加的模型定名为 “主模型”。
Vercel AI SDK 需要创建 “模型”:
import { createOpenAICompatible } from '@ai-sdk/openai-compatible'
export const mainModelId = 'deepseek-v4-flash'
export const mainModel = createOpenAICompatible({
name: mainModelId,
baseURL: process.env.AI_MAIN_MODEL_ENDPOINT!,
apiKey: process.env.AI_MAIN_MODEL_API_KEY,
})(mainModelId)这里,createOpenAICompatible 创建出来的叫 “Provider”,必须传给它一个模型名,才能选择模型,因此后面接上 (mainModelId)。
这个文件可以作为公共文件,因为后续都会使用它来获取模型。
然后,我们要提供一个后端接口,它同样使用 Vercel AI SDK,返回流式的大模型输出:
import { createTextStreamResponse, streamText, toTextStream } from 'ai'
import { mainModel } from '@/lib/agent/models'
export async function POST(request: Request) {
const { prompt } = (await request.json()) as { prompt: string }
const result = streamText({ model: mainModel, prompt })
return createTextStreamResponse({ stream: toTextStream({ stream: result.stream }) })
}这段代码接收用户的 POST 提交,提取 prompt 字段内容作为输入,通过 AI SDK 提供的 streamText 函数获取大模型输出,并使用 toTextStream 配合 createTextStreamResponse 转为流式 HTTP 响应。
然后就是前端代码了:
'use client'
import { useCompletion } from '@ai-sdk/react'
export default function ChatDemo1() {
const { completion, complete, error, input, isLoading, setCompletion, setInput } = useCompletion({
api: '后端接口的路径',
streamProtocol: 'text',
})
function handleSend() {
setCompletion('')
setInput('')
complete(input.trim())
}
return (
<div>
<textarea onChange={e => setInput(e.target.value)} value={input} />
<button disabled={!input.trim() || isLoading} isLoading={isLoading} onClick={handleSend}>
发送
</button>
<div>{error?.message ?? (isLoading ? '生成中...' : '')}</div>
<div>{completion}</div>
</div>
)
}这里使用了 Vercel AI SDK 的 useCompletion,其中 input 和 completion 分别是输入和输出文本,还有几个布尔值状态;可以认为是几个 React State 被组合在一起。填写好后端接口路径,即可通过 complete 函数发起请求。
将它们组装,渲染组件如下(样式经过了额外美化):
我们完成了最基础的文本输出 AI 大模型对接。
如果 AI 输出了 Markdown 格式,页面无法正确渲染。此时,推荐使用 Vercel 的 streamdown 来美化输出;虽然渲染 Markdown 的库非常多,但 streamdown 是 Vercel 专为大模型流式输出而开发的渲染器,它可以正确处理未闭合的标签。
安装 streamdown 和配套的插件:
pnpm add streamdown @streamdown/cjk @streamdown/code其中,@streamdown/cjk 可以让 Markdown 的标记语法在连接中日韩文字时能正确生效,@streamdown/code 用于渲染代码块。
此外,还需要在 TailwindCSS 的全局 CSS 中添加:
@source "../node_modules/streamdown/dist/*.js";
@source "../node_modules/@streamdown/code/dist/*.js";
@source "../node_modules/@streamdown/cjk/dist/*.js";
@import "streamdown/styles.css";引入相关样式。
这样以来,我们就可以更新前端代码,使用 streamdown 来渲染输出:
'use client'
import { useCompletion } from '@ai-sdk/react'
import { cjk } from '@streamdown/cjk'
import { code } from '@streamdown/code'
import { Streamdown } from 'streamdown'
export default function ChatDemo1() {
const { completion, complete, error, input, isLoading, setCompletion, setInput } = useCompletion({
api: '后端接口的路径',
streamProtocol: 'text',
})
function handleSend() {
setCompletion('')
setInput('')
complete(input.trim())
}
return (
<div>
<textarea onChange={e => setInput(e.target.value)} value={input} />
<button disabled={!input.trim() || isLoading} isLoading={isLoading} onClick={handleSend}>
发送
</button>
<div>{error?.message ?? (isLoading ? '生成中...' : '')}</div>
<Streamdown
plugins={{ cjk, code }}
controls={{ code: true, table: true }}
isAnimating={isLoading}
animated
>
{completion}
</Streamdown>
</div>
)
}这里使用了 <Streamdown> 组件,通过 plugins 传入了插件,通过 controls 开启了例如 “代码块右上角的复制按钮” 等 UI 上的交互控件。
渲染组件如下(样式经过了额外美化):
点击输出,可以看出,现在可以在保持流式输出的同时,正确渲染各种 Markdown 标记语法,甚至代码块的代码高亮也可以正确显示。
上面的 Demo,只能单纯地让大模型针对一句话进行回答,连对话都做不到。接下来,我们将实现一个在 JS 中使用变量存储会话记录,并通过 “Chat” 方式实现的 AI 会话系统。
首先,我们安装完整的 Vercel AI Elements 组件库:
npx shadcn@latest add @ai-elements/all因为后续会不断开发新功能,要用到各种 AI 组件,所以直接一次性安装完全。
可以在 OpenAI 官网开发者文档 了解到会话的接口格式。
不过,我们使用 Vercel AI SDK 的话,直接使用对应的函数传参即可,接口格式可以先不研究。 AI 会话是一系列消息历史,从代码角度来说,其实就是一个存放多个消息对象的 JS 数组,新增进来的对话每次都要追加到数组的尾部,然后重新提交。
使用 Vercel AI SDK 实现后端逻辑:
import {
convertToModelMessages,
createUIMessageStreamResponse,
streamText,
toUIMessageStream,
type UIMessage,
} from 'ai'
import { mainModel } from '@/lib/agent/models'
export async function POST(request: Request) {
const { messages } = (await request.json()) as { messages: UIMessage[] }
const modelMessage = await convertToModelMessages(messages)
const result = streamText({ model: mainModel, messages: modelMessage })
return createUIMessageStreamResponse({
stream: toUIMessageStream({ stream: result.stream }),
})
}之前是通过 prompt 接收用户的单条文本输入,现在则是通过 messages 接收完整的会话历史。
前端当然也要修改:
了解基本原理只需要看简化版。完整版代码基本上所有组件都使用来自 AI Elements 的,样式也不再修改,使用原生样式。
渲染组件如下:
你好,我是智能 AI 助手,有任何疑问尽管问我!
这样,我们就实现了一个简单的会话系统。
留言