Unlock Java Power with Claude Agent SDK: From One‑Shot to Reactive APIs

Claude Code as a General‑Purpose AI Agent

Claude Code is not a simple code‑completion tool. It runs as an autonomous agent that uses the file system for context, the terminal for interaction, and the operating system as its execution environment. This design enables it to plan multi‑step workflows, invoke tools, handle errors, and achieve high‑level goals without continuous human supervision.

Core Agent Capabilities

High autonomy : Executes tasks end‑to‑end, iterating until the objective is satisfied.

Deep environment interaction : Reads and writes files, runs shell commands, searches code bases, calls APIs, and executes tests.

Complex goal handling : Understands objectives that span databases, APIs, front‑ends, and testing pipelines.

Claude Agent SDK and Language Support

The official Claude Agent SDK (formerly Claude Code SDK) provides programmatic control, session management, tool extensions, and permission hooks. It currently supports only Python and TypeScript, leaving Java developers without a native client.

Java Implementation of Claude Agent SDK

The Spring AI community released a pure‑Java SDK that mirrors the official design, allowing Java applications to drive Claude Code.

<repositories>
  <repository>
    <id>central-snapshots</id>
    <url>https://central.sonatype.com/repository/maven-snapshots/</url>
    <snapshots>
      <enabled>true</enabled>
    </snapshots>
  </repository>
</repositories>

<dependencies>
  <dependency>
    <groupId>org.springaicommunity</groupId>
    <artifactId>claude-code-sdk</artifactId>
    <version>1.0.0‑SNAPSHOT</version>
  </dependency>
</dependencies>

API Styles

1. One‑Shot API (single call)

import org.springaicommunity.claude.agent.sdk.Query;

String answer = Query.text("What is 2+2?");
System.out.println(answer); // "4"

Custom options can be supplied via QueryOptions:

String answer = Query.text(
    "Explain quantum computing",
    QueryOptions.builder()
        .model("claude‑sonnet‑4‑20250514")
        .appendSystemPrompt("Be concise")
        .timeout(Duration.ofMinutes(5))
        .build()
);

2. Blocking (synchronous) API

try (ClaudeSyncClient client = ClaudeClient.sync()
        .workingDirectory(Path.of("."))
        .model("claude‑sonnet‑4‑20250514")
        .build()) {
    String answer = client.connectText("What is 2+2?");
    System.out.println(answer); // "4"
    String followUp = client.queryText("Multiply that by 10");
    System.out.println(followUp); // "40"
}

3. Reactive (non‑blocking) API

ClaudeAsyncClient client = ClaudeClient.async()
    .workingDirectory(Path.of("."))
    .model("claude‑sonnet‑4‑20250514")
    .build();

client.connect("Explain recursion").textStream()
    .doOnNext(System.out::print)
    .subscribe();

client.connect("My favorite color is blue.").text()
    .doOnSuccess(System.out::println)
    .flatMap(r1 -> client.query("What is my favorite color?").text())
    .doOnSuccess(System.out::println)
    .flatMap(r2 -> client.query("Spell it backwards").text())
    .doOnSuccess(System.out::println)
    .subscribe();

Practical Scenario: Retrieval‑Augmented Generation (RAG) over Local Documents

The SDK can be used to build a concise RAG service that searches a directory of documentation and returns answers in the desired language.

public class DocQAService {
    public String answerQuestion(String question) {
        try (ClaudeSyncClient client = ClaudeClient.sync()
                .workingDirectory(Path.of("/path/to/docs"))
                .model("claude‑sonnet‑4‑20250514")
                .build()) {
            return client.connectText(
                "Based on local documents answer the user question: " +
                question + "
Requirements: 1. Search relevant docs 2. Summarize key info 3. Answer in Chinese"
            );
        }
    }
}

Typical execution flow:

User submits a question to the application.

The application creates a ClaudeSyncClient configured with the documentation directory.

Claude Code automatically searches the files, extracts relevant passages, and synthesizes a response.

The generated answer is returned to the caller.

This pattern abstracts away file handling, vector‑store management, and prompt engineering, letting developers focus on business logic while the agent performs the heavy lifting.