Getting Started

This guide will help you get started with Spring AI Agents in under 5 minutes.

1. Prerequisites

Before you begin, ensure you have the following:

  • Java 17 or higher

  • Maven 3.6.3 or higher

  • An agent CLI tool installed (Claude Code, Gemini CLI, or SWE Agent)

  • API keys for your chosen agent provider

2. Installing Agent CLI Tools

2.1. Claude Code CLI

Install Claude Code from NPM:

npm install -g @anthropic-ai/claude-code

Set your API key:

export ANTHROPIC_API_KEY="your-api-key-here"

Get your API key from the Anthropic Console.

2.2. Gemini CLI

Install Gemini CLI from NPM:

npm install -g @google/generative-ai-cli

Set your API key:

export GEMINI_API_KEY="your-api-key-here"

3. Adding the Library to Your Project

3.1. Maven

Add the following dependencies to your pom.xml:

<dependencies>
    <!-- Core AgentClient API -->
    <dependency>
        <groupId>org.springaicommunity.agents</groupId>
        <artifactId>spring-ai-agent-client</artifactId>
        <version>0.1.0-SNAPSHOT</version>
    </dependency>

    <!-- Choose your agent provider -->
    <dependency>
        <groupId>org.springaicommunity.agents</groupId>
        <artifactId>spring-ai-claude-code</artifactId>
        <version>0.1.0-SNAPSHOT</version>
    </dependency>
</dependencies>

3.2. Gradle

Add the following dependencies to your build.gradle:

dependencies {
    implementation 'org.springaicommunity.agents:spring-ai-agent-client:0.1.0-SNAPSHOT'
    implementation 'org.springaicommunity.agents:spring-ai-claude-code:0.1.0-SNAPSHOT'
}

4. Quick Start Example

Here’s a simple example using Spring AI Agents with Claude Code:

import org.springaicommunity.agents.client.AgentClient;
import org.springaicommunity.agents.client.AgentClientResponse;
import org.springaicommunity.agents.claudecode.ClaudeCodeAgentModel;
import org.springaicommunity.agents.claudecode.ClaudeCodeAgentOptions;
import org.springaicommunity.agents.claudecode.sdk.ClaudeCodeClient;

public class HelloAgentWorld {
    public static void main(String[] args) {
        // 1. Create the Claude Code client
        ClaudeCodeClient claudeClient = ClaudeCodeClient.create();

        // 2. Configure agent options
        ClaudeCodeAgentOptions options = ClaudeCodeAgentOptions.builder()
            .model("claude-sonnet-4-0")
            .yolo(true) // Allow agent to make changes
            .build();

        // 3. Create the agent model
        ClaudeCodeAgentModel agentModel = new ClaudeCodeAgentModel(claudeClient, options);

        // 4. Create the AgentClient
        AgentClient agentClient = AgentClient.create(agentModel);

        // 5. Run a simple goal
        AgentClientResponse response = agentClient.run(
            "Create a simple Hello World Java class in a file called HelloWorld.java"
        );

        // 6. Get the result
        System.out.println("Agent completed the goal:");
        System.out.println(response.getResult());
        System.out.println("Success: " + response.isSuccessful());
    }
}

5. Understanding the Example

Let’s break down what happened in the example:

  1. Client Creation: We created a ClaudeCodeClient to communicate with the Claude CLI (uses current directory by default)

  2. Agent Options: We configured the agent with a model and enabled "yolo" mode (allows modifications)

  3. Agent Model: We wrapped the client in a ClaudeCodeAgentModel for Spring AI integration

  4. AgentClient: We created an AgentClient - the main API for running tasks

  5. Goal Execution: We ran a goal using the simple .run() method

  6. Result Access: We got the result using .getResult() and checked success

6. Spring Boot Integration

For Spring Boot applications, you can use dependency injection:

@RestController
public class AgentController {

    private final AgentClient agentClient;

    public AgentController(ClaudeCodeAgentModel agentModel) {
        this.agentClient = AgentClient.create(agentModel);
    }

    @PostMapping("/execute-goal")
    public String executeTask(@RequestBody String goal) {
        AgentClientResponse response = agentClient.run(goal);
        return response.getResult();
    }
}

@Configuration
public class AgentConfiguration {

    @Bean
    public ClaudeCodeAgentModel claudeAgentModel() {
        ClaudeCodeClient client = ClaudeCodeClient.create();
        ClaudeCodeAgentOptions options = ClaudeCodeAgentOptions.builder()
            .model("claude-sonnet-4-0")
            .build();
        return new ClaudeCodeAgentModel(client, options);
    }
}

7. Next Steps

Now that you have a basic agent running, explore:

8. Troubleshooting

Agent not found: Make sure you’ve installed the CLI tool (npm install -g @anthropic-ai/claude-code) and it’s in your PATH.

API key issues: Verify your environment variable is set correctly and your API key is valid.

Permission denied: Make sure the agent has access to your working directory and consider using yolo(true) for development.

For more help, see our Contribution Guidelines for community support options.