Skip to content
Back to search

spring-ai-agent-utils

A Spring AI library that brings Claude Code-inspired tools and agent skills to your AI applications.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/spring-ai-community/spring-ai-agent-utils with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/spring-ai-community/spring-ai-agent-utils'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/spring-ai-community--spring-ai-agent-utils/badge.svg)](/listings/spring-ai-community--spring-ai-agent-utils)

HTML

<a href="/listings/spring-ai-community--spring-ai-agent-utils"><img src="/api/listings/spring-ai-community--spring-ai-agent-utils/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

**1. Add dependency:**

Use the BOM to manage versions consistently across all modules:

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.springaicommunity</groupId>
            <artifactId>spring-ai-agent-utils-bom</artifactId>
            <version>0.13.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>

Or add the core library directly:

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

_Check the latest version:_ [![](https://img.shields.io/maven-central/v/org.springaicommunity/spring-ai-agent-utils.svg?label=Maven%20Central)](https://central.sonatype.com/artifact/org.springaicommunity/spring-ai-agent-utils)

> **Note:** You need Spring AI version `` or later.

**2. Configure your 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"))

                .defaultTools(
                    // Sub-Agents
                    taskTool, 

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

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

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

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

                // Advisors
                .defaultAdvisors(
                    MessageChatMemoryAdvisor.builder(MessageWindowChatMemory.builder().maxMessages(500).build()).build()) // Memory

                .build();

            String response = chatClient
                .prompt("Search for Spring AI documentation and summarize it")
                .advisors(a -> a.param(ChatMemory.CONVERSATION_ID, "session-1"))
                .call()
                .content();
        };
    }
}

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 267 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Spring AI Agent Utils
  2. [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
  3. [![Maven Central](https://img.shields.io/maven-central/v/org.springaicommunity/spring-ai-agent-utils.svg?label=Maven%20Central)](https://central.sonatype.com/artifact/org.springaicommunity/spring-ai-agent-utils)
  4. [![Java Version](https://img.shields.io/badge/Java-17%2B-orange)](https://www.oracle.com/java/technologies/javase/jdk17-archive-downloads.html)
  5. A [Spring AI](https://docs.spring.io/spring-ai/reference/2.0-SNAPSHOT/index.html) library that brings [Claude Code](https://code.claude.com/docs/en/settings#tools-available-to-claude)-inspired tools and agent skills to your AI applications.
  6. ## Overview
  7. <img style="display: block; margin: auto;" align="left" src="docs/images/spring-ai-agent-utils-logo.png" width="250" />
  8. Spring AI Agent Utils reimplements core Claude Code capabilities as Spring AI tools, enabling sophisticated agentic workflows with file operations, shell execution, web access, task management, and extensible agent skills.
  9. This project demonstrates how to reverse-engineer and reimplement Claude Code's powerful features within the Spring AI ecosystem, making them available to Java developers building AI agents.
  10. ## Project Structure
  11. ```
  12. spring-ai-agent-utils/
  13. ├── spring-ai-agent-utils-common/ # Shared subagent SPI (interfaces & records)
  14. ├── spring-ai-agent-utils/ # Core library (tools, advisors, skills, Claude subagents)
  15. ├── spring-ai-agent-utils-a2a/ # A2A protocol subagent implementation
  16. ├── spring-ai-agent-utils-bom/ # Bill of Materials for version management
  17. │
  18. └── examples/
  19. ├── code-agent-demo/ # Full-featured AI coding assistant
  20. ├── ask-user-question-demo/ # Interactive question-answer demo
  21. ├── skills-demo/ # Focused skills system demo
  22. ├── subagent-demo/ # Markdown-defined local sub-agents
  23. ├── subagent-a2a-demo/ # A2A protocol remote sub-agents
  24. ├── todo-demo/ # TodoWriteTool task management demo
  25. └── memory/
  26. ├── memory-tools-demo/ # Long-term memory with AutoMemoryTools (manual setup)
  27. ├── memory-filesystem-tools-demo/# Long-term memory with general FileSystemTools
  28. └── memory-tools-advisor-demo/ # Long-term memory via AutoMemoryToolsAdvisor
  29. ```
  30. ## Agentic Utils
  31. These are the agent tools needed to implement any agentic behavior
  32. #### Core Tools
  33. - **[AgentEnvironment](docs/tools/AgentEnvironment.md)** - Dynamic agent context utility that provides runtime environment information and git repository status to system prompts
  34. - **[FileSystemTools](docs/tools/FileSystemTools.md)** - Read, write, and edit files with precise control
  35. - **[ShellTools](docs/tools/ShellTools.md)** - Execute shell commands with timeout control, background process management, and regex output filtering
  36. - **[GrepTool](docs/tools/GrepTool.md)** - Pure Java grep implementation for code search with regex, glob filtering, and multiple output modes
  37. - **[GlobTool](docs/tools/GlobTool.md)** - Fast file pattern matching tool for finding files by name patterns with glob syntax
  38. - **[SmartWebFetchTool](docs/tools/SmartWebFetchTool.md)** - AI-powered web content summarization with caching
  39. - **[BraveWebSearchTool](docs/tools/BraveWebSearchTool.md)** - Web search with domain filtering
  40. #### User feedback
  41. - **[AskUserQuestionTool](docs/tools/AskUserQuestionTool.md)** - Ask users clarifying questions with multiple-choice options during agent execution
  42. #### Agent Skills
  43. - **[SkillsTool](docs/tools/SkillsTool.md)** - Extend AI agent capabilities with reusable, composable knowledge modules defined in Markdown with YAML front-matter
  44. #### Long-term memory
  45. - **[AutoMemoryTools](docs/tools/AutoMemoryTools.md)** - Persistent, file-based long-term memory that survives across conversations. Agents store typed memory files (`user`, `feedback`, `project`, `reference`) in a sandboxed directory and navigate them via a `MEMORY.md` index. Requires the companion `classpath:/prompt/AUTO_MEMORY_TOOLS_SYSTEM_PROMPT.md` system prompt (bundled in the jar) to instruct the agent on when and how to use the tools. Inspired by [Claude Code memory](https://code.claude.com/docs/en/memory) and the [Claude API SDK memory tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/memory-tool).
  46. - **[AutoMemoryToolsAdvisor](docs/tools/AutoMemoryToolsAdvisor.md)** - A `ChatClient` advisor that wires `AutoMemoryTools` and its companion system prompt into the request pipeline automatically. Eliminates manual tool and prompt registration, deduplicates callbacks, and supports an optional `memoryConsolidationTrigger` to prompt the model to summarise and clean up memories on a schedule.
  47. #### Task orchestration & multi-agent
  48. - **[TodoWriteTool](docs/tools/TodoWriteTool.md)** - Structured task management with state tracking
  49. - **[TaskTools](docs/tools/TaskTools.md)** - Extensible sub-agent system for delegating complex tasks to specialized agents with multi-model routing and pluggable backends
  50. #### Agent loop control & observability
  51. - **[InterruptAdvisor](docs/tools/InterruptAdvisor.md)** - Cooperative cancellation of a running agent turn: a "stop" button, a deadline or a budget guard stops the tool-calling loop before its next model request
  52. - **[ToolCallListener](docs/tools/ToolCallListener.md)** - Observe every tool invocation (audit logs, progress streaming, metrics) and choose whether a tool failure is reported to the model or rethrown
  53. While these tools can be used standalone, truly agentic behavior emerges when they are combined. SkillsTool naturally pairs with FileSystemTools and ShellTools to execute domain-specific workflows. BraveWebSearchTool and SmartWebFetchTool provide your AI application with access to real-world information. TaskTools orchestrates complex operations by delegating to specialized sub-agents, each equipped with a tailored subset of these tools.
  54. ### Detailed Documentation
  55. | Module | Description |
  56. |--------|-------------|
  57. | [**spring-ai-agent-utils**](spring-ai-agent-utils/README.md) | Core library - tools, skills, Claude subagents, and full API reference |
  58. | [**spring-ai-agent-utils-common**](spring-ai-agent-utils-common/README.md) | Shared subagent SPI (SubagentDefinition, SubagentResolver, SubagentExecutor, SubagentType) |
  59. | [**spring-ai-agent-utils-a2a**](spring-ai-agent-utils-a2a/README.md) | A2A protocol subagent for remote agent orchestration |
  60. | [**spring-ai-agent-utils-docker-cli**](docs/tools/DockerCliExecBackend.md) | Docker ExecBackend - run agent shell commands inside a sandbox container (in `exec-backends/`) |
  61. | [**spring-ai-agent-utils-bom**](spring-ai-agent-utils-bom/pom.xml) | Bill of Materials for consistent version management across all modules |
  62. | [**Examples**](#examples) | Working demos showcasing different use cases |
  63. ## Quick Start
  64. **1. Add dependency:**
  65. Use the BOM to manage versions consistently across all modules:
  66. ```xml
  67. <dependencyManagement>
  68. <dependencies>
  69. <dependency>
  70. <groupId>org.springaicommunity</groupId>
  71. <artifactId>spring-ai-agent-utils-bom</artifactId>
  72. <version>0.13.0</version>
  73. <type>pom</type>
  74. <scope>import</scope>
  75. </dependency>
  76. </dependencies>
  77. </dependencyManagement>
  78. <dependencies>
  79. <dependency>
  80. <groupId>org.springaicommunity</groupId>
  81. <artifactId>spring-ai-agent-utils</artifactId>
  82. </dependency>
  83. </dependencies>
  84. ```
  85. Or add the core library directly:
  86. ```xml
  87. <dependency>
  88. <groupId>org.springaicommunity</groupId>
  89. <artifactId>spring-ai-agent-utils</artifactId>
  90. <version>0.13.0</version>
  91. </dependency>
  92. ```
  93. _Check the latest version:_ [![](https://img.shields.io/maven-central/v/org.springaicommunity/spring-ai-agent-utils.svg?label=Maven%20Central)](https://central.sonatype.com/artifact/org.springaicommunity/spring-ai-agent-utils)
  94. > **Note:** See [Requirements](#requirements) for the supported Spring AI version.
  95. **2. Configure your agent:**
  96. ```java
  97. @SpringBootApplication
  98. public class Application {
  99. @Bean
  100. CommandLineRunner demo(ChatClient.Builder chatClientBuilder,
  101. @Value("${BRAVE_API_KEY}") String braveApiKey,
  102. @Value("${agent.skills.paths}") List<Resource> skillPaths,
  103. @Value("classpath:/prompt/MAIN_AGENT_SYSTEM_PROMPT_V2.md") Resource agentSystemPrompt) {
  104. return args -> {
  105. // Configure Task tool with Claude sub-agents
  106. var taskTool = TaskTool.builder()
  107. .subagentTypes(ClaudeSubagentType.builder()
  108. .chatClientBuilder("default", chatClientBuilder.clone())
  109. .skillsResources(skillPaths)
  110. .braveApiKey(braveApiKey)
  111. .build())
  112. .build();
  113. // Conversation memory: an in-memory session store
  114. SessionService sessionService = DefaultSessionService.builder()
  115. .sessionRepository(InMemorySessionRepository.builder().build())
  116. .build();
  117. ChatClient chatClient = chatClientBuilder
  118. // Main agent prompt
  119. .defaultSystem(p -> p.text(agentSystemPrompt) // system prompt
  120. .param(AgentEnvironment.ENVIRONMENT_INFO_KEY, AgentEnvironment.info())
  121. .param(AgentEnvironment.GIT_STATUS_KEY, AgentEnvironment.gitStatus())
  122. .param(AgentEnvironment.AGENT_MODEL_KEY, "claude-sonnet-4-5-20250929")
  123. .param(AgentEnvironment.AGENT_MODEL_KNOWLEDGE_CUTOFF_KEY, "2025-01-01"))
  124. .defaultTools(
  125. // Sub-Agents
  126. taskTool,
  127. // Skills
  128. SkillsTool.builder()
  129. .addSkillsResources(skillPaths)
  130. .build()
  131. // Core Tools
  132. ShellTools.builder().build(),
  133. FileSystemTools.builder().build(),
  134. GrepTool.builder().build(),
  135. GlobTool.builder().build(),
  136. SmartWebFetchTool.builder(chatClientBuilder.clone().build()).build(),
  137. BraveWebSearchTool.builder(braveApiKey).build(),
  138. // Task orchestration
  139. TodoWriteTool.builder().build()
  140. // User feedback tool (use CommandLineQuestionHandler for CLI apps)
  141. AskUserQuestionTool.builder()
  142. .questionHandler(new CommandLineQuestionHandler())
  143. .build())
  144. // Conversation memory
  145. .defaultAdvisors(SessionAdvisors.builder(sessionService).build())
  146. .build();
  147. String response = chatClient
  148. .prompt("Search for Spring AI documentation and summarize it")
  149. .advisors(SessionAdvisors.session("session-1"))
  150. .call()
  151. .content();
  152. };
  153. }
  154. }
  155. ```
  156. The conversation memory in this example comes from Spring AI's session module: add `org.springframework.ai:spring-ai-session-advisor` (its version comes from the Spring AI BOM, and it brings in `spring-ai-session`). See [Session Memory](https://docs.spring.io/spring-ai/reference/api/session.html) for persistent stores and compaction.
  157. ## References
  158. This project reimplements key Claude Code features based on:
  159. - [Claude Code Documentation](https://code.claude.com/docs/en/overview)
  160. - [Claude Code Agent Skills](https://code.claude.com/docs/en/skills#agent-skills)
  161. - [Claude Code Internals](https://agiflow.io/blog/claude-code-internals-reverse-engineering-prompt-augmentation/) - Reverse engineering prompt augmentation
  162. - [Claude Code Skills](https://mikhail.io/2025/10/claude-code-skills/) - Implementation patterns
  163. ## Requirements
  164. - Java 17+
  165. - Spring Boot 4.2 or later (the version Spring AI 2.1 is built on)
  166. - Spring AI 2.1 or later
  167. - Maven 3.6+
  168. ## Building
  169. ```bash
  170. # Build the entire project
  171. mvn clean install
  172. # Run an example
  173. cd examples/code-agent-demo # or examples/skills-demo
  174. mvn spring-boot:run
  175. ```
  176. ## Examples
  177. | Example | Description |
  178. |---------|-------------|
  179. | [code-agent-demo](examples/code-agent-demo) | Full-featured AI coding assistant with interactive CLI, all tools, and multi-model support |
  180. | [todo-demo](examples/todo-demo) | Structured task management with `TodoWriteTool` and real-time progress tracking |
  181. | [subagent-demo](examples/subagent-demo) | Hierarchical sub-agent system with Markdown-defined local sub-agents |
  182. | [subagent-a2a-demo](examples/subagent-a2a-demo) | A2A protocol integration for delegating tasks to remote agents |
  183. | [skills-demo](examples/skills-demo) | SkillsTool system with custom skill development and the ai-tuto example |
  184. | [ask-user-question-demo](examples/ask-user-question-demo) | Interactive agent-user communication with `AskUserQuestionTool` |
  185. | [memory/memory-tools-demo](examples/memory/memory-tools-demo) | Long-term memory across conversations using dedicated, sandboxed `AutoMemoryTools` (manual setup) |
  186. | [memory/memory-filesystem-tools-demo](examples/memory/memory-filesystem-tools-demo) | Long-term memory using general-purpose `FileSystemTools` — no dedicated memory tooling required |
  187. | [memory/memory-tools-advisor-demo](examples/memory/memory-tools-advisor-demo) | Long-term memory via `AutoMemoryToolsAdvisor` — advisor-based setup with consolidation trigger |
  188. See [examples/README.md](examples/README.md) for setup and usage details.
  189. ## License
  190. Apache License 2.0
  191. ## Links
  192. - [Documentation](https://springaicommunity.mintlify.app/projects/incubating/spring-ai-agent-utils)
  193. - [GitHub Repository](https://github.com/spring-ai-community/spring-ai-agent-utils)
  194. - [Issue Tracker](https://github.com/spring-ai-community/spring-ai-agent-utils/issues)
  195. - [Spring AI Documentation](https://docs.spring.io/spring-ai/reference/)
  196. - [Claude Code Documentation](https://code.claude.com/docs/en/overview)
  197. ## Contributing
  198. Contributions are welcome! Please feel free to submit issues or pull requests.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.