Agent Client

Portable Java API for autonomous CLI agents — Claude Code, Codex, Gemini, Amazon Q, and Amp

GitHub • Maven Central • Tutorial

Version 0.16.0 — Available on Maven Central

What’s New in 0.16.0

• Framework-independent core — agent-client-core has zero Spring Boot dependencies. Use from plain Java, Quarkus, or Micronaut.
• AgentApi replaces AgentModel — new name reflects that implementations wrap CLI runtimes, not AI models. AgentModel is deprecated with a shim.
• New property prefix agent-client.* — replaces spring.ai.agents.* to properly distance from Spring AI namespace. Example: agent-client.claude.model instead of spring.ai.agents.claude-code.model.
• LOOSE mode sandbox bypass — Codex LOOSE now derives dangerouslyBypassSandbox=true, fixing bwrap sandbox failures.
• Codex model default — updated to gpt-5.4-mini (replaces retired gpt-5-codex).
• Gemini working directory fix — request working directory now properly propagated to CLI process.

Previous (0.15.0)

• AgentClientMode (LOOSE/STRICT) — portable enum controlling default permissiveness.
• Provider Parity TCK — @ProviderCapability annotation with JUnit Assumptions.
• Reference documentation — complete configuration reference for all providers.
• Tutorial repository — progressive examples at agent-client-tutorial.

Overview

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

Agent Client provides a portable Java API for autonomous CLI agents. Build a model, create a client, run a goal — provider selection happens at construction time, everything after is portable.

// Provider-specific: build the model
ClaudeAgentModel model = ClaudeAgentModel.builder()
    .defaultOptions(ClaudeAgentOptions.builder()
        .model("claude-sonnet-4-5")
        .yolo(true)
        .build())
    .build();

// Portable: works with any provider
AgentClient client = AgentClient.create(model);
AgentClientResponse response = client.run("Create hello.txt with 'Hello!'");

No Spring Boot required. Optional Spring Boot starters provide auto-configuration for those who want it.

Supported Providers

Claude Code

Anthropic’s autonomous coding agent — 18 configuration options

Codex

OpenAI’s code generation agent — LOOSE mode for frictionless setup

Gemini CLI

Google’s Gemini models via CLI

Amazon Q

AWS developer assistant (beta)

Amp

Sourcegraph’s AI coding assistant (beta)

Custom

Implement AgentModel for any CLI agent

Documentation

Getting Started

Plain Java quick start — create your first agent task

Tutorial

Step-by-step lessons from first task to multi-provider

Reference

Configuration options, precedence rules, mode system

Switching Providers

Run the same task with different providers using Maven profiles

Key Features

Portable API

AgentClient.create(model) works with any provider. Switch by swapping the model.

LOOSE/STRICT Modes

Control default permissiveness. LOOSE works anywhere, STRICT requires opt-in.

Agent Sessions

Persistent multi-turn conversations with session lifecycle management.

Portable MCP Servers

Define MCP servers once, run on any provider. Client resolves, model translates.

Agent Advisors

Interception points for context engineering, evaluation, security, and observability.

Spring Boot Starters

Optional auto-configuration with agent-starter-claude, agent-starter-codex, etc.

Quick Start

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

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("Fix the failing test in UserServiceTest");

See the Getting Started guide for all three providers and the Spring Boot path.

Portable MCP Servers

Define MCP servers once in a portable format. Agent Client translates to each provider’s native configuration at execution time.

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

AgentClient client = AgentClient.builder(model)
    .mcpServerCatalog(catalog)
    .defaultMcpServers("weather")
    .build();

// Per-request MCP server selection
client.goal("Research recent Spring AI releases")
    .mcpServers("brave-search")
    .run();

Provider	Native mechanism
Claude	--mcp-config <path> — temporary JSON config file
Gemini	.gemini/settings.json — settings file in working directory

Agent Advisors

The same advisor pattern as Spring AI’s ChatClient — powerful interception for context engineering, evaluation, and security:

AgentClient client = AgentClient.builder(model)
    .defaultAdvisor(new WorkspaceContextAdvisor())
    .defaultAdvisor(JudgeAdvisor.builder().judge(coverageJudge).build())
    .build();

Related Projects

Agent Judge

Standalone evaluation framework — Judge, Jury, and Score APIs

Agent Sandbox

Isolated execution — Local, Docker, and E2B backends

Claude Agent SDK

Low-level Java SDK for Claude Code CLI

Agent Bench

Benchmarking framework for agent evaluation

License

Apache 2.0 — View on GitHub