Spring AI Agent Utils _ Spring Agent 工具库，用Java开发 Agent 的全套工具集

RR1335

234人浏览 · 2026-04-29 22:01:04

RR1335 · 2026-04-29 22:01:04 发布

The Spring AI Agent Utils library is an open-source project by the Spring AI Community that brings Claude Code-inspired tools and agentic patterns to Java applications. It provides a standardized way to build autonomous agents capable of file manipulation, shell execution, and multi-agent orchestration.

Spring AI Agent Utils库是Spring AI社区的开源项目，它将Claude Code启发的工具和智能体模式引入Java应用程序。该库提供了一种标准化方式来构建具备文件操作、Shell执行和多智能体编排能力的自主智能体。

Below are the primary components and features of the library:

1. Core Toolkits

These utilities allow AI agents to interact with the host system and the web securely:

FileSystemTools: Provides granular control for agents to read, write, and edit files. It supports pagination for large files and "smart edits" to replace specific code blocks without rewriting entire files.
ShellTools: Enables the agent to execute shell commands synchronously or in the background. It includes built-in safety features like timeout controls and output truncation.
Web & Search Tools: Includes the BraveWebSearchTool for live internet searching and the SmartWebFetchTool for fetching and converting web content into AI-readable Markdown.
Grep & Glob Tools: Specialized utilities for fast file pattern matching and code searching within large repositories.

文件系统工具：为智能体提供细粒度控制，支持文件读取、写入和编辑操作。支持大文件分页处理及"智能编辑"功能，可替换特定代码块而无需重写整个文件。

Shell工具：支持智能体同步或后台执行shell命令。内置超时控制和输出截断等安全功能。

网页搜索工具：包含Brave网页搜索工具（支持实时网络检索）和智能网页抓取工具（可将网页内容转换为AI可读的Markdown格式）。

Grep与Glob工具：专用于大型代码库中快速文件模式匹配和代码搜索的实用程序。

2. Agentic Patterns & Workflow Utilities

The library implements high-level patterns to make agents more reliable:

AskUserQuestionTool: A utility that allows an agent to pause execution and ask the user for clarification or missing information before continuing.
TodoWriteTool: Helps agents manage complex tasks by maintaining an explicit, structured task list to prevent them from "forgetting" steps during long-running workflows.
AgentEnvironment: Automatically injects runtime context into system prompts, such as the current operating system, working directory, and Git status.

该库实现了高级模式以提高代理的可靠性：

AskUserQuestionTool：一种实用工具，允许代理暂停执行并向用户询问澄清或缺失信息后再继续。
TodoWriteTool：通过维护明确的结构化任务列表，帮助代理管理复杂任务，防止其在长时间运行的工作流程中"遗忘"步骤。
AgentEnvironment：自动将运行时上下文（如当前操作系统、工作目录和Git状态）注入系统提示中。

3. Agent Skills System

The SkillsTool allows you to define reusable, domain-specific knowledge in Markdown files with YAML front-matter. These skills are dynamically loaded and matched semantically, enabling agents to perform specialized tasks (e.g., "how to deploy this specific microservice") without bloating the initial system prompt.

4. Multi-Agent Orchestration (TaskTools)

The library features a hierarchical sub-agent system that allows a "Main Agent" to delegate tasks to specialized sub-agents:

Built-in Sub-agents: Includes pre-configured sub-agents like Explore (for codebase discovery), Plan (for architectural design), and Bash (for command execution).
Agent-to-Agent (A2A) Protocol: Supports inter-agent communication, allowing local Spring AI agents to collaborate with remote agents over standardized protocols.

工具链接：

https://github.com/spring-ai-community/spring-ai-agent-utils

Detailed Documentation

Module	Description
spring-ai-agent-utils	Core library - tools, skills, Claude subagents, and full API reference
spring-ai-agent-utils-common	Shared subagent SPI (SubagentDefinition, SubagentResolver, SubagentExecutor, SubagentType)
spring-ai-agent-utils-a2a	A2A protocol subagent for remote agent orchestration A2A协议子代理，用于远程代理编排
spring-ai-agent-utils-bom	Bill of Materials for consistent version management across all modules 所有模块统一版本管理的物料清单
Examples	Working demos showcasing different use cases

BOM

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.springaicommunity</groupId>
            <artifactId>spring-ai-agent-utils-bom</artifactId>
            <version>0.7.0</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

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

Configure Agent

@SpringBootApplication
public class Application {

    @Bean
    CommandLineRunner demo(ChatClient.Builder chatClientBuilder,
        @Value("${BRAVE_API_KEY}") String braveApiKey,
        @Value("${agent.skills.paths}") List<Resource> skillPaths,
        @Value("classpath:/prompt/MAIN_AGENT_SYSTEM_PROMPT_V2.md") Resource agentSystemPrompt) {

        return args -> {
            // Configure Task tool with Claude sub-agents
            var taskTool = TaskTool.builder()
                .subagentTypes(ClaudeSubagentType.builder()
                    .chatClientBuilder("default", chatClientBuilder.clone())
                    .skillsResources(skillPaths)
                    .braveApiKey(braveApiKey)
                    .build())
                .build();

            ChatClient chatClient = chatClientBuilder
                // Main agent prompt
                .defaultSystem(p -> p.text(agentSystemPrompt) // system prompt
                    .param(AgentEnvironment.ENVIRONMENT_INFO_KEY, AgentEnvironment.info())
                    .param(AgentEnvironment.GIT_STATUS_KEY, AgentEnvironment.gitStatus())
                    .param(AgentEnvironment.AGENT_MODEL_KEY, "claude-sonnet-4-5-20250929")
                    .param(AgentEnvironment.AGENT_MODEL_KNOWLEDGE_CUTOFF_KEY, "2025-01-01"))

                // Sub-Agents
                .defaultToolCallbacks(taskTool)

                // Skills
                .defaultToolCallbacks(SkillsTool.builder()
                    .addSkillsResources(skillPaths)
                    .build())

                // Core Tools
                .defaultTools(
                    ShellTools.builder().build(),
                    FileSystemTools.builder().build(),
                    GrepTool.builder().build(),
                    GlobTool.builder().build(),
                    SmartWebFetchTool.builder(chatClientBuilder.clone().build()).build(),
                    BraveWebSearchTool.builder(braveApiKey).build())

                // Task orchestration
                .defaultTools(TodoWriteTool.builder().build())

                // User feedback tool (use CommandLineQuestionHandler for CLI apps)
                .defaultTools(AskUserQuestionTool.builder()
                    .questionHandler(new CommandLineQuestionHandler())
                    .build())

                // Advisors
                .defaultAdvisors(
                    ToolCallAdvisor.builder().conversationHistoryEnabled(false).build(), // Tool Calling
                    MessageChatMemoryAdvisor.builder(MessageWindowChatMemory.builder().maxMessages(500).build()).build()) // Memory

                .build();

            String response = chatClient
                .prompt("Search for Spring AI documentation and summarize it")
                .call()
                .content();
        };
    }
}

Examples

Example	Description
code-agent-demo	Full-featured AI coding assistant with interactive CLI, all tools, and multi-model support
todo-demo	Structured task management with `TodoWriteTool` and real-time progress tracking
subagent-demo	Hierarchical sub-agent system with Markdown-defined local sub-agents
subagent-a2a-demo	A2A protocol integration for delegating tasks to remote agents
skills-demo	SkillsTool system with custom skill development and the ai-tuto example
ask-user-question-demo	Interactive agent-user communication with `AskUserQuestionTool`
memory/memory-tools-demo	Long-term memory across conversations using dedicated, sandboxed `AutoMemoryTools` (manual setup)
memory/memory-filesystem-tools-demo	Long-term memory using general-purpose `FileSystemTools` — no dedicated memory tooling required
memory/memory-tools-advisor-demo	Long-term memory via `AutoAutoMemoryToolsAdvisor` — advisor-based setup with consolidation trigger