从 Chat 到 Agent
Chat：一问一答，模型不知道下一步 unless 你继续喂。
Agent：
- 理解目标；
- 拆步骤；
- 调用工具（读文件、跑命令、HTTP、搜索）；
- 观察结果，决定继续或结束。
Cursor Agent、Claude Code、Devin 类产品的本质都是 LLM + 工具循环。
典型架构
User Goal
↓
Planner（可选）
↓
LLM ←→ Tools（file, shell, browser, MCP…）
↓
Memory / State
↓
Answer or PR
关键组件：
| 组件 | 作用 |
|---|---|
| System prompt | 角色、边界、输出格式 |
| Tools schema | 模型可见的能力列表 |
| Context | 仓库、会话、检索结果 |
| Guardrails | 限步数、限命令、审计 |
本博客里的 Agent
站点 /ai 路由对接后端 agent 模块，支持：
- 多轮对话与附件；
- 搜索范围（国内 / 国际）；
- 流式输出；
- 图片生成（对接网关）。
这是 产品化 Agent 而非本地 CLI：要处理会话持久化、鉴权、限流、审计。
自建 Agent 时建议 early 考虑：
- Session 与 token 成本；
- 工具失败的 user-visible 错误；
- 流式中断与重连；
- 管理员关闭开关（
chatEnabled）。
设计工具的原则
- 粒度：一个 tool 做一件事（
read_file、grep），不要 mega tool； - 可观测：日志记录 tool name、参数摘要（脱敏）；
- 幂等：写操作要想清楚重复调用后果；
- 人类闸门：删库、发邮件、部署要确认。
MCP 与 Agent
MCP（Model Context Protocol）让 Agent 以标准方式连接外部系统——数据库、Notion、GitHub。下一篇可专讲 MCP；这里只强调：Agent 的能力边界 = 你接了什么 tool。
失败模式
- 无限循环：max steps、重复检测；
- 工具幻觉：schema 严格校验，未知 tool 拒绝；
- 上下文爆炸：summarize 旧步骤，只留结论；
- 静默错误：tool stderr 必须回传模型。
小结
Agent 工作流 = 目标 + 工具 + 循环 + 护栏。日常开发用 Cursor/Claude Code 已是 Agent；做产品则要补会话、成本与合规。
结合本仓库
backend/src/modules/agent实践总结。