Spring AI Agent Utils

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

Overview

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.

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.

Project Structure

spring-ai-agent-utils/
├── spring-ai-agent-utils-common/        # Shared subagent SPI (interfaces & records)
├── spring-ai-agent-utils/               # Core library (tools, advisors, skills, Claude subagents)
├── spring-ai-agent-utils-a2a/           # A2A protocol subagent implementation
├── spring-ai-agent-utils-bom/           # Bill of Materials for version management
│
└── examples/
    ├── code-agent-demo/                 # Full-featured AI coding assistant
    ├── ask-user-question-demo/          # Interactive question-answer demo
    ├── skills-demo/                     # Focused skills system demo
    ├── subagent-demo/                   # Markdown-defined local sub-agents
    ├── subagent-a2a-demo/               # A2A protocol remote sub-agents
    ├── todo-demo/                       # TodoWriteTool task management demo
    └── memory/
        ├── memory-tools-demo/           # Long-term memory with AutoMemoryTools (manual setup)
        ├── memory-filesystem-tools-demo/# Long-term memory with general FileSystemTools
        └── memory-tools-advisor-demo/   # Long-term memory via AutoMemoryToolsAdvisor

Agentic Utils

These are the agent tools needed to implement any agentic behavior

Core Tools

AgentEnvironment - Dynamic agent context utility that provides runtime environment information and git repository status to system prompts
FileSystemTools - Read, write, and edit files with precise control
ShellTools - Execute shell commands with timeout control, background process management, and regex output filtering
GrepTool - Pure Java grep implementation for code search with regex, glob filtering, and multiple output modes
GlobTool - Fast file pattern matching tool for finding files by name patterns with glob syntax
SmartWebFetchTool - AI-powered web content summarization with caching
BraveWebSearchTool - Web search with domain filtering

User feedback

AskUserQuestionTool - Ask users clarifying questions with multiple-choice options during agent execution

Agent Skills

SkillsTool - Extend AI agent capabilities with reusable, composable knowledge modules defined in Markdown with YAML front-matter

Long-term memory

AutoMemoryTools - 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 and the Claude API SDK memory tool.
AutoMemoryToolsAdvisor - 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.

Task orchestration & multi-agent

TodoWriteTool - Structured task management with state tracking
TaskTools - Extensible sub-agent system for delegating complex tasks to specialized agents with multi-model routing and pluggable backends

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.

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
spring-ai-agent-utils-docker-cli	Docker ExecBackend - run agent shell commands inside a sandbox container (in `exec-backends/`)
spring-ai-agent-utils-bom	Bill of Materials for consistent version management across all modules
Examples	Working demos showcasing different use cases

Quick Start

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.12.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.12.0</version>
</dependency>

Check the latest version:

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();
        };
    }
}

References

This project reimplements key Claude Code features based on:

Claude Code Documentation
Claude Code Agent Skills
Claude Code Internals - Reverse engineering prompt augmentation
Claude Code Skills - Implementation patterns

Requirements

Java 17+
Spring Boot 3.x / 4.x
Spring AI 2.0.0 or later
Maven 3.6+

Building

# Build the entire project
mvn clean install

# Run an example
cd examples/code-agent-demo  # or examples/skills-demo
mvn spring-boot:run

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 `AutoMemoryToolsAdvisor` — advisor-based setup with consolidation trigger

See examples/README.md for setup and usage details.

License

Apache License 2.0

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

spring-ai-agent-utils

Links

README