1. 项目缘起与整体架构设计1.1 为什么我要做这个英语情景教学Agent做英语教学类产品的人都有一个共识传统背单词、刷题模式的学习留存率极低用户坚持不过两周。真正有效的语言习得方式是沉浸式情景对话——把学习者丢进一个具体场景里比如在星巴克点单机场值机酒店投诉空调坏了逼着他用目标语言完成任务。但真人外教成本高、时间难约AI恰好能补上这个缺口。我做的这个英语情景教学Agent核心目标就一句话用户选一个场景Agent扮演场景中的角色用英语跟用户进行多轮对话并在对话过程中实时纠错、给出更地道的表达建议。它不是一个简单的你问我答聊天机器人而是有角色设定、有教学目标、有动态难度调整的对话系统。技术选型上后端用Python FastAPI前端用React实时通信走WebSocket。为什么不用HTTP轮询因为教学场景对延迟极其敏感——用户说完一句话如果等两三秒才看到Agent的回复和纠错提示沉浸感直接碎掉。WebSocket的全双工特性让服务端可以主动推送消息比如Agent在用户说话过程中就可以推送注意时态的提示而不是等整轮对话结束才反馈。这个项目适合谁参考如果你正在学Agent开发想找一个有真实业务场景、不是玩具demo的项目如果你在纠结FastAPI项目目录结构怎么设计才合理如果你想搞明白WebSocket心跳机制实现和断线重连到底怎么写才稳——那这篇内容应该能帮你省下不少查文档的时间。1.2 整体架构拆解数据怎么流模块怎么分先上一张我实际落地的架构思路图文字描述版因为我不喜欢在博文里塞流程图用户浏览器打开React前端 → 建立WebSocket连接 → FastAPI的WebSocket端点接收连接 → 连接管理器注册该会话 → 用户发送语音或文本 → 后端ASR语音转文字如果用语音输入→ Agent核心处理模块 → 调用LLM生成回复 → 同时触发纠错分析模块 → 将回复和纠错建议通过WebSocket推回前端 → 前端渲染对话气泡和纠错卡片。这里有几个关键设计决策值得展开说第一Agent核心和WebSocket层解耦。很多人写Agent项目喜欢把LLM调用直接写在WebSocket的接收回调里结果就是代码耦合严重想换个模型或者加个中间件都得动通信层。我的做法是WebSocket层只负责连接管理和消息路由Agent逻辑封装在独立的Service类里通过依赖注入的方式传给WebSocket端点。这样单元测试也好写——直接测Service不用起WebSocket。第二会话状态存在内存里但设计了持久化接口。教学Agent需要记住对话历史、用户当前水平、已经纠错过的语法点这些状态如果每次请求都从数据库读延迟受不了。我用了一个SessionStore类底层是字典加TTL过期但预留了Redis适配器接口。开发阶段用内存上线换Redis只需要改一行配置。第三纠错和回复并行处理。用户说了一句话Agent需要做两件事生成符合角色设定的回复以及分析用户这句话的语法和用词问题。这两件事没有依赖关系可以并行。我用asyncio.gather把两个LLM调用并发执行整体响应时间从串行的4秒降到2秒左右。这个优化在教学场景里体感差异巨大。2. 后端核心FastAPI WebSocket的工程化落地2.1 FastAPI项目目录结构怎么设计才不乱我见过太多FastAPI项目把所有路由塞在一个main.py里写到后面自己都找不到代码。这个项目的目录结构我调整了三版最终定下来是这样english-tutor-agent/ ├── app/ │ ├── main.py # 应用入口注册路由和中间件 │ ├── config.py # 配置管理读环境变量 │ ├── api/ │ │ ├── __init__.py │ │ ├── websocket.py # WebSocket端点 │ │ └── health.py # 健康检查 │ ├── core/ │ │ ├── agent.py # Agent核心逻辑 │ │ ├── session.py # 会话状态管理 │ │ └── prompts.py # 提示词模板 │ ├── services/ │ │ ├── llm_service.py # LLM调用封装 │ │ └── correction.py # 纠错分析服务 │ ├── models/ │ │ └── schemas.py # Pydantic模型 │ └── utils/ │ └── logger.py # 日志配置 ├── tests/ ├── requirements.txt └── .env这个结构的好处是职责边界清晰。api/只处理HTTP和WebSocket协议层的东西core/放业务逻辑services/放外部依赖的封装。举个例子哪天我想把LLM从某个模型换成另一个只需要改services/llm_service.pycore/agent.py完全不用动。注意config.py里我用的是pydantic-settings不是直接读os.environ。前者有类型校验配置写错了启动就报错不会等到运行时才发现。2.2 WebSocket连接管理别让连接泄漏拖垮服务WebSocket连接管理是这类项目最容易出问题的地方。我踩过的坑包括用户直接关浏览器标签页服务端不知道连接已断连接对象一直挂在内存里多个标签页打开同一账号消息推送到错误的连接心跳超时没处理僵尸连接越积越多。我的解决方案是写一个ConnectionManager类核心逻辑如下import asyncio from fastapi import WebSocket from typing import Dict class ConnectionManager: def __init__(self): self.active_connections: Dict[str, WebSocket] {} self._lock asyncio.Lock() async def connect(self, session_id: str, websocket: WebSocket): await websocket.accept() async with self._lock: if session_id in self.active_connections: old self.active_connections[session_id] try: await old.close(code1000) except Exception: pass self.active_connections[session_id] websocket async def disconnect(self, session_id: str): async with self._lock: self.active_connections.pop(session_id, None) async def send_personal(self, session_id: str, message: dict): ws self.active_connections.get(session_id) if ws: try: await ws.send_json(message) except Exception: await self.disconnect(session_id)这里有几个细节值得说。第一用asyncio.Lock保护字典操作。虽然Python的GIL让字典操作本身是原子的但检查是否存在→关闭旧连接→写入新连接这个复合操作不是原子的并发场景下可能出问题。第二send_personal里捕获异常后主动断开。如果发送失败说明连接已经不可用留着只会占内存。第三同一session_id的新连接会踢掉旧连接。这是产品决策——教学场景不允许同一账号多端同时对话否则状态会乱。2.3 WebSocket心跳机制实现别等TCP超时才清理WebSocket协议本身有ping/pong帧但很多代理和负载均衡器会拦截或延迟这些帧。我的做法是在应用层实现一套心跳机制不依赖协议层。服务端启动一个后台任务每30秒遍历所有活跃连接发送一个{type: ping}消息。前端收到后必须在10秒内回复{type: pong}。如果超时未回复服务端主动关闭连接并清理。async def heartbeat_loop(manager: ConnectionManager): while True: await asyncio.sleep(30) for session_id in list(manager.active_connections.keys()): try: await manager.send_personal(session_id, {type: ping}) except Exception: await manager.disconnect(session_id)前端对应的处理逻辑ws.onmessage (event) { const data JSON.parse(event.data); if (data.type ping) { ws.send(JSON.stringify({ type: pong })); return; } // 处理正常业务消息 };实操心得心跳间隔不要设太短。我一开始设了10秒结果移动端网络切换时频繁误判断线用户体验很差。30秒是实测下来比较平衡的值——既能及时发现死连接又不会因为网络抖动误杀。2.4 断线重连前端要做的比后端多WebSocket断线是常态不是异常。移动端切后台、地铁进隧道、WiFi切4G都会断。后端能做的是清理连接重连的责任主要在前端。我的React端重连策略是指数退避 最大重试次数const connect (retryCount 0) { const ws new WebSocket(wss://api.example.com/ws/${sessionId}); ws.onclose () { if (retryCount 5) { const delay Math.min(1000 * Math.pow(2, retryCount), 16000); setTimeout(() connect(retryCount 1), delay); } else { // 提示用户手动刷新 } }; ws.onopen () { // 重连成功后恢复会话状态 ws.send(JSON.stringify({ type: resume, sessionId })); }; };重连成功后前端发送resume消息后端从SessionStore里恢复对话历史把断线期间可能错过的消息补推给前端。这里有个坑如果断线时间太长会话可能已经过期。我的处理是后端返回一个session_expired消息前端引导用户重新选择场景开始新对话。3. Agent核心提示词工程与纠错逻辑3.1 角色设定提示词怎么写才不出戏英语情景教学Agent最容易翻车的地方是角色一致性。你设定它是星巴克店员结果用户问了个语法问题它突然变成语法老师开始长篇大论沉浸感瞬间归零。我的提示词模板分三层角色层、任务层、约束层。角色层定义Agent是谁、在什么场景、说话风格如何。比如You are a barista at a busy Starbucks in Seattle. You are friendly but efficient, using casual American English. You never break character. You never explain grammar rules directly.任务层定义Agent要做什么推进对话、在合适时机给出更地道的表达建议。约束层是最关键的定义Agent不能做什么- Never output more than 3 sentences per turn. - Never use Chinese. - If the user makes a grammar error, do NOT correct it directly. Instead, naturally use the correct form in your reply. - If the user seems stuck, offer a hint in the form of a question.最后一条用正确形式自然复述是我试了很多次才定下来的。直接纠错会打断对话流但用正确形式复述一遍用户潜意识里就接收到了正确表达。比如用户说I want go to airportAgent回复Oh, you want to go to the airport? Gate 12 is that way.——既推进了对话又示范了正确用法。3.2 纠错分析模块单独跑一个LLM调用虽然Agent本身不直接纠错但教学产品必须给用户显式的反馈。我的做法是纠错分析独立成一个LLM调用和对话生成并行执行。纠错分析的提示词要求模型输出结构化JSON{ has_error: true, errors: [ { original: I want go to airport, corrected: I want to go to the airport, type: grammar, explanation: want后面接不定式to do不能直接跟动词原形 } ], suggestion: 更地道的说法Id like to head to the airport. }前端拿到这个JSON后在对话气泡下方渲染一个纠错卡片用不同颜色标注语法错误、用词不当、表达不地道三类问题。注意纠错分析的LLM调用要设置temperature0保证输出稳定。对话生成可以用temperature0.7让回复更自然多变。这两个参数不能共用。3.3 动态难度调整让Agent跟着用户水平走固定难度的教学Agent有个问题对初学者太难对进阶者太简单。我加了一个简单的难度评估逻辑每次纠错分析后统计用户最近5轮对话的错误率。错误率高于40%降低Agent用词复杂度低于10%提高复杂度并引入更多地道俚语。实现上我在SessionStore里维护一个difficulty_level字段取值1到5。每次纠错分析后更新下次生成对话时把难度等级注入提示词Current difficulty level: 3/5. Use vocabulary appropriate for an intermediate learner. Avoid idioms and phrasal verbs at this level.这个机制不复杂但效果立竿见影。测试时明显感觉到初学者不会被长难句吓跑进阶者也不会觉得无聊。4. 前端React实现状态管理与实时渲染4.1 React状态设计别把所有东西塞一个useState前端这块我踩的最大坑是状态管理混乱。一开始所有对话消息、连接状态、纠错数据都塞在几个useState里结果WebSocket消息一来多个状态更新触发多次重渲染页面卡顿明显。后来我改成useReducer统一管理对话状态const initialState { messages: [], connectionStatus: connecting, currentScenario: null, difficultyLevel: 3, errorCard: null, }; function chatReducer(state, action) { switch (action.type) { case ADD_MESSAGE: return { ...state, messages: [...state.messages, action.payload] }; case SET_CONNECTION: return { ...state, connectionStatus: action.payload }; case SET_ERROR_CARD: return { ...state, errorCard: action.payload }; default: return state; } }useReducer的好处是状态更新逻辑集中而且可以配合useImmer让不可变更新写起来更简洁。另外WebSocket实例我用useRef存不用useState——因为WebSocket对象变化不需要触发重渲染。4.2 WebSocket消息的防抖与批量处理Agent回复是流式的一个字一个字推过来。如果每个字符都触发一次setStateReact渲染压力很大。我的做法是前端缓冲 requestAnimationFrame批量更新const bufferRef useRef(); const rafRef useRef(null); const handleStreamChunk (chunk) { bufferRef.current chunk; if (!rafRef.current) { rafRef.current requestAnimationFrame(() { dispatch({ type: UPDATE_LAST_MESSAGE, payload: bufferRef.current }); bufferRef.current ; rafRef.current null; }); } };这样无论流式消息多密集每帧最多更新一次渲染性能提升非常明显。实测在低端安卓机上从卡顿到流畅的差异肉眼可见。4.3 对话气泡与纠错卡片的渲染细节UI这块我不展开讲样式只说两个和Agent交互强相关的点。第一消息类型要区分。对话消息分三种用户消息、Agent消息、系统提示比如连接已恢复。每种渲染样式不同用message.role字段区分。第二纠错卡片要可折叠。一开始我把纠错信息直接展开显示结果对话流被切得很碎。改成默认折叠、点击展开后阅读体验好很多。用户可以选择性查看纠错不打断对话节奏。第三自动滚动到底部要判断用户是否在手动滚动。如果用户正在往上翻看历史消息新消息来了不要强制滚到底部。用scrollTop clientHeight scrollHeight - 50判断用户是否在底部。5. 常见问题与排查技巧实录5.1 WebSocket连接但不接收消息这是最高频的问题。现象是前端onopen触发了但onmessage一直不执行。排查思路按顺序来排查项检查方法常见原因服务端是否发送后端日志打点Agent处理超时消息没发出去消息格式浏览器Network面板WS帧发送了非JSON格式前端解析报错代理层拦截对比直连和经代理代理不支持WebSocket升级前端监听器检查onmessage赋值时机在onopen之前赋值但被覆盖我遇到过一次是代理层配置问题WebSocket握手成功但数据帧被缓冲。换成直连后正常。这类问题排查时先用wscat命令行工具直连后端确认服务端没问题再逐层往上查。5.2 Agent回复延迟高怎么优化延迟来源有三个LLM调用、网络传输、前端渲染。我的优化顺序是LLM调用并行化对话生成和纠错分析用asyncio.gather并发省掉一半时间。流式输出不等LLM生成完整回复边生成边推。首字延迟从3秒降到0.8秒。提示词精简提示词越长LLM处理越慢。我把角色设定从500字压到200字延迟降低约15%。前端批量渲染前面说的requestAnimationFrame方案解决渲染瓶颈。实测下来端到端延迟从最初的5秒降到1.5秒左右教学场景完全够用。5.3 会话状态丢失的排查用户反馈聊到一半Agent突然失忆。排查发现是SessionStore的TTL设太短用户思考时间长了点会话就过期了。改成滑动过期——每次收到消息就刷新TTL而不是固定过期时间。另一个原因是多worker部署。FastAPI用uvicorn --workers 4启动时每个worker有独立的内存会话状态不共享。开发阶段单worker没问题上线就出bug。解决方案是会话状态外置到Redis所有worker共享。实操心得开发阶段就用Redis存会话状态别等上线才发现问题。本地起个Redis容器成本很低但能避免一类很难排查的bug。5.4 LLM输出不稳定怎么兜底LLM偶尔会输出不符合格式的内容比如纠错分析要求返回JSON结果返回了一段自然语言。我的兜底策略是三层防护第一层提示词里明确要求Output valid JSON only, no markdown code fences。 第二层解析时用try/except包裹解析失败则用正则提取JSON片段。 第三层如果还是失败降级为不显示纠错卡片只显示对话回复同时记录日志。这样即使LLM抽风用户也不会看到报错只是少了一次纠错反馈。6. 部署与并发扛压的实战经验6.1 AI Agent怎么扛并发Agent类应用的并发瓶颈不在WebSocket连接数而在LLM API的速率限制。我的做法是加一个信号量控制import asyncio llm_semaphore asyncio.Semaphore(10) async def call_llm(prompt): async with llm_semaphore: return await llm_client.generate(prompt)这样最多同时10个LLM调用超出的请求排队等待。配合前端显示Agent正在思考的加载状态用户感知不到排队。另外连接数本身也要限制。我在ConnectionManager里加了最大连接数检查超过阈值的新连接直接拒绝并返回server_busy消息。这比让所有连接都卡着体验好。6.2 部署清单与配置要点部署这块我列一个实际用的清单反向代理Nginx配置WebSocket升级proxy_read_timeout设300秒以上否则长连接会被切断。进程管理用gunicorn配合uvicorn workerworker数量设为CPU核数的2倍。环境变量LLM API Key、Redis地址、日志级别全部走环境变量不硬编码。健康检查/health端点返回服务状态和当前连接数方便监控。日志WebSocket连接建立、断开、消息收发都打日志但不要打完整消息内容只打长度和类型避免日志爆炸和隐私问题。6.3 后续可以扩展的方向这个项目目前是文本对话为主后续我打算加两个东西。一是语音输入用浏览器原生Web Speech API做ASR成本低且延迟可接受。二是多场景切换用户在一个会话里可以从点咖啡切换到投诉咖啡太凉Agent角色无缝切换。技术上就是把场景配置做成可插拔的每个场景一个提示词模板文件。另外纠错数据积累下来是很有价值的。可以做一个用户学习报告统计高频错误类型、进步曲线这对教学产品来说是核心留存功能。数据已经在存了只差一个展示页面。这个项目从零到跑通大概花了我两周的业余时间其中一半时间花在WebSocket稳定性调优上。如果你也在做类似的东西我的建议是先把通信层做稳再搞Agent逻辑。通信不稳Agent再聪明用户也感知不到。反过来通信稳了Agent哪怕简单一点体验也是流畅的。
