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

Portable MCP Servers

Define MCP servers once, run on any agent provider

CLI Discovery

Automatic detection of installed CLI tools

Portable MCP Servers

MCP (Model Context Protocol) server definitions that work across all supported agent providers. Define MCP servers once in a portable format; Agent Client translates them to each provider’s native configuration at execution time.

How it works: The client resolves server names from a catalog of portable definitions. The model layer translates each definition to the provider’s native format — Claude gets a temp JSON config file via --mcp-config, Gemini gets .gemini/settings.json with --allowed-mcp-server-names. Your application code stays the same regardless of which agent runs the task.

Three transport types are supported: stdio (subprocess), sse (Server-Sent Events), and http.

Available since version 0.10.0. Currently supported by the Claude and Gemini agent models.

Defining a Catalog

JSON File

Create an mcp-servers.json file:

{
  "mcpServers": {
    "brave-search": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": { "BRAVE_API_KEY": "${BRAVE_API_KEY}" }
    },
    "weather": {
      "type": "sse",
      "url": "http://localhost:8080/sse"
    }
  }
}

McpServerCatalog catalog = McpServerCatalog.fromJson(Path.of("mcp-servers.json"));

Environment variable placeholders (${VAR_NAME}) are resolved from System.getenv() at load time. You can also point fromJson at a directory — all *.json files are parsed and merged into a single catalog.

Programmatic

Build a catalog using the builder API:

McpServerCatalog catalog = McpServerCatalog.builder()
    .add("brave-search", new McpServerDefinition.StdioDefinition(
        "npx",
        List.of("-y", "@modelcontextprotocol/server-brave-search"),
        Map.of("BRAVE_API_KEY", System.getenv("BRAVE_API_KEY"))))
    .add("weather", new McpServerDefinition.SseDefinition(
        "http://localhost:8080/sse"))
    .build();

Using MCP Servers with AgentClient

Set default servers on the builder, override per-request, or combine both:

AgentClient client = AgentClient.builder(agentModel)
    .mcpServerCatalog(catalog)
    .defaultMcpServers("weather")        // Applied to every request
    .build();

// Uses the default "weather" server
client.goal("What is the forecast in Portland?").run();

// Override: use "brave-search" instead for this request
client.goal("Research recent Spring AI releases")
    .mcpServers("brave-search")
    .run();

// Multiple servers in a single request
client.goal("Find weather data and summarize search results")
    .mcpServers("weather", "brave-search")
    .run();

Provider Translation

The same catalog produces the correct native configuration for each provider. No code changes needed when switching agents.

Provider	Native mechanism	What Agent Client generates
Claude	--mcp-config <path>	Temporary JSON config file (cleaned up after)
Gemini	.gemini/settings.json	Settings file in working directory (cleaned up after)

Limitations

• In-process MCP servers (live SDK server instances) cannot be expressed portably. Use provider-specific options for those.
• Unresolved environment variables in JSON catalogs are replaced with empty strings, not left as placeholders.

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.