AI Agent 技术全景：规划、工具与工程实践

1. 一句话总结

AI Agent 是一个由大模型驱动、能够理解目标、拆解任务、调用工具、接收环境反馈并持续迭代执行的智能系统。

它和普通聊天机器人的区别在于：

对比项	普通 LLM 应用	AI Agent
核心能力	根据输入直接生成回答	根据目标规划、决策、调用工具并执行
执行方式	一问一答	多轮循环：思考 → 行动 → 观察 → 再决策
工具使用	可选增强能力	核心能力之一
记忆能力	通常依赖上下文窗口	可结合短期记忆、长期记忆、外部存储
适用场景	FAQ、摘要、翻译、普通问答	代码生成、投研分析、数据查询、自动化流程、复杂决策

---

2. Agent 的核心组成

Agent 的关键能力可归纳为三类：规划、记忆、工具使用。结合联网资料，可以扩展为以下 6 个核心模块：

模块	作用	工程落地方式
Planning 规划	将复杂目标拆解为可执行子任务	ReAct、Plan-and-Execute、LangGraph StateGraph
Memory 记忆	保存上下文、历史经验、用户偏好、任务状态	Redis、MySQL、PostgreSQL、向量库、LangGraph Checkpoint
Tool Use 工具调用	调用外部 API、数据库、搜索、代码执行器等	Function Calling、MCP、LangChain Tool、OpenAI Tools
Reflection 反思	对执行结果进行复盘，生成更高层次结论	轨迹日志、Evaluator、LLM 自检
Environment 环境	Agent 观察与影响的外部系统	浏览器、文件系统、数据库、业务系统、第三方服务
Guardrails 防护栏	限制权限、校验输入输出、防止越权和错误累积	白名单、人工审批、权限隔离、审计日志、沙盒执行

---

3. Agent 的三种典型架构

3.1 反应式 Agent：Reactive Agent

定位：快速决策的"直觉型"智能体。

反应式 Agent 主要根据当前输入和环境反馈立即选择行动，不做复杂长期规划。

工作流程

感知输入 → 判断当前状态 → 选择工具/动作 → 执行 → 观察结果 → 再次判断

优点

• 响应速度快。
• 实现简单。
• 适合规则明确、链路较短的任务。
• 易于验证和调试。

局限

• 缺少长期规划能力。
• 容易短视，只优化当前步骤。
• 对复杂多步骤任务支持较弱。
• 如果工具选择不准，容易陷入无效循环。

适合场景

场景	示例
规则问答	私募基金合格投资者标准查询
实时查询	今日指数、账户余额、订单状态
工具路由	用户问 A 调用搜索工具，问 B 调用数据库工具
简单客服	FAQ、政策解释、业务规则查询

---

3.2 深思熟虑 Agent：Deliberative Agent

定位：面向复杂目标的"规划型"智能体。

深思熟虑 Agent 会先构建内部模型，再进行多方案推理和决策，最后生成结果。

工作流程

感知 → 建模 → 推理 → 决策 → 生成报告/执行方案

优点

• 适合多步骤复杂任务。
• 可以优化长期目标。
• 能生成多个候选方案并比较优劣。
• 推理过程更透明。

局限

• 成本更高。
• 延迟更长。
• 对提示词、状态设计、错误恢复要求更高。
• 如果缺少事实数据或评估机制，容易生成看似合理但不可靠的结论。

适合场景

场景	示例
投研分析	新能源汽车行业投资机会研究
复杂报告生成	市场分析、竞品分析、可研报告
代码重构规划	多文件代码理解、修改计划、测试计划
数据分析	收集数据 → 建模 → 生成洞察 → 输出建议

---

3.3 混合式 Agent：Hybrid Agent

定位：兼顾"快速响应"和"深度规划"的综合型智能体。

混合式 Agent 一般由三层组成：

层级	作用
底层：反应式层	处理紧急、简单、时效性强的问题
中层：协调层	判断任务类型、优先级、处理模式
顶层：深思熟虑层	处理复杂分析、长期规划、多方案推理

典型决策逻辑

用户输入
  ↓
协调层判断任务类型
  ↓
如果是紧急/简单问题 → Reactive 快速处理
如果是复杂/分析问题 → Deliberative 深度处理
  ↓
统一生成最终响应

适合场景

场景	示例
投顾助手	查询指数走反应式，资产配置建议走深思熟虑
企业智能客服	简单 FAQ 直接答，复杂工单进入多步骤流程
AI Coding	简单报错直接修，复杂架构改造先规划再执行
运维助手	简单状态查询直接调用工具，故障诊断进入推理流程

---

4. Agent 框架对比

主流 Agent 框架对比如下：

工具/框架	核心定位	适合场景	优点	注意点
LangChain	LLM 应用开发框架	RAG、工具调用、Chain、Agent	生态成熟、工具多	抽象层较多，复杂项目需控制架构
LangGraph	有状态 Agent 编排框架	多步骤、多分支、循环、Human-in-the-loop	状态图清晰、支持持久化、适合复杂 Agent	需要认真设计 State 和边
Qwen-Agent	通义千问 Agent 框架	Qwen 模型、工具调用、RAG、Code Interpreter、MCP	国内生态友好，适合通义千问	生产需关注模型兼容和服务稳定性
Coze	无代码/低代码 Bot 平台	快速搭建机器人、知识库助手	上手快、插件生态丰富	深度定制和私有化能力受平台约束
Dify	开源 LLM 应用平台	企业内部 LLM 应用、工作流、RAG	可私有化、API 友好	复杂 Agent 仍需额外工程化
OpenAI Agents SDK	Agent 应用开发 SDK	工具、handoff、guardrails、trace	官方 SDK，适合构建多 Agent 应用	需结合业务权限和审计设计
MCP	工具/资源/上下文接入协议	统一连接文件、数据库、搜索、业务系统	类似 AI 应用的统一外设协议	工具描述、权限、沙盒和安全治理非常关键

---

5. LangGraph 落地步骤

LangGraph 的推荐落地步骤如下：

1. 定义状态：TypedDict / Pydantic
2. 创建 StateGraph
3. 定义节点函数
4. 添加节点 add_node()
5. 设置入口 set_entry_point()
6. 添加边 add_edge() / add_conditional_edges()
7. 编译工作流 compile()
8. 执行工作流 invoke()

推荐工程结构

agent-project/
├── app/
│   ├── states/
│   │   └── wealth_advisor_state.py
│   ├── nodes/
│   │   ├── assess_query.py
│   │   ├── reactive_processing.py
│   │   ├── collect_data.py
│   │   ├── analyze_data.py
│   │   └── generate_recommendations.py
│   ├── tools/
│   │   ├── market_tools.py
│   │   ├── portfolio_tools.py
│   │   └── news_tools.py
│   ├── prompts/
│   │   ├── assess_prompt.py
│   │   └── advisor_prompt.py
│   ├── workflow/
│   │   └── graph.py
│   └── main.py
├── tests/
├── requirements.txt
└── README.md

---

6. 工具开发：Function / MCP 的设计原则

Agent 的能力上限很大程度取决于工具质量。工具不是简单封装 API，而是要让模型能理解、会选择、能正确传参、能安全执行。

6.1 一个好工具必须具备的要素

要素	说明
明确名称	工具名要表达动作和业务对象，如 query_order_status
清晰描述	说明什么时候用、什么时候不用
严格入参	使用 JSON Schema / Pydantic 定义类型和约束
稳定输出	返回结构化结果，避免自由文本
错误语义	明确区分参数错误、权限错误、业务不存在、系统异常
幂等性	写操作必须支持 requestId / traceId / idempotencyKey
权限控制	用户只能调用自己有权限的业务能力
可观测性	记录调用日志、耗时、入参摘要、返回状态
可测试性	每个工具都有单元测试、集成测试、异常测试

---

6.2 工具描述模板

{
  "name": "query_portfolio_allocation",
  "description": "查询指定客户当前投资组合的资产配置比例。适用于用户询问自己的股票、债券、现金、另类投资等资产占比时。不要用于生成投资建议。",
  "input_schema": {
    "type": "object",
    "properties": {
      "customer_id": {
        "type": "string",
        "description": "客户唯一编号"
      }
    },
    "required": ["customer_id"]
  }
}

---

6.3 工具返回值模板

{
  "success": true,
  "code": "SUCCESS",
  "message": "查询成功",
  "data": {
    "stock_ratio": 0.4,
    "bond_ratio": 0.3,
    "cash_ratio": 0.1,
    "alternative_ratio": 0.2
  },
  "trace_id": "20260618-agent-0001"
}

---

7. 企业级 Agent 的推荐架构

7.1 总体架构

用户入口
  ↓
权限认证 / 用户画像
  ↓
意图识别 / 任务分类
  ↓
协调层 Router
  ├── 简单任务 → Reactive Agent
  ├── 复杂任务 → Deliberative Agent / LangGraph
  └── 高风险任务 → Human Approval
  ↓
工具调用层 Function / MCP
  ↓
业务系统 / 数据库 / 搜索 / 文件系统 / 第三方 API
  ↓
结果校验 / 风控 / 审计
  ↓
最终响应

---

7.2 Java / Spring Boot 落地映射

如果你要把这个思路落到 Java 后端，可以这样拆：

Agent 概念	Java/Spring Boot 对应
Tool	Spring Service / Feign Client / Mapper
Tool Schema	DTO + Bean Validation
Agent State	状态表 + Redis + TraceContext
Workflow	状态机 / Flow Engine / LangGraph 外部服务
Memory	MySQL + Redis + 向量库
Guardrails	AOP 权限校验、参数校验、审计日志
Human-in-the-loop	审批流 / 工单流
Observability	Logback + TraceId + Prometheus + Grafana

---

8. 生产环境最佳实践

8.1 不要为所有任务都构建 Agent

优先判断：

如果任务路径固定 → 用传统工作流
如果任务简单可规则化 → 用函数/规则引擎
如果任务复杂、开放、步骤不可预测 → 才考虑 Agent

---

8.2 从简单方案开始

推荐演进路线：

Prompt
  ↓
Prompt + RAG
  ↓
Prompt + Tool
  ↓
Reactive Agent
  ↓
LangGraph Workflow
  ↓
Hybrid Agent
  ↓
Multi-Agent

不要一开始就上多 Agent，否则调试、成本、稳定性都会变复杂。

---

8.3 工具优先，而不是模型优先

Agent 项目成败的关键不是"模型有多强"，而是：

1. 工具是否设计清楚。
2. 工具是否安全。
3. 工具返回是否稳定。
4. 工具描述是否能让模型正确选择。
5. 工具是否有测试和审计。

---

8.4 必须做轨迹日志

建议每次 Agent 执行都记录：

字段	说明
trace_id	单次执行链路编号
user_id	用户编号
task_type	任务类型
selected_mode	reactive / deliberative / hybrid
model_name	使用的模型
tool_calls	工具调用列表
input_summary	输入摘要，避免记录敏感全文
output_summary	输出摘要
token_usage	Token 消耗
latency_ms	耗时
error_message	错误信息
human_approved	是否人工审批

---

8.5 高风险动作必须加审批

以下动作不要让 Agent 直接执行：

• 转账。
• 下单。
• 删除数据。
• 修改生产配置。
• 发送正式通知。
• 批量导出敏感数据。
• 调用付费 API。
• 对外发送邮件或消息。

推荐策略：

Agent 生成计划 → 系统展示计划 → 用户/管理员确认 → 执行工具 → 记录审计

---

9. 常见错误与规避

错误	后果	规避方式
工具描述太模糊	Agent 选错工具	写清楚使用场景和禁用场景
工具返回自由文本	后续节点难解析	返回 JSON 结构
没有状态管理	多步任务容易断链	使用 StateGraph / 状态表
没有错误恢复	一次失败导致整体失败	节点级 try-catch + fallback
没有权限控制	越权调用业务系统	工具层鉴权
没有审计日志	事故不可追踪	trace_id + tool_call_log
所有请求都走 Agent	成本高、延迟高	简单任务走工作流/规则
缺少知识边界	容易胡编	明确"未检索到依据"