Java 转 Agent 开发之路（一）：先看懂 Agent 系统的五块拼图

系列定位：记录 Java 工程师转向 Agent 开发的学习与实践路径。  
本篇目标：建立 Agent 系统整体架构认知，理解五个核心模块及其协作关系。  
目标读者：有 Java 后端基础，想进入 AI Agent / LLM 应用开发的工程师。

一、开篇：为什么 Java 工程师要重新理解“系统架构”

写作要点

1. 从 Java 后端视角切入：
      - 我们熟悉 Controller、Service、DAO、消息队列、缓存、数据库。
      - 但 Agent 系统不是传统“请求-响应”流程，而是“推理-决策-行动-观察”的循环。
2. 提出核心问题：
      - LLM 不只是一个 API，它更像系统的大脑。
      - Agent 不是“调用一次大模型”，而是让模型在规划、工具、记忆和框架支撑下完成任务。
3. 本篇主线：
      - 用五块拼图理解 Agent：模型、规划、工具、记忆、编排。
4. 给读者一个预期：
      - 第一篇不写复杂代码，先建立架构地图。
      - 后续文章再逐个拆解，并用 Java/Spring 生态做类比和实践。

可插入内容

一张总览图：

用户目标
   ↓
Orchestration 编排框架
   ↓
LLM 模型：推理与决策
   ↓
Planning 规划：拆解、反思、修正
   ↓
Tools 工具：搜索、代码执行、API、数据库
   ↓
Memory 记忆：短期上下文 + 长期向量库
   ↓
观察结果，进入下一轮循环

二、核心认知：Agent 不是“更长的 Prompt”，而是可运行的系统

写作要点

1. 普通 LLM 调用：
      - 输入 Prompt → 输出文本。
2. Agent 系统：
      - 输入目标 → 推理 → 规划 → 调工具 → 观察结果 → 记忆更新 → 继续推理。
3. 用 Java 类比：
      - LLM 像“会推理的 Service”。
      - Planning 像“任务调度与工作流引擎”。
      - Tools 像“外部系统适配层 / Client / DAO”。
      - Memory 像“上下文缓存 + 检索库”。
      - Orchestration 像“Spring 容器 + 流程编排 + 运行时”。
4. 强调：
      - Agent 的难点不只是模型能力，而是工程化：状态、工具调用、错误处理、可观测性、成本和安全。

三、五块拼图逐一拆解

1. 模型 LLM：负责推理和决策，是整个系统的大脑

本节要点

• LLM 在 Agent 中的职责：
    - 理解用户目标。
    - 判断下一步做什么。
    - 选择是否调用工具。
    - 根据工具结果继续推理。
    - 生成最终答复。
• Java 开发者理解方式：
    - 不要把 LLM 当普通远程 API，而要把它当“非确定性决策组件”。
    - 它像 Service，但输出不稳定，需要约束、校验和兜底。
• 工程关注点：
    - 模型选型：通用模型、代码模型、小模型、私有化模型。
    - Prompt / Message 结构：System、User、Assistant、Tool。
    - 温度、上下文长度、成本、延迟。
    - 结构化输出：JSON Schema、函数调用、工具调用协议。
• 常见误区：
    - 以为什么都靠 Prompt 就能解决。
    - 忽略模型不确定性，缺少校验和重试。
• 本篇只讲职责，不展开模型接入代码。

可插入 Java 类比

LLM ≈ 一个具备推理能力但输出不完全确定的远程 Service
Agent Runtime ≈ 调用该 Service 并管理状态的应用程序

2. 规划 Planning：任务拆解、反思、自我修正

本节要点

• Planning 解决什么问题：
    - 复杂任务不能一步完成，需要拆成子任务。
    - 执行过程中可能失败，需要反思和修正。
• 三个关键词：
    - 任务拆解：把“做一个功能”拆成查询资料、设计方案、生成代码、测试验证。
    - 反思：检查结果是否满足目标。
    - 自我修正：发现错误后调整计划或重新调用工具。
• 常见模式：
    - ReAct：Reason + Act，推理与行动交替。
    - Plan-and-Execute：先计划，再执行。
    - Reflection：执行后反思改进。
• Java 类比：
    - 像工作流引擎、状态机、任务调度器。
    - 但计划不是完全静态的，而是由模型动态生成和调整。
• 工程关注点：
    - 最大循环次数，防止死循环。
    - 计划可观测：记录每一步计划、动作、观察结果。
    - 失败重试与人工介入。
• 常见误区：
    - 让模型无限反思，导致成本和延迟失控。
    - 没有终止条件。

3. 工具 Tools：代码执行器、搜索引擎、内部 API、数据库操作等

本节要点

• Tools 是 Agent 的“手脚”，让模型能影响外部世界或获取外部信息。
• 常见工具类型：
    - 代码执行器：运行代码、测试、脚本。
    - 搜索引擎：获取实时信息。
    - 内部 API：调用公司业务系统。
    - 数据库操作：查询、写入、校验数据。
• 工具调用的本质：
    - 模型输出工具调用意图。
    - 编排框架解析并执行。
    - 执行结果回传给模型。
• Java 开发者优势：
    - 写 API Client、参数校验、权限控制、事务、日志、限流本来就是强项。
• 工程关注点：
    - 工具描述要清晰：名称、用途、参数、返回结构。
    - 参数校验与权限控制。
    - 超时、重试、幂等、审计。
    - 高风险工具需要人工确认。
• 常见误区：
    - 工具太多导致模型选择困难。
    - 工具返回结果太长，污染上下文。
    - 没有权限边界，让模型直接操作生产库。

可插入示例

工具：queryOrderStatus
参数：orderId
返回：订单状态、更新时间
Java 映射：OrderClient.queryStatus(orderId)

4. 记忆 Memory：短期记忆和长期记忆

本节要点

• 为什么需要记忆：
    - 模型本身无状态，每次调用都要携带必要上下文。
    - 长任务需要记住历史步骤、用户偏好、工具结果。
• 短期记忆：
    - 当前会话上下文窗口。
    - 包括用户消息、模型回复、工具调用结果。
    - 类似 HttpSession / ThreadLocal / 请求上下文，但生命周期和容量不同。
• 长期记忆：
    - 向量数据库、文档库、知识库。
    - 通过 Embedding 检索相关内容再注入上下文。
    - 适合企业知识、历史案例、用户偏好。
• Java 类比：
    - 短期记忆像缓存和会话上下文。
    - 长期记忆像全文检索/向量检索服务，类似 Elasticsearch 的语义检索升级版。
• 工程关注点：
    - 上下文裁剪与摘要。
    - 记忆写入策略：什么值得记。
    - 检索质量与权限过滤。
    - 隐私与数据安全。
• 常见误区：
    - 把所有历史都塞进上下文。
    - 以为什么都能靠向量库解决。

5. 编排框架 Orchestration：承接上述模块，让它跑起来

本节要点

• Orchestration 是 Agent 的运行时和骨架。
• 它负责：
    - 组织 Prompt 和消息。
    - 调用 LLM。
    - 解析模型输出。
    - 执行工具调用。
    - 管理记忆读写。
    - 控制规划循环。
    - 处理异常、重试、超时、日志和追踪。
• 没有编排框架会怎样：
    - 代码散落，状态难管理，工具调用难追踪，循环难终止。
• Java 类比：
    - 像 Spring 容器 + 工作流引擎 + 状态机 + 网关的组合体。
• 常见框架认知：
    - LangChain / LangGraph、LlamaIndex、Semantic Kernel、Spring AI 等。
    - 本篇不比较框架优劣，只说明其职责。
• 工程关注点：
    - 可观测性：每一步输入输出、耗时、Token 成本。
    - 可测试性：Mock LLM 和工具。
    - 可扩展性：工具注册、模型切换、记忆后端替换。
    - 安全与权限。

四、把五块拼图串起来：一个最小 Agent 闭环

写作要点

用一个简单例子串起来，例如：“帮我查询订单并生成售后处理建议”。

流程：

1. 用户提出目标。
2. Orchestration 组装上下文并调用 LLM。
3. LLM 判断需要查询订单。
4. Planning 决定先查订单，再查售后政策。
5. Tools 调用订单 API 和知识库检索。
6. Memory 保存工具结果和关键结论。
7. LLM 根据结果反思是否信息足够。
8. 生成最终建议。
9. Orchestration 记录日志、成本和结果。

可插入表格

五、Java 工程师转 Agent 开发的优势与坑

优势

• 工程化能力强：接口设计、异常处理、日志、权限、事务。
• Spring 生态适合做工具适配层和企业 API 集成。
• 对稳定性和可维护性敏感，这正是 Agent 落地需要的。

需要补的课

• Prompt 与上下文工程。
• 模型不确定性下的系统设计。
• 向量检索与 Embedding 基础。
• Agent 循环、工具调用协议和评测。
• 成本、延迟、安全与可观测性。

常见坑

• 把 Agent 当普通接口开发。
• 工具权限过大。
• 没有终止条件和预算控制。
• 没有评测集，只靠感觉调 Prompt。
• 忽略日志和调用链追踪。

六、总结

• Agent 系统由五块拼图组成：
    - LLM 是大脑。
    - Planning 是思考与修正机制。
    - Tools 是手脚。
    - Memory 是记忆。
    - Orchestration 是骨架和运行时。
• 对 Java 工程师来说，转 Agent 开发不是丢掉后端能力，而是把工程能力迁移到新架构里。