项目地址：GitHub ｜ Gitee
当前进度：RL 轨迹产出层开发中

Java 工程师学 AI Agent 的三道墙

我想学 AI Agent。不是跟风，是真的觉得这是当前最值得关注的技术方向。

但学起来发现，到处是墙。

墙一：开源框架，不是 Python 就是 TypeScript

AutoGPT、CrewAI、LangChain、Semantic Kernel……你打开 GitHub 一搜，主流的 Agent 框架和产品，基本全是 Python 或 TypeScript 技术栈。

我照着教程写了一堆 Demo——调用 API、接工具、跑对话——跑是跑通了，但始终找不到状态。为什么？因为我在用一门我不够熟的语言，去理解一个我还不懂的领域。双重陌生叠加，每一步都是照猫画虎。

Demo 跑完了，但心里没底：这个工具调用的异常处理在生产环境会怎样？记忆模块的并发安全怎么保证？这些 Demo 都不会告诉你。

墙二：网上的教程，Agent 部分讲得很浅

你搜"AI Agent 教程"，大部分路线是这样的：Python 基础 → PyTorch → Transformer 原理 → RAG → 微调 → …… → Agent。

Agent 排在最后，寥寥几页，讲个 ReAct 循环就结束了。

但 Agent 恰恰是和工程实践结合最紧密的部分——工具调用的治理、执行的隔离与恢复、记忆的生命周期、Token 的预算控制、安全边界——这些才是 Agent 在生产环境能不能用的关键。而这些，教程几乎不提。

墙三：我的积累怎么迁移？

我做 Java 很多车了。分布式系统、并发模型、接口抽象、工程规范——这些是我吃饭的家伙。

但 Agent 的主流生态在 Python 那边。我要从零学一套技术栈，然后从零理解 Agent 架构？那我的积累呢？这么多年对 Java 生态的理解、对企业级工程的经验，就全部清零了？

这不是学习效率的问题，是路径选择的问题。

我的解法：造轮子

想清楚之后，我做了一个决定：用 Java，从零手写一个 Agent Runtime。

不是为了做另一个框架——是为了通过造轮子来理解轮子。

为什么造轮子有效？因为你必须为每一个设计决策负责。用别人的框架，工具调用的异常处理是"别人的事"；自己写，就是你的事。你必须想清楚：模型超时了怎么办？工具执行挂了怎么恢复？记忆在多 Agent 间怎么共享？这些别人教程里一笔带过的地方，才是架构的核心。

13 个阶段后：AI Agent 框架的 6 大基石

走了 13 个阶段之后，我回过头来看，AI Agent 框架真正要关注的，其实就这几件事：

核心关注点	解决的问题	我做的模块
Agent Loop	Agent 怎么思考和行动	agent-core
Tool 调用与治理	工具怎么注册、执行、审计、防注入	agent-core → agent-security
记忆	上下文怎么存、怎么共享、怎么过期	agent-memory
沙箱	不可信代码怎么隔离执行	agent-sandbox
Token 治理	每次调用花了多少 Token、怎么控制预算	agent-core（ModelClient 装饰器链）
安全	权限、审批、注入防护、审计链路	agent-security

其余的——插件热插拔、工作流编排、持久化恢复、调度器、MCP 接入、多 Agent 协作、频道入驻、声明式定义——都是在这六块基石上的延伸。

这个认识，不是看教程看来的，是每一行代码写出来的。

几个踩过的坑和设计决策

模型调用不是发个 HTTP 请求那么简单

第一次写模型调用，就是发请求、拿响应。跑起来没问题——直到模型超时、限流、返回非 JSON、主服务宕机。

后来我把 ModelClient 做成了装饰器链，每一层只管一种故障：

ReActAgentLoop.chat(request)
  → StructuredOutputModelClient  // JSON 验证 + 修正重试
    → FallbackModelClient        // 主模型挂了？降级到备用
      → TimeoutModelClient       // 超时强制中断
        → RetryModelClient       // 瞬时故障自动重试
          → OpenAiModelClient    // 真正的 HTTP 调用

这不是过度设计——这是生产环境必须面对的问题链。

ToolRegistry 和 ToolExecutor 分开，后来救了我三次

Stage 2 时我把"什么工具存在"（Registry）和"如何安全执行"（Executor）分开。当时只是觉得职责不同。

结果 Stage 9 做工具治理时，我在 Executor 上包了一层 GovernedToolExecutor——权限检查、审批、审计、注入净化，全部自动生效，Registry 一行代码没改。

Stage 10 接 MCP，McpToolAdapter 注册到 Registry 后，同样被 GovernedToolExecutor 自动治理。零额外代码。

你在早期做对的设计决策，后面会反复回报你。

沙箱不等于 Docker

很多人提到沙箱就想到 Docker 或 WASM。但 Agent 调用不可信代码的场景，需要的不是"容器级隔离"，而是"可控的隔离级别"：

• ClassLoader 隔离：拦截 File/Runtime/ProcessBuilder/Network/反射，零磁盘 IO
• 内存编译：Java Compiler API 直接在内存里编译执行，不落盘
• 进程隔离：ProcessBuilder + 超时 + 工作目录限制，死循环 2 秒被 kill

不追求绝对安全（那是操作系统的事），追求的是防御纵深。

agent4j：Java 版 AI Agent 框架的定位

学习是一方面，但走到第 13 个阶段，我越来越清楚这个项目最终要沉淀成什么——一个 Java 版的 AI Agent 框架。

不是"学习项目"，是真正能用的框架。

从产品角度：三类场景

场景	为什么 Java 版有优势
Coding Agent	代码审查、重构、CI/CD——企业开发的主战场在 Java，Agent 理应跑在同一个生态里
企业级 Agent	权限、审计、审批链路、Token 预算——Java 工程师对这些概念天然有感觉
酒馆游戏类 Agent	NPC 的记忆、角色一致性、多 Agent 协作——这些是框架能力的试金石

从技术角度：给 RL 反哺

这是我最想做的事——让 Agent 的每一步决策，都变成可训练的数据。

现在的 Agent，调试靠人看日志，优化靠手动改 Prompt。但如果每个 Run 的轨迹（观察→思考→行动→反馈）都能结构化导出，就可以用 RL 或 SFT 来优化 Agent 的策略。

Agent Runtime 不应该只是"跑 Agent 的地方"，还应该是"产出训练数据的地方"。

这是 Stage 14 正在做的事，也是目前社区里很少有人在做的事。

写给同频的人

如果你也是 Java 工程师，也想学 Agent，也写了一堆 Python Demo 找不到状态——

你不是一个人。

Agent 不只是 Python 的事。Java 工程师对企业级问题的直觉——并发、安全、治理、持久化——恰恰是 Agent 从 Demo 走向生产最缺的东西。

我把我整个学习过程开源出来了：

• 🐙 GitHub — 源码 + 所有学习笔记
• 🍎 Gitee — 国内镜像
• 📝 notes/ 目录 — 13 个阶段的完整架构笔记，每个设计决策都有推演过程

如果你在看代码时有任何问题——一个接口为什么这么设计、一个阶段为什么是这个顺序——开 Issue 来聊。

因为 Agent 这门课，最好的学法是：用你最熟的武器，打最硬的仗。

---