Hello World: Your First Agent Task

Spring AI Agents provides a fluent API for executing autonomous agent tasks. Let’s start with the simplest possible example.

Prerequisites

Add the Spring AI Claude Agent starter to your pom.xml:

<dependency>
    <groupId>org.springaicommunity.agents</groupId>
    <artifactId>spring-ai-starter-agent-claude</artifactId>
    <version>0.1.0-SNAPSHOT</version>
</dependency>

This starter includes everything you need: AgentClient, Claude integration, and Judge support.

Authentication: Run claude auth login or set the ANTHROPIC_API_KEY environment variable.

Your First Agent Task

import org.springframework.boot.CommandLineRunner;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.Bean;
import org.springaicommunity.agents.advisors.judge.JudgeAdvisor;
import org.springaicommunity.agents.client.AgentClient;
import org.springaicommunity.agents.client.AgentClientResponse;
import org.springaicommunity.agents.judge.fs.FileExistsJudge;
import org.springaicommunity.agents.judge.result.Judgment;

import java.nio.file.Path;

@SpringBootApplication
public class HelloWorldApplication {

    public static void main(String[] args) {
        SpringApplication.run(HelloWorldApplication.class, args);
    }

    @Bean
    CommandLineRunner demo(AgentClient.Builder agentClientBuilder) {
        return args -> {
            AgentClientResponse response = agentClientBuilder.build()
                .goal("Create a file named hello.txt with content 'Hello World'")
                .workingDirectory(Path.of(System.getProperty("user.dir")))
                .advisors(JudgeAdvisor.builder().judge(new FileExistsJudge("hello.txt")).build())
                .run();

            Judgment judgment = response.getJudgment();
            System.out.println("Agent completed!");
            System.out.println("Result: " + response.getResult());
            System.out.println("Judge: " + (judgment != null && judgment.pass() ? "PASSED" : "FAILED"));
        };
    }
}

What Just Happened?

Let’s break down what the agent did:

  1. Goal - We specified what we want: "Create a file named hello.txt with content 'Hello World'"

  2. Working Directory - The agent operates in the current directory (user.dir)

  3. Judge Advisor - We added a FileExistsJudge to verify the file was created

  4. Agent Execution - Claude Code autonomously:

    • Created hello.txt in the working directory

    • Wrote "Hello World" to the file

  5. Verification - The judge verified the file exists and returned a passing judgment

  6. Response - We received the agent’s final output and judge verdict

Verify It Worked

Check that the file was created in your current directory:

$ cat hello.txt
Hello World

The agent successfully completed your goal!

Key Concepts

Goal-Driven Execution

You specify what you want, not how to do it.

// ❌ Traditional approach: specify HOW (imperative)
Files.createDirectories(path);
Files.writeString(path.resolve("hello.txt"), "Hello World");

// ✅ Agent approach: specify WHAT (declarative)
agentClientBuilder.build()
    .goal("Create a file named hello.txt with content 'Hello World'")
    .workingDirectory(path)
    .run();

Autonomous Execution

The agent figures out the steps needed to achieve your goal. It might:

  • Check if the directory exists

  • Create it if needed

  • Determine the best way to create the file

  • Write the content

  • Verify the result

You don’t write the steps—the agent does.

Understanding the AgentClient Fluent API

The AgentClient provides a clean fluent API for configuring agent tasks:

Method Purpose

goal(String)

Required. The objective you want the agent to achieve.

workingDirectory(Path)

Required. The directory where the agent will operate (file operations are scoped here).

advisors(AgentCallAdvisor…​)

Optional. Add advisors to verify, log, or augment agent execution (e.g., judges).

run()

Execute the agent task and return the response.

The fluent chain makes it easy to build up your agent request step by step.

Spring Boot autoconfiguration handles everything automatically:

  • AgentClient.Builder bean (prototype scope)

  • Claude agent (model: claude-sonnet-4.5, yolo: true)

  • LocalSandbox for secure execution

No manual configuration required!

Next Steps

Now that you understand basic agent execution, learn how to:

You just used a CLI agent! Claude Code executed commands autonomously in your environment. Learn more about this in CLI Agents.