Agent Client

Autonomous CLI agent integrations for the Spring AI ecosystem

GitHub • Docs • Maven

Renamed: This project was previously called “Spring AI Agents” and has been renamed to “Agent Client” in version 0.9.0. The evaluation framework (Agent Judge) and sandbox isolation (Agent Sandbox) have been extracted into separate repositories.

Overview

What ChatClient did for completion endpoints, AgentClient does for Agent CLIs.

Agent Client 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.

Version: 0.9.0-SNAPSHOT Maven snapshot artifacts are available from Maven Central Snapshots

Agent SDKs

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

Claude Agent SDK

Anthropic’s Claude Code agent

Gemini Agent SDK

Google’s Gemini CLI agent

Amazon Q Agent SDK

AWS’s AI development agent

Amp Agent SDK

Amp AI agent platform

Codex Agent SDK

OpenAI’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

Currently Supported

• 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

Coming Soon

• Goose - Square’s AI agent framework
• Aider - AI pair programming in your terminal (GitHub)
• OpenHands - Open-source AI software engineer (GitHub)
• GitHub Copilot CLI - GitHub’s command-line AI assistant

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 Agent Client - no cloning, no building:

# One-time setup: Add the catalog
jbang catalog add --name=springai \
  https://raw.githubusercontent.com/spring-ai-community/agent-client/main/jbang-catalog.json

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

# 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.9.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 Agent Client architecture showing all five core concepts working together:

Core Domain Model

In Agent Client, 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, local processes, or cloud microVMs) for safe agent operations. Judges verify that goals were achieved - from simple file checks to LLM-powered validation.

Learn more: Agent Sandbox • Agent Judge

Agent Advisors

Agent Client 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)

Related Projects

These standalone libraries power Agent Client’s evaluation and isolation capabilities:

Agent Judge

Standalone evaluation framework - Judge, Jury, and Score APIs

Agent Sandbox

Isolated execution API - Local, Docker, and E2B backends

Resources

Official Documentation

Complete documentation and guides

GitHub Repository

View source code and contribute

Getting Started

Quick start guide

API Reference

API documentation

License

Agent Client is Open Source software released under the Apache 2.0 license.