Javaclaw: A Spring-Native Framework for Enterprise-Grade Secure Agent Workflows

This article introduces the Javaclaw project, a Java Agent runtime framework built on Spring Boot and Spring AI. It provides enterprise-grade security features such as a policy engine, approval gating, and full audit trails, enabling development teams to safely deploy LLM-driven intelligent workflows in production environments.

With the continuous improvement of Large Language Model (LLM) capabilities, more and more enterprises are exploring the application of AI Agents in production environments. However, unlike traditional software, AI Agents have autonomous decision-making and execution capabilities, which bring unique security and governance challenges:

• Unpredictability: Agents may generate unexpected tool calls or operation sequences
• Blurred permission boundaries: Which resources do Agents need to access? How to limit their operation scope?
• Lack of auditability: The decision-making process of Agents is often a black box, making it difficult to trace and review
• No control over risky operations: High-risk operations (such as database writing, command execution) lack manual approval mechanisms

These challenges make many enterprises hesitant to deploy AI Agents to production environments despite recognizing their potential. The Javaclaw framework was created to address these issues.

Javaclaw is a lightweight Agent runtime framework based on the Spring ecosystem, designed specifically for enterprise scenarios requiring strict governance. It is built on Spring AI, fully leveraging modern features of Spring Boot 3.4 and Java 21, and uses the Apache 2.0 open-source license.

The core idea of the project is: while providing powerful AI Agent capabilities, ensure every operation is within controllable limits through the policy engine, approval gating, and audit trails.

Javaclaw's policy engine allows administrators to configure independent execution policies for each tool and each Agent. Policy decisions have three outcomes:

• ALLOW: Allow execution without additional approval
• DENY: Reject execution; the tool is unavailable for this Agent
• REQUIRE_APPROVAL: Require manual approval before execution

This fine-grained control mechanism enables enterprises to flexibly configure the permission boundaries of Agents according to business scenarios and risk preferences. For example, the code search tool can be set to ALLOW, while the database writing tool can be set to REQUIRE_APPROVAL.

For tool calls marked as REQUIRE_APPROVAL, Javaclaw will pause the task before execution and wait for manual approval. The approval request includes the following information:

• Tool name and input parameters
• Risk level assessment (HIGH/MEDIUM/LOW)
• Explanation of the reason for triggering approval

Approvers can view the list of pending approval tasks via REST API and choose to approve or reject. After approval, the task automatically resumes execution; if rejected, the task enters the CANCELLED state. This design ensures that high-risk operations do not execute automatically without manual confirmation.

Javaclaw maintains a complete audit log for each Agent task, recording the following events:

• TASK_CREATED: Task creation, recording the initial goal
• TASK_STARTED: Task execution start, recording the Agent configuration used
• POLICY_CHECK: Policy check, recording the tool name and decision result
• TOOL_EXECUTED: Tool execution, recording input parameters and return results
• APPROVAL_REQUESTED: Approval request, recording details of the operation to be approved
• APPROVAL_RESOLVED: Approval resolution, recording the approval result and reason
• TASK_COMPLETED / TASK_FAILED / TASK_CANCELLED: Task final state

This end-to-end audit capability not only meets compliance requirements but also provides a data foundation for problem troubleshooting and system optimization.

Javaclaw adopts a clear layered architecture:

Entry Layer: Supports two access methods: REST API and Slack Bot. REST API is suitable for system integration, while Slack Bot is suitable for interactive scenarios.

Runtime Layer: Implements the Agent's execution loop (think → act → observe), manages task status and tool calls.

Tool Layer: Built-in common tools (file reading, code search, command execution, GitHub operations, etc.), supports custom tool extensions.

Policy Layer: The policy engine checks each tool call and makes decisions based on configuration rules.

AI Layer: Connects to underlying LLMs (OpenAI, Anthropic, Ollama, etc.) via Spring AI.

Javaclaw's Agent execution follows the classic ReAct pattern:

1. Think: The LLM analyzes the current state and decides the next action
2. Act: Call the selected tool and obtain the execution result
3. Observe: Feed the observation results back to the LLM and update the state
4. Loop until the task is completed or the maximum step limit is reached

Each step's tool call goes through the policy engine check to ensure compliance with security policies.