Sagacity¶
Human oversight and audit for Spring AI agents. Pause before irreversible actions. Approve or reject. Unwind automatically. Every decision tamper-evident.
Your AI agents are making decisions that affect real people — approving transactions, sending emails, charging cards, updating records. Right now:
- nobody approved the irreversible action before it ran
- nothing undoes completed steps when something later fails
- there is no compliance-grade record of what happened, in what order, who approved what
- there is no answer when legal asks "can you prove your AI didn't act without authorisation?"
Sagacity is the governance layer that sits between your Spring AI agent and the actions it takes — inside your existing Spring Boot app, with no new infrastructure.
Annotate your tools¶
Drop @Compensable on any Spring AI @Tool method. Sagacity intercepts every call,
journals it with a SHA-256 hash chain, and runs compensation in reverse if anything
fails downstream. No new infrastructure. No restructuring of your agent.
Human approval gates¶
Mark a tool as IRREVERSIBLE and the agent pauses before it executes. Resume via REST,
the embedded UI, or programmatically. The approval is bound to the exact input the
approver saw — a re-planning agent cannot substitute a different payload.
Two minutes to understand the shape
Annotate your tools, run inside a saga¶
Drop @Compensable on any Spring AI @Tool method. Sagacity intercepts every call,
journals it, and compensates on failure. One line change to how you run your agent.
@Tool(description = "Charge the customer")
@Compensable(by = "refundCharge")
public String chargeCard(String amount, String customerId) {
return payments.charge(customerId, amount); // returns "ch_1M2n3"
}
@Compensation
public void refundCharge(CompensationContext ctx) {
payments.refund(ctx.result()); // ctx.result() = "ch_1M2n3"
}
// Run your agent inside a saga — one line change
SagaResult<ChatResponse> result = sagacity.saga("order-123", () ->
chatClient.prompt()
.user("Place order for customer C-991")
.toolCallbacks(sagacity.wrap(orderTools)) // ← wrap your tools
.call().chatResponse());
// If chargeCard succeeded but a later step failed:
// → refundCharge runs automatically
// → every step is journaled with a SHA-256 hash chain
The distinction that matters
How Sagacity relates to Temporal¶
Temporal is infrastructure. It solves durable execution — if your process crashes, your workflow replays from exactly where it stopped. It also handles distributed workers, cross-service orchestration, and horizontal scale. Temporal just raised $550M and ships a Spring AI integration (temporal-spring-ai) that makes model calls and tool executions durable activities. It is serious, production-grade infrastructure.
That is not the same problem Sagacity solves.
A workflow that resumes perfectly after a crash still leaves you with: - A charged card when the business logic says the order should be abandoned - An inventory reservation nobody will ever release - An email already sent to a customer about a transaction that failed
Crash recovery cannot undo a side effect. A refund is not a retry.
Sagacity answers a different question: when your agent succeeds technically but the business says "this should not have happened," what gets unwound, who approved it before it ran, and what is the tamper-evident record?
| Temporal | Sagacity | |
|---|---|---|
| Durable execution (survive process crash) | ✅ cluster-backed | ❌ v0.4 adds JDBC state, not the same |
| Distributed workers, horizontal scale | ✅ | ❌ single JVM |
| Spring AI native integration | ✅ temporal-spring-ai (Preview) |
✅ sagacity-spring-boot-starter |
| Undo side effects on business failure | ⚠️ possible via child workflow pattern | ✅ @Compensable — first-class, annotation-driven |
| Tamper-evident SHA-256 audit trail | ❌ event history is operational, not compliance-grade | ✅ append-only, hash-chained, verifiable |
| EU AI Act Article 12 compliance | ❌ | ✅ |
| Human approval gates before irreversible actions | ❌ | ✅ @Gate(approvalRequired=true) |
| New infrastructure to run | ✅ cluster or Temporal Cloud (~$200+/month) | ❌ library — add a dependency |
| Adopt without rewriting agent code | ❌ must model everything as Workflows + Activities | ✅ annotate existing Spring AI tools |
They are complementary. A production system could use both — Temporal for durability and scale, Sagacity for compensation semantics, approval gates, and the compliance audit trail. The things Temporal's event history records and the things Sagacity's hash-chained journal records serve different audiences: Temporal's history is for engineers debugging a stuck workflow; Sagacity's journal is for compliance officers proving what an AI agent did, in what order, and who approved it.
Install
Add the dependency¶
<!-- Core: compensation + audit trail -->
<dependency>
<groupId>io.github.sumitvairagar</groupId>
<artifactId>sagacity-spring-boot-starter</artifactId>
<version>0.4.0</version>
</dependency>
<!-- Optional: declarative workflow engine -->
<dependency>
<groupId>io.github.sumitvairagar</groupId>
<artifactId>sagacity-workflows</artifactId>
<version>0.4.0</version>
</dependency>
Requires Java 17+, Spring AI 2.0.0, Spring Boot 4.0.x.
Spring Boot 4 is required, not optional
Spring AI 2.0.0 compiles against Spring Framework 7. Spring Boot 3.5.x
resolves Spring Framework 6.2 and will downgrade spring-core underneath
Spring AI, failing at runtime with
NoClassDefFoundError: org/springframework/core/Nullness.
Before you rely on it
Status¶
0.4.0 ships durable JDBC-backed workflow state — runs survive JVM restarts, gates stay
open across deploys. The compensation, approval, audit, and workflow paths are covered by
237 tests across unit and integration suites, but the library has not been
battle-tested in production by anyone yet.
Read the threat model before relying on the audit trail for anything that matters.
Known gaps: no streaming tool-call support, no LangChain4j adapter. See the roadmap.