【全栈实践】第一个 AI Agent 项目：从零搭建 AI 音频创作助手（入门篇）
内容提要
该项目是一个AI驱动的音频内容创作助手，支持通过自然语言生成定制语音、复刻音色及管理本地音频文件。前端使用Vue 3、TypeScript、Tailwind CSS和ai-elements-vue组件库，后端基于FastAPI、LangChain 1.0和LangGraph，通过SSE和AG-UI协议实现流式交互。系统具备多轮对话记忆，并调用阿里云TTS生成音频。文章还分享了开发中遇到的版本兼容和缓冲问题及解决心得。
延伸解读
技术选型背后的考量
项目选择 Vue 3 + TypeScript + Vite 作为前端基础，强调 Composition API 对复杂交互的支持和 Vite 的开发体验。后端采用 FastAPI 与 LangChain 1.0，利用其异步特性和新 API 体系。UI 层选用 Tailwind CSS、shadcn-vue 和 ai-elements-vue，其中 ai-elements-vue 专为 AI 对话场景设计，减少了基础 UI 的重复建设。这些选择反映了当前 AI 应用开发的主流趋势，但需注意框架版本迭代快，需锁定版本
SSE 与 AG-UI 协议的优势
项目使用 SSE 而非 WebSocket 实现流式通信，因为 AI 对话是单向推送场景，SSE 更轻量。AG-UI 协议定义了标准事件类型，如 TEXT_MESSAGE_CONTENT 和 TOOL_CALL_RESULT，使前后端解耦。后端通过 StreamProcessor 将 LangGraph 的 chunk 转换为 AG-UI 事件，前端统一解析并更新 UI。这种设计简化了通信逻辑，但需注意 SSE 可能被中间件缓冲，需添加 X-Accel-Buffering: no 响应头。
LangGraph 多轮记忆的实现
项目利用 LangGraph 的 InMemorySaver 按 thread_id 保存对话历史，前端只需发送当前消息，后端自动恢复上下文。这简化了前端状态管理，但 InMemorySaver 仅适用于本地尝试，生产环境需改用数据库持久化。此外，LangChain 1.0 的 API 变化较大，旧教程代码可能失效，建议直接参考官方文档和 Changelog。
新手避坑指南
作者分享了几个常见问题：LangChain 1.0 废弃了旧 API，需使用 create_agent；SSE 响应可能被 gzip 缓冲，需添加响应头；前后端跨域需同时配置 CORS 和 Vite proxy；Python 依赖冲突需使用虚拟环境。这些经验对初学者很有价值，建议在开发前锁定框架版本，并优先跑通整体链路，再深入优化细节。
Q&A
这个AI音频创作助手项目主要实现了哪些功能？
该项目是一个AI驱动的音频内容创作助手，主要功能包括：通过文字描述生成定制语音、音色复刻合成语音、直接使用已复刻音色合成语音，以及本地音频资源展示和管理。用户可以用自然语言与AI对话，AI会理解意图并调用语音合成工具生成音频文件保存在本地。
这个项目的前端技术栈是什么？
前端使用Vue 3、TypeScript、Vite、Tailwind CSS、shadcn-vue和ai-elements-vue组件库。其中Vue 3采用Composition API，TypeScript提供静态类型检查，Vite用于构建，Tailwind CSS实现原子化样式，ai-elements-vue提供AI对话场景的UI组件。
后端技术栈有哪些？为什么选择这些技术？
后端使用Python 3.11+、FastAPI、LangChain 1.0、LangGraph、SSE和AG-UI协议，并调用阿里云Qwen TTS。FastAPI基于ASGI支持流式响应，LangChain 1.0提供新的Agent API，LangGraph用于构建Agent并管理多轮对话记忆，SSE和AG-UI实现流式通信，阿里云TTS用于语音合成。
项目是如何实现多轮对话记忆的？
项目使用LangGraph的InMemorySaver作为checkpointer，按thread_id保存每次对话的完整消息历史。每次用户发新消息时，只需传入当前消息，LangGraph会自动从checkpoint中恢复上下文，前端无需维护历史。但InMemorySaver仅适合本地简单尝试，真实业务需使用数据库。
为什么选择SSE而不是WebSocket？
SSE是单向的服务器推送，基于普通HTTP连接，比WebSocket更轻量，不需要额外的握手和连接管理。对于AI对话这种用户发一条、AI持续回复的场景，SSE完全够用，因此选择SSE。
AG-UI协议是什么？它定义了哪些事件类型？
AG-UI是一套专门为AI Agent与前端通信设计的事件规范，定义了标准事件类型，如RUN_STARTED、TEXT_MESSAGE_START、TEXT_MESSAGE_CONTENT、TEXT_MESSAGE_END、TOOL_CALL_START、TOOL_CALL_ARGS、TOOL_CALL_END、TOOL_CALL_RESULT和RUN_FINISHED。这些事件用于流式传输文本增量和工具调用结果。
开发过程中遇到了哪些坑？如何解决的？
遇到的坑包括：LangChain 1.0版本API变化大，旧代码无法使用，需参考官方Changelog；SSE响应被gzip压缩缓冲，导致流式效果失效，解决方法是添加X-Accel-Buffering: no响应头；跨域和代理配置需同时设置FastAPI的CORS和Vite的proxy；Python依赖版本冲突需使用虚拟环境隔离。
项目整体架构是怎样的？
项目分为前端和后端。前端使用Vue 3，通过api/chat.ts发送POST请求到后端，建立SSE长连接。后端使用FastAPI接收请求，创建StreamingResponse，LangGraph Agent流式执行，每个chunk经StreamProcessor转换为AG-UI事件，以SSE格式推送到前端。前端解析事件并更新UI，实现文本打字机效果和工具结果卡片展示。
