[AI工程] Spring AI 第十五篇(Spring AI Agent Utils): Claude Code 的那套工具箱，被人在 Java 里重写了一遍

原创

已于 2026-09-20 16:13:29 修改 · 292 阅读

话题

#开学季·九月创作之星博客挑战赛

于 2026-09-20 11:30:00 首次发布

💡 这两年用惯了 AI 编程工具的人会有一种共识：真正让 Agent 好用的不是模型，是它手里那套工具——能读文件、能跑命令、能 grep、能把复杂任务拆成 todo、能在需要时反问一句。

问题来了：这些能力在 Claude Code、Qoder 这类工具里是内置的，但当你用自己的 Java 服务做一个"能干活"的 Agent 时，全得从零写：进程管理、超时、输出截断、路径越权防护、子智能体委派、跨会话记忆……写到最后你会发现自己在重造一个小型 IDE。

Spring AI Agent Utils 就是冲这件事来的：它是 Spring AI 社区（org.springaicommunity）下的一个 incubating 项目，把 Claude Code 的核心工具与 Agent Skills 机制用 Spring AI 重写了一遍，作为一组 @Tool 直接挂到 ChatClient.defaultTools(...) 上。注：写这篇时最新版本是 0.12.0（2026-08-30 发布），Apache 2.0 许可，仍处于孵化阶段。

这一篇按"它有什么 → 怎么接 → 哪三样组合才真正产生 Agentic 行为 → 安全边界在哪 → 什么时候该用它"来盘，顺便和第十五篇讲的 Agent 五种模式、以及 Spring AI Alibaba 的 Agent Framework 做个分工对照。

下面开启本篇： [AI工程] 玩转 Spring AI Agent Utils：Claude Code 的那套工具箱，被人在 Java 里重写了一遍
在这里插入图片描述

1. 先说清楚它是什么、不是什么

一句话：把 Claude Code 的工具面板，翻译成 Spring AI 的工具 Bean。

1.1 基本盘

项	内容
坐标	`org.springaicommunity:spring-ai-agent-utils`（有 BOM：`spring-ai-agent-utils-bom`）
当前版本	0.12.0（2026-08-30 发布；0.1.1 → 0.12.0 迭代节奏很快）
定位	用 Spring AI 重实现 Claude Code 的工具与技能机制，给 Java 侧 Agentic 工作流用
环境要求	Java 17+ / Spring Boot 3.x 或 4.x / Spring AI 2.0.0+ / Maven 3.6+
许可 & 状态	Apache 2.0，spring-ai-community 下 incubating
文档	官方文档站

一个小提醒：README 的 Quick Start 里有句 “You need Spring AI version `` or later”，版本号是个空占位（写这篇时如此）。以 Requirements 段写的 2.0.0 or later 为准。

1.2 模块划分

spring-ai-agent-utils-common     子智能体 SPI：SubagentDefinition / SubagentResolver / SubagentExecutor / SubagentType
spring-ai-agent-utils            核心库：工具、Advisor、技能、Claude 子智能体实现
spring-ai-agent-utils-a2a        A2A 协议子智能体（远程 Agent 编排）
spring-ai-agent-utils-bom        统一版本管理
examples/                        9 个可运行 Demo（code-agent / ask-user-question / skills / subagent / subagent-a2a / todo / memory x3）

`Q1：它和 Spring AI 官方是什么关系？`

社区项目，不在 org.springframework.ai 坐标下，也不承诺跟随官方发布节奏。这决定了使用姿势：把它当"高质量参考实现 + 可用的积木"，而不是平台依赖。0.x 阶段 API 会变，锁版本并在升级时过一遍回归。

`Q2：和 Anthropic 官方 SDK 有什么区别？`

这里没有任何 Claude 专有协议——工具是普通 Spring AI @Tool，模型可以是 Spring AI Alibaba 接的千问、DeepSeek、OpenAI、Gemini，任选。它复刻的是 Claude Code 的能力形状（工具集 + 提示词约定），不是它的运行时。

2. 工具体系全景

分五组看，一次记住。

2.1 核心工具（任何 Agentic 行为的地基）

工具	对应 Claude Code 能力	关键细节（文档实测）	风险面
`AgentEnvironment`	动态上下文注入	把运行时环境、git 状态以 param 形式塞进 system prompt	泄露仓库信息
`FileSystemTools`	Read / Write / Edit	支持行区间与分页、精确字符串替换、行长截断（2000 字符）、自动建父目录；默认全盘可访问，可用 `allowedDirectory(...)` 收口	覆盖文件
`ShellTools`	Bash / BashOutput	同步默认超时 2 分钟（上限 10 分钟）、后台执行返回 `bash_id`、stdout/stderr 分离、正则过滤输出、输出超 30000 字符截断	命令执行
`GrepTool`	Grep	纯 Java 实现，支持正则、glob 过滤、多种输出模式	大仓库扫全量
`GlobTool`	Glob	按文件名模式快速查找	低
`SmartWebFetchTool`	WebFetch	AI 摘要 + 缓存，需要传一个 ChatClient 做摘要	二阶模型成本
`BraveWebSearchTool` / `BraveWebFetchTool`	WebSearch	走 Brave 搜索，支持域名过滤	需要 API Key

2.2 另外四组

组	工具	干什么	值得注意
用户反馈	`AskUserQuestionTool`	执行中途向用户提澄清问题	每题 2~4 个选项、单次 1~10 题、`header` 最多 12 字符、支持单选/多选与自由文本；只能主 Agent 用，子智能体不能与用户交互
技能	`SkillsTool`	Markdown + YAML front-matter 定义可复用能力包	启动时只加载 name/description，命中语义才加载全文（渐进披露）；可从目录、classpath、依赖 JAR 加载
长期记忆	`AutoMemoryTools` / `AutoMemoryToolsAdvisor`	跨会话的文件型记忆	六个操作（`MemoryView` / `MemoryCreate` / `MemoryStrReplace` / `MemoryInsert` / `MemoryDelete` / `MemoryRename`）；沙箱目录；`MEMORY.md` 索引；自带配套 system prompt
任务编排	`TodoWriteTool`、`TaskTool`	显式计划 + 子智能体委派	Todo 有一条硬规则：同一时刻只能有一个 `in_progress`；Task 支持多模型路由与可插拔后端

一句话理解：核心工具给手，Skills 给知识，Memory 给记性，Task/Todo 给组织度——四样凑齐才像个能干活的 Agent。

3. 十分钟接一个能干活的最小 Agent

代码基于 README 的 Quick Start 改写，去掉了演示噪音。

3.1 依赖

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.springaicommunity</groupId>
            <artifactId>spring-ai-agent-utils-bom</artifactId