Skip to main content
Incubating Status GitHub • Docs • Maven

​
Overview

What ChatClient did for completion endpoints, AgentClient does for Agent CLIs. Spring AI Agents provides a unified framework for autonomous agents with Goals (clear objectives), Tools (actions agents can take), Context (information for decisions), Judges (automated verification), and Sandboxes (isolated execution). This project brings multiple AI agent platforms to Spring applications as first-class citizens with Spring Boot auto-configuration. Currently supported: Claude Code, Gemini, Amazon Q, Amp, and Codex. Coming soon: Goose, Aider, OpenHands, and GitHub Copilot CLI. Agent Execution Workflow
Version: 0.1.0-SNAPSHOT Maven snapshot artifacts are available from Maven Central Snapshots

​
Agent SDKs

Spring AI Agents provides Agent SDKs for multiple platforms with Spring Boot auto-configuration:

Claude Agent SDK

Claude CodeAnthropic’s Claude Code agent

Gemini Agent SDK

GeminiGoogle’s Gemini CLI agent

Amazon Q Agent SDK

Amazon QAWS’s AI development agent

Amp Agent SDK

AmpAmp AI agent platform

Codex Agent SDK

CodexOpenAI’s Codex agent

Custom Agent SDK

Bring your own agent

​
Key Features

Spring Boot Auto-Configuration

Automatic agent discovery and configuration with Spring Boot starters

Secure Sandbox Isolation

Docker container isolation with local fallback for safe agent execution

Unified AgentClient API

Consistent interface across all agent providers

CLI Discovery

Automatic detection of installed CLI tools

​
Agent Roadmap

  • Claude Code - Anthropic’s autonomous coding assistant
  • Gemini - Google’s AI development platform
  • Amazon Q - AWS’s enterprise AI assistant
  • Amp - AI agent platform
  • Codex - OpenAI’s code generation model

​
Highlighted Achievement

​
Code Coverage Agent

An autonomous agent that increased test coverage from 0% to 71.4% on Spring’s gs-rest-service tutorial.
Key Finding: Both Claude and Gemini achieved the same coverage percentage, but only Claude followed all Spring WebMVC best practices (@WebMvcTest, jsonPath(), BDD naming).
Model quality matters: Same coverage, different code quality. Claude generated production-ready tests while Gemini used slower patterns (@SpringBootTest).
Learn More: See the Code Coverage Agent Guide for detailed implementation and results.

​
Quick Start

​
Try with JBang (Zero Setup)

The fastest way to try Spring AI Agents - no cloning, no building: 
# One-time setup: Add the catalog
jbang catalog add --name=springai \
  https://raw.githubusercontent.com/spring-ai-community/spring-ai-agents/main/jbang-catalog.json

# Static content example
jbang agents@springai hello-world \
  path=greeting.txt \
  content="Hello Spring AI Agents!"

# AI-powered examples (requires API keys)
export ANTHROPIC_API_KEY="your-key-here"

jbang agents@springai hello-world-agent-ai \
  path=ai-greeting.txt \
  content="a creative message about AI agents" \
  provider=claude

​
Maven Dependencies

<dependency>
    <groupId>org.springaicommunity.agents</groupId>
    <artifactId>spring-ai-starter-agent</artifactId>
    <version>0.1.0-SNAPSHOT</version>
</dependency>

​
Basic Usage

@Autowired
private AgentClient agentClient;

// Simple goal execution
String result = agentClient.run("Fix the failing test in UserServiceTest");

// Advanced goal configuration
AgentClientResponse response = agentClient
    .goal("Generate comprehensive API documentation")
    .workingDirectory(projectRoot)
    .run();

​
Complete Architecture

The complete Spring AI Agents architecture showing all five core concepts working together: Spring AI Agents Complete Architecture

​
Core Domain Model

In Spring AI Agents, we model agents around these components:

Goals 🎯

Clear objectives that guide agent execution

Tools 🔧

Actions the agent can take (call APIs, run commands, read files)

Context 📊

Information the agent needs to make decisions

Judges ⚖️

Verification that the goal was achieved
Example: 
CoverageJudge judge = new CoverageJudge(80.0);

AgentClientResponse response = agentClient
    .goal("Increase JaCoCo test coverage to 80%")
    .workingDirectory(projectRoot)
    .advisors(JudgeAdvisor.builder().judge(judge).build())
    .run();
Sandboxes provide isolated execution environments (Docker or local processes) for safe agent operations. Judges verify that goals were achieved - from simple file checks to LLM-powered validation. Learn more: Sandboxes • Judges

​
Agent Advisors

Spring AI Agents implements the same advisor pattern as Spring AI’s ChatClient: 
public class WorkspaceContextAdvisor implements AgentCallAdvisor {
    @Override
    public AgentClientResponse adviseCall(AgentClientRequest request,
                                          AgentCallAdvisorChain chain) {
        // Inject context before execution
        String workspaceInfo = analyzeWorkspace(request.workingDirectory());
        request.context().put("workspace_info", workspaceInfo);

        // Execute agent
        AgentClientResponse response = chain.nextCall(request);

        // Add post-execution metrics
        response.context().put("files_modified", countModifiedFiles());
        return response;
    }
}
Common Use Cases:
  • Context Engineering (git cloning, dependency sync)
  • Evaluation/Judges (test running, file verification)
  • Security (goal validation, operation blocking)
  • Observability (metrics, logging, performance)

​
Resources

Official Documentation

Complete documentation and guides

GitHub Repository

View source code and contribute

Getting Started

Quick start guide

API Reference

API documentation

​
License

Spring AI Agents is Open Source software released under the Apache 2.0 license.
⌘I