Getting Started

Run your first agent task with Spring AI Agent Client in under 5 minutes

Prerequisites

• Java 17+
• Maven 3.9+ (or use the Maven wrapper)
• A CLI agent installed and authenticated:
  • Claude: claude auth login (install guide)
  • Codex: export OPENAI_API_KEY=sk-... (install guide)
  • Gemini: export GEMINI_API_KEY=... (install guide)

1. Add the Dependency

Pick your provider. You need the agent model module for your provider:

Claude

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

Codex

<dependency>
    <groupId>org.springaicommunity.agents</groupId>
    <artifactId>agent-codex</artifactId>
    <version>0.16.0</version>
</dependency>

Gemini

<dependency>
    <groupId>org.springaicommunity.agents</groupId>
    <artifactId>agent-gemini</artifactId>
    <version>0.16.0</version>
</dependency>

2. Create an Agent and Run a Task

No Spring Boot required. Build a model, create a client, run a goal:

Claude

import org.springaicommunity.agents.client.AgentClient;
import org.springaicommunity.agents.client.AgentClientResponse;
import org.springaicommunity.agents.claude.ClaudeAgentModel;
import org.springaicommunity.agents.claude.ClaudeAgentOptions;

public class HelloAgent {
    public static void main(String[] args) {
        ClaudeAgentOptions options = ClaudeAgentOptions.builder()
            .model("claude-sonnet-4-5")
            .yolo(true)
            .build();

        ClaudeAgentModel model = ClaudeAgentModel.builder()
            .defaultOptions(options)
            .build();

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

        System.out.println("Success: " + response.isSuccessful());
    }
}

Codex

import org.springaicommunity.agents.client.AgentClient;
import org.springaicommunity.agents.client.AgentClientResponse;
import org.springaicommunity.agents.codex.CodexAgentModel;
import org.springaicommunity.agents.codex.CodexAgentOptions;
import org.springaicommunity.agents.codex.CodexClient;

public class HelloAgent {
    public static void main(String[] args) {
        CodexAgentOptions options = CodexAgentOptions.builder()
            .model("gpt-5-codex")
            .skipGitCheck(true)
            .build();

        CodexAgentModel model = new CodexAgentModel(
            CodexClient.create(), options, null
        );

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

        System.out.println("Success: " + response.isSuccessful());
    }
}

Gemini

import org.springaicommunity.agents.client.AgentClient;
import org.springaicommunity.agents.client.AgentClientResponse;
import org.springaicommunity.agents.gemini.GeminiAgentModel;
import org.springaicommunity.agents.gemini.GeminiAgentOptions;
import org.springaicommunity.agents.geminisdk.GeminiClient;

public class HelloAgent {
    public static void main(String[] args) {
        GeminiAgentOptions options = GeminiAgentOptions.builder()
            .model("gemini-2.5-flash")
            .yolo(true)
            .build();

        GeminiAgentModel model = new GeminiAgentModel(
            GeminiClient.create(), options, null
        );

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

        System.out.println("Success: " + response.isSuccessful());
    }
}

3. Run It

mvn compile exec:java -Dexec.mainClass="HelloAgent"

The agent will create hello.txt in your working directory.

With Spring Boot

If you’re building a Spring Boot application, use the starter dependencies instead. They auto-configure the AgentApi and provide an injectable AgentClient.Builder:

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

@Component
public class MyAgentRunner implements CommandLineRunner {

    private final AgentClient.Builder agentClientBuilder;

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

    @Override
    public void run(String... args) {
        AgentClient client = agentClientBuilder.build();
        AgentClientResponse response = client.run("Create hello.txt");
        System.out.println("Success: " + response.isSuccessful());
    }
}

Configuration goes in application.yml:

agent-client:
  claude:
    model: claude-sonnet-4-5
    yolo: true

Next Steps

• Switching Providers — Run the same task with different providers
• Structured Output — Get structured JSON responses from agents
• Configuration Reference — All available configuration options
• Tutorial: First Task — Step-by-step walkthrough with verification