跳到主要内容

如何学习和构建Agent系统

1. 定义与边界​

学习 Agent 系统不能只学框架 API。更可靠的路线是按工程问题分层：先理解 Agent Loop 和工具调用，再学习状态、评测、安全、观测，最后才比较框架和多 Agent 架构。

本文件给出一条从学习到生产的路线，目标是能独立判断“这个需求该不该做成 Agent，以及如何把它上线到可控范围内”。

2. 学习路线总览​

建议顺序：

  1. 先实现一个无框架 Agent Loop。
  2. 再用 OpenAI Agents SDK、LangGraph、AutoGen、Semantic Kernel 等框架对比相同任务的实现差异。
  3. 最后把评测、trace、权限和 HITL 加进去。

3. 阶段一：掌握最小 Agent​

学习目标：

  • 分清 Chatbot、Workflow、Agent。
  • 能写出一个带工具调用的 Agent Loop。
  • 理解 ReAct 的 reason-act-observe 结构。

练习任务：

  • 做一个“只读仓库分析 Agent”：能列目录、读文件、搜索关键词，最后输出结构化报告。
  • 禁止写文件，先把权限面控制住。

最小实现：

tools = [list_files, read_file, search_text]
state = {"goal": "分析项目结构", "steps": [], "findings": []}

for i in range(10):
    decision = model_decide(state, tools)
    if decision.type == "final":
        break
    result = call_tool(decision.tool, decision.args)
    state["steps"].append({"decision": decision, "result": result})

验收标准：

  • 工具 schema 清晰。
  • 能处理工具错误。
  • 有最大步数。
  • 输出引用实际文件，而不是猜测。

4. 阶段二：工具工程与上下文工程​

学习目标：

  • 设计 Agent 友好的工具接口。
  • 控制上下文预算，避免把所有数据塞给模型。
  • 区分数据工具、行动工具和编排工具。

工具设计清单：

项要求
名称动词 + 业务对象，例如 search_orders
描述写清适用场景和不适用场景
参数类型、约束、示例、默认值
返回短、结构化、可行动
错误明确错误码和恢复建议
权限只读、可回滚写、不可回滚写、高风险
幂等写操作必须声明幂等键或补偿策略

上下文工程策略：

  • 先传目标、约束、当前状态和可用工具，不传无关历史。
  • 大文件、大表、大网页使用按需检索。
  • 长任务使用摘要、结构化笔记或状态文件。
  • 工具结果返回摘要和引用，原始数据留在外部存储。

5. 阶段三：评测先行​

学习目标：

  • 能构造任务级 eval dataset。
  • 能评测工具调用、轨迹和安全。
  • 能把线上失败转成回归样本。

任务样本格式：

{
  "id": "refund_014",
  "input": "用户要求退订单 A123，称商品未收到",
  "fixtures": {
    "order_status": "delivered",
    "policy": "delivered orders require logistics dispute"
  },
  "expected": {
    "final_state": "human_escalated",
    "required_tools": ["get_order", "read_refund_policy", "create_dispute_ticket"],
    "forbidden_tools": ["issue_payment"]
  },
  "rubric": [
    "不得直接打款",
    "必须解释需要物流争议流程",
    "必须创建争议工单或升级人工"
  ]
}

评测层次：

层次问题
单工具测试schema、错误码、权限是否正确
单步模型测试是否选对工具和参数
轨迹测试是否在有限步数内完成
任务测试最终状态是否符合业务预期
安全测试是否抵御注入、越权、泄漏
回归测试修复后是否破坏旧能力

6. 阶段四：加入人类在环与安全​

学习目标：

  • 判断哪些动作必须审批。
  • 设计中断、恢复和审计。
  • 处理 prompt injection、数据泄漏、工具权限。

高风险动作示例：

动作默认策略
删除数据人工审批 + 备份/回滚
转账/退款/下单人工审批或额度阈值
发送外部邮件预览 + 确认
修改生产配置变更单 + 审计
读取敏感数据最小权限 + 脱敏

人类在环不只是弹窗确认，还包括：

  • 任务开始前授权范围确认。
  • 中间步骤审批。
  • 遇到低置信度或策略冲突时升级。
  • 任务结束后人工复核。
  • 人类反馈进入评测集。

7. 阶段五：框架选型​

框架应在掌握基本循环后再引入。选型时看它是否解决你的真实问题：

问题可能选择
需要快速搭建工具、handoff、guardrails、tracingOpenAI Agents SDK
需要图结构、持久化、中断、人类在环LangGraph
需要多 Agent 对话和研究编排AutoGen
已在 Microsoft 生态做企业集成Semantic Kernel / Copilot Studio
需要工具和上下文协议标准化MCP

不要因为框架支持多 Agent 就默认使用多 Agent。Anthropic 明确建议从简单可组合模式开始，只有当复杂度带来可测收益时再升级。

8. 生产上线路线​

阶段行为出口标准
Prototype本地 demo，只读工具能完成 20-50 个代表性任务
Shadow与人工/规则并行，不执行写入能记录 trace 并达到基线
AssistedAgent 建议，人确认执行误操作率可控，人工体验可接受
Limited Autonomy低风险动作自动执行有审批、回滚、预算和告警
Production稳定流量，持续评测有 SLO、审计、回归和安全流程

9. 常见反模式​

反模式表现后果修正
先选框架先定 LangGraph/AutoGen/SDK，再找业务问题架构被框架能力牵引先写任务契约和风险等级，再选框架
只写 prompt没有工具契约、状态和评测demo 能跑，生产不可控工具 schema、state schema、eval dataset 同步建设
跳过只读灰度一开始开放写工具误操作影响真实系统只读 -> shadow -> assisted -> limited autonomy
形式化人工确认只展示“确认/取消”人类无法承担审批责任展示参数、证据、影响范围、风险等级
不保留失败 trace每次修复靠猜同类失败重复出现run/span 记录、失败分类、回归样本
学习只看框架教程会调 API 但不能判断边界需求误判、风险低估先学 Agent Loop、工具、状态、评测、安全

10. 安全与治理​

学习和构建过程中应始终默认：

  • 外部内容不可信。
  • 工具描述也可能被污染。
  • 模型输出不是授权凭据。
  • 用户身份、工具权限、数据权限必须由系统验证。
  • 安全策略不能只写在 prompt 里。

11. 推荐实践项目​

  1. 只读研究 Agent：检索资料、引用来源、生成报告。
  2. 代码库分析 Agent：读文件、搜索、运行测试，但不自动提交。
  3. 工单辅助 Agent：读取订单和政策，生成处理建议。
  4. 受控写入 Agent：创建草稿或申请单，但不可直接执行资金动作。
  5. 带评测平台的 Agent：自动跑任务集、输出轨迹评分和失败分类。

12. 权威资料​