Important

This repository is no longer maintained.

Active development has moved to markpollack/agent-client. Current documentation is available at lab.pollack.ai.

This repository remains available for historical Spring AI Community releases. Its Apache 2.0 license and historical contents are unchanged. Please submit new issues and pull requests to the active repository.

Agent Client

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

Agent Client provides a unified Java API for autonomous CLI agents — Claude Code, Codex, Gemini, Amazon Q, and Amp — with Spring Boot auto-configuration support.

📖 Documentation | Getting Started | Reference | Tutorial

Quick Start

Add the dependency for your provider:

<dependency>
    <groupId>org.springaicommunity.agents</groupId>
    <artifactId>agent-claude</artifactId>
    <version>0.15.0</version>
</dependency>

Build a model, create a client, run a goal — no Spring Boot required:

ClaudeAgentModel model = ClaudeAgentModel.builder()
    .defaultOptions(ClaudeAgentOptions.builder()
        .model("claude-sonnet-4-5")
        .yolo(true)
        .build())
    .build();

AgentClient client = AgentClient.create(model);
AgentClientResponse response = client.run("Create hello.txt with 'Hello from Agent Client!'");

With Spring Boot

Use a starter for auto-configuration:

<dependency>
    <groupId>org.springaicommunity.agents</groupId>
    <artifactId>agent-starter-claude</artifactId>
    <version>0.15.0</version>
</dependency>

@Component
public class MyAgent implements CommandLineRunner {
    private final AgentClient.Builder agentClientBuilder;

    public MyAgent(AgentClient.Builder agentClientBuilder) {
        this.agentClientBuilder = agentClientBuilder;
    }

    @Override
    public void run(String... args) {
        AgentClient client = agentClientBuilder.build();
        AgentClientResponse response = client.run("Fix the failing test");
    }
}

Supported Providers

Provider	Starter	Status
Claude Code	agent-starter-claude	Production
Codex	agent-starter-codex	Production
Gemini CLI	agent-starter-gemini	Production
Amazon Q	agent-starter-amazon-q	Beta
Amp	agent-starter-amp	Beta

Multi-Provider Support

Switch providers without changing code — use Maven profiles or swap the starter:

// This code works with ANY provider
AgentClient client = AgentClient.create(model);
AgentClientResponse response = client.run("Create hello.txt");

See Switching Providers for the Maven profile pattern.

Configuration

spring:
  ai:
    agents:
      mode: loose  # or strict
      claude-code:
        model: claude-sonnet-4-5
        timeout: PT5M
        yolo: true
      codex:
        model: gpt-5-codex
        full-auto: true
      gemini:
        model: gemini-2.5-flash
        yolo: true

See the Reference pages for all configuration options.

Architecture

agent-client/
├── agent-client-core/               # AgentClient fluent API
├── agent-models/                    # Provider adapters
│   ├── agent-model/                 # Core abstractions (AgentModel, AgentOptions)
│   ├── agent-tck/                   # Provider parity test kit
│   ├── agent-claude/                # Claude Code adapter
│   ├── agent-codex/                 # Codex adapter
│   ├── agent-gemini/                # Gemini CLI adapter
│   ├── agent-amazon-q/              # Amazon Q adapter
│   └── agent-amp/                   # Amp adapter
├── provider-sdks/                   # CLI client libraries
├── agent-starters/                  # Spring Boot auto-configuration
└── agents/                          # JBang-compatible agents

Two-Layer Design

• AgentClient — High-level fluent API (like ChatClient)
• AgentModel — Low-level provider interface (like ChatModel)

Provider selection happens at construction time. Everything after AgentClient.create(model) is portable.

Documentation

Type	Link
Getting Started	Quick start guide
Tutorial	Step-by-step lessons
Reference	Configuration options
Provider Reference	Claude · Codex · Gemini
Defaults Philosophy	LOOSE vs STRICT modes
Sessions	Multi-turn conversations

Building

./mvnw clean compile          # Compile
./mvnw clean test             # Unit tests
./mvnw clean verify -Pfailsafe  # Integration tests (requires CLIs + API keys)

License

Apache 2.0 — see LICENSE.