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>io.github.markpollack</groupId>
    <artifactId>agent-claude</artifactId>
    <version>0.18.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>io.github.markpollack</groupId>
    <artifactId>agent-starter-claude</artifactId>
    <version>0.18.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)

Evaluation

AgentClient focuses on running CLI-delegated agents. Evaluation is provided by Agent Judge.

Use agent-judge-agent-client to adapt AgentClientResponse into Agent Judge's JudgmentContext. Judge advisor modules have been removed from AgentClient's runtime release path so the runtime layer remains independent from the evaluation layer.

Licensing

This project originated from earlier Apache-licensed work in the Spring AI Community.

Beginning with version 0.18.0, new development is licensed under the Business Source License 1.1 (BSL).

Historical Apache-licensed portions remain available under their original terms. See LICENSE and LICENSE-APACHE.txt for details.

Migration Notes

This project was previously published under org.springaicommunity.agents. Beginning with version 0.18.0, the Maven coordinates are:

<groupId>io.github.markpollack</groupId>

All Java packages have moved from org.springaicommunity.agents.* to io.github.markpollack.agents.*.