CLI Agents: The Foundation

CLI agents are the foundation of Spring AI Agents. Understanding what they are and how they work is essential to using this framework effectively.

What Are CLI Agents?

CLI (Command-Line Interface) agents are autonomous AI systems that interact with your development environment through command-line tools. Unlike chatbots or code completion tools, CLI agents can:

  • Execute shell commands - Run builds, tests, git operations, etc.

  • Read and write files - Navigate codebases, create/modify files

  • Iterate until complete - Keep working until the goal is achieved

  • Make decisions - Choose which commands to run based on results

  • Operate autonomously - No human intervention during execution

Think of a CLI agent as a developer who works through the terminal—but powered by AI.

Anthropic’s Vision: Building Agents with the Claude Agent SDK

In their engineering blog post Building Agents with the Claude Agent SDK (renamed from "Claude Code SDK" in September 2025 to reflect broader applications beyond coding), Anthropic describes the architecture of agentic CLI tools:

The agent loop is: gather context → take action → verify work → repeat. The agent writes files, runs commands, and iterates on its work until the goal is achieved.
— Anthropic Engineering Blog

Key Principles from Anthropic

The Anthropic blog outlines four foundational principles:

1. Tool-Calling Loop

Agents iterate through a cycle:

Think → Act → Observe → Repeat

1. THINK: Agent analyzes the goal and current state
2. ACT: Agent decides which tool/command to execute
3. OBSERVE: Agent sees the result of the action
4. REPEAT: Loop until goal is achieved

Example iteration:

Goal: "Fix the failing test in UserServiceTest"

Iteration 1:
  THINK: Need to see what test is failing
  ACT: Run "mvn test"
  OBSERVE: UserServiceTest.testCreateUser fails with NPE

Iteration 2:
  THINK: NPE suggests null email field
  ACT: Read UserService.java source
  OBSERVE: createUser() doesn't validate email

Iteration 3:
  THINK: Add null check before using email
  ACT: Modify UserService.java to add validation
  OBSERVE: File modified successfully

Iteration 4:
  THINK: Verify the fix works
  ACT: Run "mvn test" again
  OBSERVE: All tests pass ✓

Goal achieved!

2. Workspace Isolation

Agents operate in well-defined workspaces with clear boundaries:

  • Sandboxed execution - Agents don’t have unrestricted system access

  • Scoped file operations - File operations are limited to the workspace

  • Controlled permissions - Explicit permissions for sensitive operations

Spring AI Agents implements this through:

agentClientBuilder
    .goal("Create a REST API")
    .workingDirectory(Path.of("/projects/my-api"))  // ← Workspace boundary
    .call();

3. Goal-Driven Execution

Agents have clear objectives that guide their behavior:

// ✅ Clear goal
"Add a GET /users endpoint that returns JSON"

// ❌ Vague instruction
"Make the API better"

The goal is the what, not the how. The agent figures out the steps.

4. Built-in Verification

Agents verify their own work:

  • Check if files were created

  • Run tests to validate changes

  • Verify build success

  • Confirm deployment readiness

Spring AI Agents extends this with the Judge API:

agentClientBuilder
    .goal("Fix the failing tests")
    .advisors(JudgeAdvisor.builder()
        .judge(new BuildSuccessJudge())  // ← Verify tests pass
        .build())
    .call();

Why Many CLI Agents Exist

We are in the age of agent exploration. The CLI agent ecosystem is diverse because there isn’t a single right answer for all use cases—and Spring AI Agents embraces this reality.

The Agent Landscape is Maturing

Right now, the question is: "Can an agent achieve my goal?"

As the landscape matures, the question will shift to: "What’s the cheapest way to achieve my goal?"

This means considering:

  • Model selection - Different models have different costs and capabilities

  • Vendor independence - Avoid lock-in, have a Plan B if your preferred model becomes unavailable

  • Simple hand-coded agents - Sometimes a custom script using your preferred stack is the right answer

  • Hybrid approaches - Use LLM agents for complex tasks, simple automation for routine ones

Agent Diversity

Different agents excel at different tasks:

Agent Strengths Use Cases

Claude Code

Advanced reasoning, multi-step planning, code understanding

Complex refactoring, architectural changes, bug fixes

Gemini CLI Agent SDK

Multimodal capabilities, fast execution, Google integration

Document analysis, image processing, quick tasks

SWE-Agent

Research-focused, benchmark-optimized, academic rigor

SWE-bench evaluation, research projects

Custom Agents

Domain-specific, hand-written logic, company-specific workflows

Internal tools, proprietary systems, specialized tasks

Spring AI Agents is not a CLI agent implementation. It’s a framework for integrating any CLI agent into Spring Boot applications with familiar Spring patterns. This gives you the flexibility to choose the right agent for each task and switch between them as the landscape evolves.

LLM as Workflow Engine

This is a fundamental shift in how we think about automation.

Traditional Workflow Engines

Traditional approaches use code to define workflows:

// ❌ Traditional: You write the workflow logic
public void fixAndDeploy() {
    boolean buildSucceeds = runBuild();
    if (!buildSucceeds) {
        return; // Give up
    }

    boolean testsPass = runTests();
    if (!testsPass) {
        return; // Give up
    }

    if (buildSucceeds && testsPass) {
        deploy();
    }
}

Problems:

  • Rigid - Can’t adapt to unexpected situations

  • Limited - Only handles predefined scenarios

  • Brittle - Breaks when environment changes

LLM-Based Workflow Engines

CLI agents use the LLM as the workflow engine:

// ✅ Agent: LLM decides the workflow
Goal: "Fix the failing tests and deploy"

Agent reasoning (dynamic):
1. Run tests → Some tests fail
2. Analyze failures → NPE in UserService
3. Read UserService code → Missing null check
4. Fix the null check → Code modified
5. Run tests again → Tests pass ✓
6. Run build → Build succeeds ✓
7. Deploy → Deployment successful ✓

The LLM adapts the workflow based on what it observes:

  • If tests fail → analyze and fix

  • If build breaks → investigate and repair

  • If deployment fails → retry with adjustments

No predefined workflow—the agent figures it out.

Spring AI Integration

Spring AI Agents provides a Spring-idiomatic way to work with CLI agents:

Unified Abstraction

The AgentModel interface abstracts any CLI agent:

┌─────────────────────┐
│   AgentClient       │  Your Spring Boot app
│   (Fluent API)      │
└──────────┬──────────┘
           │
           ▼
┌─────────────────────┐
│   AgentModel        │  Abstraction layer
│   (Interface)       │
└──────────┬──────────┘
           │
    ┌──────┴──────┬──────────────┬──────────────┐
    ▼             ▼              ▼              ▼
┌────────┐  ┌─────────┐  ┌──────────┐  ┌──────────┐
│ Claude │  │ Gemini  │  │SWE-Agent │  │  Custom  │
└────────┘  └─────────┘  └──────────┘  └──────────┘

You write code against AgentClient, not a specific agent.

Fluent API

Following Spring AI’s ChatClient pattern:

// Mirrors ChatClient fluent API
AgentClientResponse response = agentClientBuilder
    .goal("Create a REST API")           // Like ChatClient.prompt()
    .workingDirectory(projectRoot)       // Workspace context
    .advisors(judgeAdvisor)              // Like ChatClient.advisors()
    .call();                             // Like ChatClient.call()

Spring Boot Auto-Configuration

Zero-configuration for common agents:

// Just add dependency + API key
// Spring Boot auto-configures everything

@Service
public class MyService {

    private final AgentClient.Builder agentClientBuilder;

    // Auto-wired by Spring Boot ✓
    public MyService(AgentClient.Builder agentClientBuilder) {
        this.agentClientBuilder = agentClientBuilder;
    }
}

Production Patterns

Built-in support for:

  • Goals - Clear, measurable objectives

  • Context Engineering - Providing information to agents

  • Judges - Automated verification

  • Sandboxes - Safe execution environments

  • Advisors - Extensible plugin architecture

Building Your Own Agent vs Using CLI Agents

Both approaches fundamentally implement "LLM in a loop"—but with different trade-offs:

Aspect Build Your Own (Spring AI @Tool/MCP) Use CLI Agents (Spring AI Agents)

Control

Complete - you write the tools

Delegated - agent provider handles tools

Development Effort

High - build and maintain tools

Low - integrate pre-built agents

Flexibility

Custom tools for specific needs

General-purpose development tasks

Investment

Your team’s R&D

Anthropic, Google, Amazon, OpenAI R&D

Tool Scope

Methods you explicitly code

Full bash/CLI access

Best For

Domain-specific workflows, custom integrations

General development, rapid adoption

Spring AI supports both approaches:

  • @Tool annotations + MCP: Build custom agent loops (Spring AI MCP support)

  • CLI agents: Integrate production-ready agents (Spring AI Agents library)

Use what fits your needs. Combine both when appropriate.

CLI Agents vs Other AI Tools

Understanding where CLI agents fit in the broader AI ecosystem:

Tool Type What It Does Example

Code Completion

Suggests next lines/blocks

GitHub Copilot, Cursor

Chatbots

Answers questions, generates code

ChatGPT, Claude Chat

Annotation-Based Agents

Predefined tool calling in conversation

LangChain4j, Spring AI @Tool

CLI Agents

Autonomous bash execution

Claude Agent SDK, Gemini CLI Agent SDK

Workflow Engines

Orchestrates predefined steps

Airflow, Temporal

CLI agents are unique because they:

  • ✅ Execute real bash commands (not just predefined Java methods)

  • ✅ Iterate until complete (not one-shot responses)

  • ✅ Adapt dynamically (not predefined workflows)

  • ✅ Have full computer access (bash, file system, git)

Example: CLI Agent in Action

Let’s see a CLI agent solve a real problem:

Goal: "Upgrade Spring Boot from 2.7 to 3.2 and fix any breaking changes"

Agent execution (Claude Code):

Iteration 1:
  $ grep -r "spring-boot" pom.xml
  Found: <version>2.7.0</version>

Iteration 2:
  $ sed -i 's/2.7.0/3.2.0/g' pom.xml
  Updated pom.xml

Iteration 3:
  $ mvn clean compile
  ERROR: javax.* packages removed in Spring Boot 3

Iteration 4:
  $ find src/ -name "*.java" | xargs grep "javax\."
  Found 15 files using javax.servlet.*

Iteration 5:
  $ find src/ -name "*.java" | xargs sed -i 's/javax.servlet/jakarta.servlet/g'
  Updated imports in 15 files

Iteration 6:
  $ mvn clean test
  All tests pass ✓

Goal achieved!

The agent:

  1. Found the Spring Boot version

  2. Updated the version

  3. Discovered breaking changes

  4. Found affected files

  5. Fixed the imports

  6. Verified with tests

All autonomously. No human intervention.

When to Use CLI Agents

CLI agents excel at:

  • ✅ Multi-step development tasks - Refactoring, migrations, bug fixes

  • ✅ Exploratory work - "Find and fix all SQL injection vulnerabilities"

  • ✅ Repetitive tasks - "Update all deprecated API usages"

  • ✅ Build/test automation - "Fix failing tests and deploy"

  • ✅ Code generation - "Create CRUD API for User entity"

CLI agents are less suitable for:

  • ❌ Real-time interactions - Use chatbots instead

  • ❌ Code completion - Use Copilot/Cursor instead

  • ❌ Simple lookups - Use vector search/RAG instead

  • ❌ Predefined workflows - Use workflow engines instead

Next Steps

Now that you understand the foundation, explore how to use CLI agents effectively:

Further Reading