纸飞机的信笺
博客Awesome开源Demos制品库

从零开始搭建 Agent:① 起步、会话、流式 Markdown

  1. 路线图
  2. 技术选型
  3. 迈出第一步:流式文本生成
  4. 流式渲染 Markdown
  5. 支持历史消息上下文

从零开始搭建 Agent:① 起步、会话、流式 Markdown

2026年 5月 30日AI#AI#JS留言: ...

别人开发的 Agent 用久了,肯定会有想法自己也开发一个,而且,这个开发过程能使我们更深一步理解 Agent 的实现原理。

本文是一系列文章的第一篇,介绍使用前端技术栈从零开发一个 Agent。

路线图#

须知

路线图不是固定死的,后续可能会不断调整。

实现方式:直接基于本项目(本项目是一个 Next.js 全栈项目),开发一个类似于 Manus 的在线版网页 Agent。

功能清单:

  • 基础 AI 对话,带有附加功能:例如 Token 统计、智能标题等;
  • 联网搜索;
  • 沙箱、文件系统、代码执行器;
  • 记忆;
  • 多步骤计划;
  • 支持子 Agent,实现例如拆解任务、并行任务等;
  • 表单工具,对模糊不清的任务需求,请求用户给出选择或指示;
  • 支持 Agent Skill,提供 Agent Skills 配置功能;
  • 支持 MCP,提供 MCP 配置功能;
  • 自动上下文压缩总结;
  • 未完待续……

技术选型#

须知

当然,技术选型也不是固定死的,如果某些库不好用,后续随时会换掉,并更新此列表。

已有的库: 目前,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。

沙箱: 使用 E2B 即可,它也有对应的 SDK。

杂项: 使用 Vercel 的 resuamable-stream 实现可恢复流;使用 TokenLens 实现 Token 消耗统计;使用 ai-stream-utils 处理流式输出。

迈出第一步:流式文本生成#

首先,安装几个最基础的包:

pnpm add ai @ai-sdk/react

Vercel 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 函数发起请求。

将它们组装,渲染组件如下(样式经过了额外美化):

在线 Demo

我们完成了最基础的文本输出 AI 大模型对接。

流式渲染 Markdown#

如果 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 上的交互控件。

渲染组件如下(样式经过了额外美化):

在线 Demo

点击输出,可以看出,现在可以在保持流式输出的同时,正确渲染各种 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 接收完整的会话历史。

前端当然也要修改:

'use client'
 
import { useChat } from '@ai-sdk/react'
import { DefaultChatTransport, type UIMessage } from 'ai'
import { useState } from 'react'
 
const chatHistory: UIMessage[] = [
  {
    id: 'welcome',
    parts: [{ text: '你好,我是智能 AI 助手,有任何疑问尽管问我!', type: 'text' }],
    role: 'assistant',
  },
]
 
const transport = new DefaultChatTransport({ api: '后端接口的路径' })
 
export default function Chat() {
  const [input, setInput] = useState('')
  const { messages, sendMessage, status } = useChat({ messages: chatHistory, transport })
 
  return (
    <div>
      {messages.map(message => (
        <div key={message.id}>
          <strong>{message.role === 'user' ? '用户' : 'AI'}:</strong>
          {message.parts.map((part, index) =>
            part.type === 'text' ? <span key={`${message.id}-${index}`}>{part.text}</span> : null
          )}
        </div>
      ))}
 
      <textarea onChange={event => setInput(event.target.value)} value={input} />
      <button
        disabled={!input.trim() || status !== 'ready'}
        onClick={() => {
          setInput('')
          sendMessage({ text: input.trim() })
        }}
      >
        发送
      </button>
    </div>
  )
}
'use client'
 
import { useChat } from '@ai-sdk/react'
import { DefaultChatTransport, type UIMessage } from 'ai'
 
import { Conversation, ConversationContent } from '@/components/ai-elements/conversation'
import { Message, MessageContent, MessageResponse } from '@/components/ai-elements/message'
import {
  PromptInput,
  PromptInputBody,
  PromptInputFooter,
  PromptInputSubmit,
  PromptInputTextarea,
} from '@/components/ai-elements/prompt-input'
 
const chatHistory: UIMessage[] = [
  {
    id: 'welcome',
    parts: [{ text: '你好,我是智能 AI 助手,有任何疑问尽管问我!', type: 'text' }],
    role: 'assistant',
  },
]
 
const transport = new DefaultChatTransport({ api: '后端接口的路径' })
 
export default function Chat() {
  const { error, messages, sendMessage, status, stop } = useChat({
    messages: chatHistory,
    transport,
  })
 
  return (
    <div>
      <Conversation>
        <ConversationContent>
          {messages.map(message => (
            <Message from={message.role} key={message.id}>
              <MessageContent>
                {message.parts.map((part, index) =>
                  part.type === 'text' ? (
                    <MessageResponse
                      isAnimating={
                        message.role === 'assistant' &&
                        status === 'streaming' &&
                        messageIndex === messages.length - 1 &&
                        index === message.parts.length - 1
                      }
                      key={`${message.id}-${index}`}
                    >
                      {part.text}
                    </MessageResponse>
                  ) : null
                )}
              </MessageContent>
            </Message>
          ))}
        </ConversationContent>
      </Conversation>
 
      <PromptInput
        onSubmit={message => void sendMessage({ text: message.text.trim() })}
        className="mt-5"
      >
        <PromptInputBody>
          <PromptInputTextarea
            disabled={status !== 'ready'}
            placeholder="和 AI 说点什么..."
            rows={2}
          />
        </PromptInputBody>
 
        <PromptInputFooter>
          <span>{error?.message ?? (status === 'submitted' ? '等待响应...' : '')}</span>
 
          <PromptInputSubmit onStop={stop} status={status} />
        </PromptInputFooter>
      </PromptInput>
    </div>
  )
}

了解基本原理只需要看简化版。完整版代码基本上所有组件都使用来自 AI Elements 的,样式也不再修改,使用原生样式。

渲染组件如下:

在线 Demo

你好,我是智能 AI 助手,有任何疑问尽管问我!

这样,我们就实现了一个简单的会话系统。

修订记录

  • 2026年 11月 18日
    feat(blog/article): 更新《Agent》系列文章
  • 2026年 7月 8日
    feat(agent): 现在使用 GLM-5.2 模型
  • 2026年 6月 16日
    feat(blog/article): 《Agent 1》所有用例流式输出添加动画;动画判断属性更新
  • 2026年 6月 12日
    refactor(blog/article): 更新《agent 1》,使用 snake_case 的工具名
  • 2026年 6月 11日
    refactor(blog/article): 《Agent 1》更新 demo 文件名和组件名
修订记录

留言