> ## Documentation Index > Fetch the complete documentation index at: https://springaicommunity.mintlify.app/llms.txt > Use this file to discover all available pages before exploring further. # Spring AI Agent Utils > Claude Code-inspired tools and agent skills for Spring AI applications Incubating Status [GitHub](https://github.com/spring-ai-community/spring-ai-agent-utils) • [Maven Central](https://central.sonatype.com/artifact/org.springaicommunity/spring-ai-agent-utils) ## Overview Spring AI Agent Utils brings [Claude Code](https://code.claude.com/docs/en/overview)-inspired tools and agent skills to Spring AI applications. This library 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. **Version**: 0.4.0 • Requires Spring AI 2.0.0-SNAPSHOT or 2.0.0-M2 ## Tool Categories Read, write, and edit files with precise control Execute commands with timeout, background processes, and output filtering Grep and Glob for fast code search and file pattern matching AI-powered web fetch with caching and Brave search integration Todo tracking and multi-agent task orchestration Extensible sub-agents with A2A protocol support Reusable knowledge modules in Markdown with YAML front-matter ## Quick Start ### Add Dependency ```xml theme={null} org.springaicommunity spring-ai-agent-utils 0.4.0 ``` ### Configure Your Agent ```java theme={null} ChatClient chatClient = chatClientBuilder // System prompt with environment context .defaultSystem(p -> p.text(agentSystemPrompt) .param(AgentEnvironment.ENVIRONMENT_INFO_KEY, AgentEnvironment.info()) .param(AgentEnvironment.GIT_STATUS_KEY, AgentEnvironment.gitStatus())) // Core Tools .defaultTools( ShellTools.builder().build(), FileSystemTools.builder().build(), GrepTool.builder().build(), GlobTool.builder().build(), SmartWebFetchTool.builder(chatClient).build(), BraveWebSearchTool.builder(braveApiKey).build()) // Task Management .defaultTools(TodoWriteTool.builder().build()) // Skills System .defaultToolCallbacks(SkillsTool.builder() .addSkillsDirectory(".claude/skills") .build()) // Sub-Agents .defaultToolCallbacks(TaskToolCallbackProvider.builder() .chatClientBuilder("default", chatClientBuilder.clone()) .subagentReferences(ClaudeSubagentReferences.fromRootDirectory(".claude/agents")) .build()) .build(); ``` ## Core Tools ### FileSystemTools Read, write, and edit files with precise control: ```java theme={null} FileSystemTools.builder() .allowedPaths(List.of("/project")) // Restrict access .build(); ``` Operations: `readFile`, `writeFile`, `editFile`, `listDirectory` ### ShellTools Execute shell commands with timeout control and background process management: ```java theme={null} ShellTools.builder() .defaultTimeout(Duration.ofMinutes(2)) .allowBackgroundProcesses(true) .build(); ``` Features: timeout control, background execution, regex output filtering ### GrepTool Pure Java grep implementation for code search: ```java theme={null} GrepTool.builder() .maxResults(100) .build(); ``` Features: regex patterns, glob filtering, multiple output modes (content, files, count) ### GlobTool Fast file pattern matching: ```java theme={null} GlobTool.builder().build(); ``` Supports patterns like `**/*.java`, `src/**/*.ts` ### SmartWebFetchTool AI-powered web content summarization with caching: ```java theme={null} SmartWebFetchTool.builder(chatClient) .cacheDuration(Duration.ofMinutes(15)) .build(); ``` ### BraveWebSearchTool Web search with domain filtering: ```java theme={null} BraveWebSearchTool.builder(braveApiKey) .maxResults(10) .build(); ``` ## User Interaction ### AskUserQuestionTool Ask users clarifying questions during agent execution: ```java theme={null} AskUserQuestionTool.builder() .questionHandler(questions -> { // Display questions to user, collect answers return answers; }) .build(); ``` Supports multiple-choice options and free-form input. ## Task Management ### TodoWriteTool Structured task management with state tracking: ```java theme={null} TodoWriteTool.builder().build(); ``` Track tasks with states: `pending`, `in_progress`, `completed` ### TaskTools (Sub-Agents) Extensible sub-agent system for delegating complex tasks to specialized agents: ```java theme={null} TaskToolCallbackProvider.builder() .chatClientBuilder("default", chatClientBuilder) .chatClientBuilder("haiku", haikuBuilder) // Multi-model support .subagentReferences(ClaudeSubagentReferences.fromRootDirectory(".claude/agents")) .skillsDirectories(".claude/skills") .build(); ``` **Features:** * **Multi-model routing** - Use different models for different sub-agents * **Pluggable backends** - Claude-style, A2A protocol, or custom implementations * **Background task execution** - Run sub-agents asynchronously * **Task output retrieval** - Get results from background tasks ### A2A Protocol Support The sub-agent architecture supports the [A2A (Agent-to-Agent) protocol](https://github.com/a2aprotocol/a2a-spec) for interoperability with external agents: ```java theme={null} // Custom A2A subagent integration (see subagent-demo example) public class A2ASubagentExecutor implements SubagentExecutor { @Override public String execute(TaskCall taskCall, SubagentDefinition subagent) { AgentCard agentCard = ((A2ASubagentDefinition) subagent).getAgentCard(); // Send message via A2A protocol Client client = Client.builder(agentCard) .withTransport(JSONRPCTransport.class, config) .build(); client.sendMessage(message); // ... } } ``` The extensible architecture uses three interfaces: * `SubagentResolver` - Discovers and loads sub-agent definitions * `SubagentExecutor` - Executes tasks on sub-agents * `SubagentDefinition` - Describes a sub-agent's capabilities ## Agent Skills Extend AI capabilities with reusable knowledge modules: ```markdown theme={null} --- name: code-review description: Reviews code for best practices tools: [FileSystemTools, GrepTool] --- # Code Review Skill When reviewing code, check for: 1. Security vulnerabilities 2. Performance issues 3. Code style consistency ... ``` Load skills from directories: ```java theme={null} SkillsTool.builder() .addSkillsDirectory(".claude/skills") .addSkillsDirectory("/shared/skills") .build(); ``` ## AgentEnvironment Dynamic context utility for system prompts: ```java theme={null} .defaultSystem(p -> p.text(systemPrompt) .param(AgentEnvironment.ENVIRONMENT_INFO_KEY, AgentEnvironment.info()) .param(AgentEnvironment.GIT_STATUS_KEY, AgentEnvironment.gitStatus()) .param(AgentEnvironment.AGENT_MODEL_KEY, "claude-sonnet-4-5") .param(AgentEnvironment.AGENT_MODEL_KNOWLEDGE_CUTOFF_KEY, "2025-01-01")) ``` Provides: working directory, platform info, git status, model information ## Examples | Example | Description | | ------------------------ | --------------------------------------------------------- | | `code-agent-demo` | Full-featured AI coding assistant with interactive CLI | | `todo-demo` | Task management with TodoWriteTool and progress tracking | | `subagent-demo` | Extensible sub-agent system with A2A protocol integration | | `skills-demo` | Custom skill development with SkillsTool | | `ask-user-question-demo` | Interactive agent-user communication | ## Requirements * Java 17+ * Spring Boot 3.x / 4.x * Spring AI 2.0.0-SNAPSHOT or 2.0.0-M2 ## Resources Source code, examples, and detailed documentation Original Claude Code documentation (inspiration) ## License This project is licensed under the [Apache License 2.0](https://github.com/spring-ai-community/spring-ai-agent-utils/blob/main/LICENSE.txt).