Skip to main content

​
Overview

The Claude agent wraps the Claude Code CLI via ClaudeAgentModel. Configure it through Spring properties under agent-client.claude.*. 
agent-client:
  claude:
    model: claude-sonnet-4-5
    timeout: PT5M
    yolo: true

​
Configuration Properties

Prefix: agent-client.claude
PropertyTypeDefaultDescription
modelStringclaude-sonnet-4-5Claude model to use for agent tasks
timeoutDuration5mTimeout for agent task execution
yolobooleantrueBypass all permission checks
executable-pathString—Path to the Claude CLI executable (auto-discovered if not set)
effortString—Reasoning effort level (--effort): low, medium, high, xhigh, max. Overrides the portable effort when both are set
max-thinking-tokensInteger—Maximum thinking tokens for extended thinking mode
system-promptString—System prompt to use for the agent
allowed-toolsList<String>[]Tools that are allowed to be used
disallowed-toolsList<String>[]Tools that are not allowed to be used
permission-modeString—Permission mode for tool execution (overrides yolo if set)
json-schemaMap<String,Object>—JSON schema for structured output
max-tokensInteger—Maximum tokens for the response
max-turnsInteger—Maximum number of agentic turns before stopping
max-budget-usdDouble—Maximum budget in USD before stopping
fallback-modelString—Fallback model if the primary model is unavailable
append-system-promptString—Additional text appended to the default system prompt

​
Advanced Options

These options provide full parity with the Claude Code Python SDK:
PropertyTypeDefaultDescription
add-dirsList<String>[]Additional directories to include in Claude’s context
settingsString—Custom settings file path
permission-prompt-tool-nameString—Permission prompt tool name for interactive permission handling
extra-argsMap<String,String>—Arbitrary extra CLI arguments (keys are flag names without --)
envMap<String,String>—Custom environment variables for the CLI process
max-buffer-sizeInteger—Maximum buffer size for JSON parsing in bytes (default 1MB)
userString—Unix user to run the CLI process as (requires sudo configuration)
trace-dirString—Directory for JSONL trace files. Each invocation writes one file.

​
Permission Modes

The permission-mode property overrides yolo when set. Available modes:
ModeDescription
bypassPermissionsSkip all permission checks (equivalent to yolo=true)
defaultUse Claude Code’s default permission behavior
agent-client:
  claude:
    permission-mode: bypassPermissions
    # yolo is ignored when permission-mode is set

​
Tool Filtering

Control which tools Claude can use: 
agent-client:
  claude:
    allowed-tools:
      - Read
      - Write
      - Bash
    disallowed-tools:
      - WebSearch
allowed-tools and disallowed-tools are mutually exclusive in practice. If both are set, allowed-tools takes precedence.

​
Budget Controls

Limit agent execution costs and turns: 
agent-client:
  claude:
    max-turns: 10           # Stop after 10 agentic turns
    max-budget-usd: 0.50    # Stop after $0.50 spent
    max-tokens: 4096        # Limit response tokens

​
Structured Output

Request structured JSON output using a JSON schema: 
agent-client:
  claude:
    json-schema:
      type: object
      properties:
        summary:
          type: string
        files_changed:
          type: array
          items:
            type: string

​
Trace Files

Enable JSONL trace output to capture tool calls, thinking blocks, and result metrics per invocation: 
agent-client:
  claude:
    trace-dir: /path/to/traces
Each call() writes one file like agent-run-20260528-143000-123-a1b2c3d4.jsonl containing Claude-specific events (tool_use, tool_result, text, thinking, result). The file path is available in the response metadata: 
String tracePath = (String) response.getMetadata().getProviderFields().get("tracePath");
Or via the builder API: 
ClaudeAgentModel model = ClaudeAgentModel.builder()
    .traceDir(Path.of("traces"))
    .build();
Trace files are flushed per event during parsing, so you can tail -f them during long-running sessions. When used with Agent Workflow, trace paths propagate automatically through the workflow journal.
These are Claude-specific JSONL traces, not provider-neutral journal events. See Agent Journal for the portable event layer.

​
Authentication