ARTICLE / 2026·07·04
AIAgent框架实践
总结AI Agent的任务规划、工具调用、RAG、多Agent协作、记忆、权限、安全、评估和工程落地模式。
AIAgent框架实践
1. Agent是什么
Agent是能围绕目标进行感知、规划、调用工具、观察结果并迭代的AI系统。与单轮Chat不同，Agent强调状态、工具、反馈和任务闭环。
flowchart TB
G["Goal"] --> P["Plan"]
P --> A["Act: call tool / write file / query DB"]
A --> O["Observe result"]
O --> R["Reason / update state"]
R -->|continue| A
R -->|done| D["Deliver verified result"]
2. 基本组件
| 组件 | 作用 |
|---|---|
| LLM | 任务理解、推理、生成 |
| Tool registry | 声明可用工具和参数schema |
| Planner | 把目标拆成步骤 |
| Executor | 执行工具调用和文件操作 |
| Memory | 保存短期状态和长期经验 |
| RAG | 提供外部知识 |
| Guardrail | 权限、安全和输出约束 |
| Evaluator | 检查结果是否满足目标 |
3. 工具调用
工具调用让Agent从“只生成文本”变成“能操作外部系统”。常见工具包括搜索、数据库、终端、代码编辑、浏览器、工单系统和知识库。
sequenceDiagram
participant U as User
participant A as Agent
participant T as Tool
U->>A: Task
A->>A: Decide tool and arguments
A->>T: Call tool
T-->>A: Observation
A->>A: Validate and continue
A-->>U: Final answer / artifact
工具设计原则：
| 原则 | 说明 |
|---|---|
| Schema明确 | 参数类型、必填项、枚举值清楚 |
| 权限最小化 | 工具只暴露必要能力 |
| 可观察 | 返回足够状态和错误信息 |
| 可回滚 | 高风险操作要有确认或事务 |
| 幂等优先 | 重试不应造成重复副作用 |
4. RAG Agent
RAG Agent适合企业知识库、标准文档、代码仓库和运维Runbook。
| 模块 | 实践要点 |
|---|---|
| Indexing | 按标题、段落、代码符号切分 |
| Retrieval | 向量检索 + 关键词检索混合 |
| Reranking | 过滤无关片段 |
| Citation | 输出引用来源 |
| Freshness | 标记文档版本和更新时间 |
| Permission | 检索前做权限过滤 |
5. 多Agent协作
多Agent不是越多越好，只有当任务存在清晰角色边界时才值得拆分。
| 模式 | 适用场景 | 风险 |
|---|---|---|
| Planner-Executor | 长任务、步骤明确 | Planner脱离执行现实 |
| Researcher-Writer | 调研和成稿分离 | 信息丢失 |
| Coder-Reviewer | 代码生成和审查 | 审查流于表面 |
| Debate | 复杂决策 | 成本高、结论不稳定 |
| Specialist agents | 多领域任务 | 协调复杂 |
flowchart LR
P["Planner"] --> R["Researcher"]
P --> E["Executor"]
R --> W["Writer"]
E --> V["Reviewer"]
W --> V
V --> F["Final artifact"]
6. 记忆设计
| 类型 | 内容 | 注意事项 |
|---|---|---|
| Short-term memory | 当前任务上下文、计划、工具结果 | 防止上下文过长 |
| Long-term memory | 用户偏好、项目约定、历史决策 | 需要可编辑和可删除 |
| Episodic memory | 任务过程和结果 | 用于复盘 |
| Semantic memory | 稳定知识 | 适合放入RAG |
记忆必须可追溯，避免把错误结论永久化。
7. 工作流与自治程度
| 自治级别 | 描述 | 适用 |
|---|---|---|
| Copilot | 人每步确认 | 高风险操作、初期系统 |
| Semi-autonomous | 低风险自动，高风险确认 | 编码、文档、分析 |
| Autonomous | 自主执行并验收 | 明确边界的批处理任务 |
高风险工具应设置approval gate，例如删除数据、发邮件、部署、交易和权限变更。
8. 评估方法
| 维度 | 指标 |
|---|---|
| Task success | 是否完成用户目标 |
| Tool correctness | 工具选择和参数是否正确 |
| Grounding | 是否基于证据而非猜测 |
| Efficiency | 工具调用次数、耗时、成本 |
| Safety | 是否越权或造成危险副作用 |
| Recoverability | 错误后是否能诊断并恢复 |
Agent评估最好使用真实任务集，而不是只做单轮问答集。
9. 常见失败模式
| 失败 | 表现 | 对策 |
|---|---|---|
| 计划漂移 | 做着做着偏离目标 | 明确验收清单，定期对齐目标 |
| 工具误用 | 参数错、路径错、权限错 | schema、dry-run、结果检查 |
| 观察不足 | 不看工具输出就继续 | 强制观察-判断循环 |
| 过度拆分 | 多Agent成本高且互相等待 | 只在边界清晰时拆 |
| 幻觉执行 | 编造文件/API状态 | 所有外部状态用工具验证 |
10. 工程落地清单
- 定义任务边界和不可做事项。
- 给工具设计最小权限schema。
- 建立日志和审计。
- 建立RAG知识版本管理。
- 为高风险操作增加确认。
- 用真实任务集评估Agent成功率。
- 对失败案例做回归集。
11. 参考资料
- ReAct: Synergizing Reasoning and Acting in Language Models.
- Toolformer: Language Models Can Teach Themselves to Use Tools.
- Retrieval-Augmented Generation for Knowledge-Intensive NLP Tasks.
- Reflexion: Language Agents with Verbal Reinforcement Learning.