local_fire_departmentHoneystax
search⌘K
loginLog Inperson_addSign Up
layers
HONEYSTAX TERMINAL v1.0
HomeNewsSavedSubmit
Back to the live board
S

spring-ai-agent-utils

Agent

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

Copy the install, test the workflow, then decide if it earns a permanent slot.

180
Why nowMoving now

Fresh repo activity plus visible builder pull. This is the kind of tool people test before it turns obvious.

DecisionWorth testing this week

Copy the install, test the workflow, then decide if it earns a permanent slot.

Trial costMedium lift

Reasonable to try, but it will take more than a quick skim to get real signal.

Risk26/100

GitHub health 62/100. no security policy. Fresh enough repo health and manageable issue load keep the risk controlled.

What You Are Adopting

AI Agent

Claude Code

Model

Multiple

Build Time

Instant

Test This In Your Stack

One command inClean rollbackLow commitment
shieldSandboxedInstalls to ~/.claude — isolated from your projects. One command to remove.

Fastest way to find out if spring-ai-agent-utils belongs in your setup.

Copy the install command, run a real test, and back it out cleanly if it slows you down.

Try now
git clone https://github.com/spring-ai-community/spring-ai-agent-utils ~/.claude/agents/spring-ai-agent-utils

Run this first. You will know quickly if the workflow earns a permanent slot.

Back out
rm -rf ~/.claude/agents/spring-ai-agent-utils

No messy cleanup loop. If it misses, remove it and keep moving.

Install Location

~/  └─ .claude/      ├─ commands/      ├─ agents/      │   └─ spring-ai-agent-utils/ ← installs here      └─ settings.json

About

A Spring AI library that brings Claude Code-inspired tools and agent skills to your AI applications.. An open-source agent for the AI coding ecosystem.

README

Spring AI Agent Utils

License Maven Central Java Version

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, 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

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

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-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.5.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.5.0</version>
</dependency>

Check the latest version:

Note: You need Spring AI version 2.0.0-M2 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"))

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

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-M2 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

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

License

Apache License 2.0

Links

  • GitHub Repository
  • Issue Tracker
  • Spring AI Documentation
  • Claude Code Documentation

Contributing

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

Tech Stack

JavaSpringGoClaude
Open Live ProjectAudit Repo

Reviews0

Log in to write a review.

ActiveLast commit 20d ago
bug_report20open issues
Submitted January 8, 2026

auto_awesomeYour strongest next moves after spring-ai-agent-utils