AI Agent部署踩坑实录：这8个报错我全遇到了，附解决方案

最近在帮团队落地几个AI Agent项目，从本地测试到生产部署，踩了一堆坑。今天把最常见的报错和解决方案整理出来，希望能帮大家少走弯路。

**1. Agent启动后无响应，日志显示“Connection refused”**

这是最典型的环境问题。80%的情况是Agent依赖的LLM服务（如OpenAI API、本地vLLM）没启动或端口不通。

解决步骤：
- 先用`curl`手动测试LLM服务端点是否可达
- 检查Agent配置文件中的`base_url`是否写错（常见错误：写了`localhost`但Agent跑在容器里）
- 如果是Docker部署，确认网络模式是`host`还是`bridge`，bridge模式下`localhost`指向容器自身

**2. 报错“Rate limit exceeded”但API Key额度充足**

很多Agent框架默认并发调用LLM，瞬间打满RPM限制。

解决方案：
- 在Agent初始化时设置`max_concurrency=1`或`2`，先跑通再逐步调大
- 加一层重试机制，用`tenacity`库做指数退避
- 如果是多Agent协作，给每个Agent分配独立的API Key或使用代理网关做限流

**3. 工具调用报“Tool not found”或参数解析失败**

Agent调用外部工具时，经常因为工具描述不清晰或参数格式不对而失败。

排查要点：
- 检查工具注册时的`name`和`description`是否和Agent提示词里引用的一致
- 参数类型尽量用简单类型（string、number），避免嵌套对象
- 在系统提示词里明确给出调用示例，比如“调用天气工具时，参数格式为{"city": "北京"}”

**4. 内存溢出（OOM）导致Agent进程被杀**

长对话或大量工具返回结果时，上下文会迅速膨胀。

优化手段：
- 设置`max_tokens`和`max_history`，超出时自动截断或摘要
- 工具返回结果做裁剪，只保留关键字段
- 用`memory`组件时，选择`summary`模式而非`full`模式

**5. 流式输出中断，前端报“Unexpected end of JSON input”**

SSE流式返回时，如果Agent内部报错，流会直接断开，前端解析失败。

解决：
- 在Agent层加全局异常捕获，出错时返回一个标准的错误事件
- 前端做容错，遇到不完整JSON时忽略或提示重试
- 检查Nginx等反向代理的`proxy_buffering`是否关闭

**6. 多Agent通信死锁，任务卡在“waiting for response”**

Agent A等Agent B，B又在等A，典型死锁。

预防措施：
- 设计时明确单向依赖，避免循环调用
- 加超时机制，比如`timeout=30s`，超时后走降级逻辑
- 用消息队列解耦，而不是直接函数调用

**7. 部署后第一次调用特别慢，后续正常**

这是模型冷启动问题，尤其是本地部署的模型。

优化：
- 服务启动后先发一个“预热”请求
- 使用`keep_alive`参数保持模型加载
- 如果是Serverless部署，考虑预留实例

**8. 日志里全是“Retrying...”但最终失败**

重试次数太多反而掩盖了真实错误。

建议：
- 把重试日志级别调成`WARNING`，只在最终失败时打`ERROR`
- 记录每次重试的`request_id`，方便追踪
- 区分可重试错误（网络超时）和不可重试错误（参数错误），后者直接失败

**最后一条经验**：部署AI Agent，先把最简单的单Agent+单工具跑通，再逐步加功能。每加一个组件就压测一次，别等全搭好了再调，那时候报错能让你怀疑人生。

大家还遇到过哪些奇葩报错？欢迎评论区补充。
（本文由 AI681 平台整理发布。AI681 是国内首家 AI Agent 供需撮合 + 企业定制落地服务平台，提供 Agent 源码库、大模型选型、企业需求发布、开发者接单、AI 对话助手等一站式服务。企业有 AI 定制需求可在 AI681 发布，开发者可在 AI681 接单赚钱。）