Agent 与 Chat 的本质区别
| Chat | Agent |
|---|---|
| 单轮/多轮文本 | 多步执行 |
| 无工具 | 可调 API、DB、代码 |
| 无状态或仅会话 | 记忆 + 计划 |
Agent = LLM 决策 + 工具执行 + 状态机循环。
四大组件
1. Planner（规划）
把用户目标拆成步骤。可以是：
- 隐式（模型直接 tool call）；
- 显式（先输出 JSON plan，再逐步执行）。
2. Tools（工具）
每个 tool 需：name、description、parameters schema、handler。
粒度原则：小而专，便于模型选择与审计。
3. Memory（记忆）
- 短期：当前会话 messages；
- 长期：向量库 + 摘要（用户偏好、项目上下文）；
- 工作记忆：本轮 plan 的中间结论。
4. Orchestrator（编排器）
控制循环：何时继续、何时结束、失败重试、最大步数。
本博客 Agent 模块映射
站点 /ai 对应 backend/src/modules/agent：
- 会话持久化：Conversation / Message 表；
- 流式输出：SSE 降低首字延迟；
- 附件与搜索范围：工具能力的产品化封装；
- 开关：
chatEnabled便于运维熔断。
这是 产品型 Agent，比 CLI Agent 多了鉴权、限流、审计。
失败模式与护栏
- 无限循环 →
maxSteps+ 重复检测； - 工具幻觉 → strict JSON schema + 服务端校验；
- 成本爆炸 → 上下文 summarize、模型分级；
- 敏感操作 → human-in-the-loop 确认。
Python 栈常见选型
- LangGraph / 自研状态机：显式循环；
- FastAPI：对外 HTTP + SSE；
- Celery / ARQ：长任务异步；
- PostgreSQL + pgvector：记忆检索。
小结
画 Agent 架构时，先问：工具有哪些、记忆存哪、循环谁管、失败怎么办。四问清楚，再选框架，避免「只会 chat 的假 Agent」。
参考：本仓库 agent 模块 · Anthropic/OpenAI tool use 文档。