---
title: "Building a reliable AI agent with OSCAR"
description: "Learn how to take a Spring AI agent from prototype to production with Temporal, adding durable execution, retries, observability, and human approval."
canonical: "https://temporal.io/blog/building-a-reliable-ai-agent-with-oscar.md"
source: "https://temporal.io/blog/building-a-reliable-ai-agent-with-oscar"
published: "2026-11-18"
authors:
  - "Loïc Ortola"
category: "Community"
tags:
  - "AI/ML"
  - "Java"
  - "Code Samples"
reading_time_minutes: 20
---

# Building a reliable AI agent with OSCAR

|        |
| ---------- |
| *This is a guest post from Loïc Ortola, CTO at Takima*           |
|        |

For thirty years, software has digitized human processes through deterministic rules. A great deal of what used to be done by hand got industrialized into code, and whatever language or tool was used to do it, the result shared the same character: for the same input, you got the same output. Something precise, auditable, and reasonably cost-controlled.

The trade-off for that precision was rigidity. A deterministic system only understands what it was explicitly built to expose, so every adaptation had to happen on the human's side, or be built by hand. The first layer of that cost is the human-machine interface itself: land on a new piece of software, and you have to learn how to interact with it before you can get anything done. The second layer shows up between systems rather than between a system and a person - integrating two applications meant adapting to whichever API each one exposed, and building custom mappers to translate between them. Every new connection was its own project.

That's the rigidity LLMs break. Where a deterministic system needs its input shaped to fit a predefined structure, an LLM can read context that's genuinely messy - unstructured, inconsistent, nothing like the clean interfaces software has always demanded - and still extract what the person on the other end actually wants. AI becomes a bridge over that messy data, able to pull out the underlying intent regardless of the form it arrives in. That's also the real reason "agentic" is suddenly everywhere: AI is changing what an interface to computing even looks like, adapting to the user rather than forcing the user to adapt to it. The agent, as a piece of software, follows directly from that shift.

What follows is a single running example: a customer-support agent for a fictional e-commerce marketplace, built first as a naive prototype and then hardened, step by step, into something that can actually run in production.

## A marketplace, Stripe, and an unhappy customer
Super Marketplace is a small e-commerce back office wired to Stripe for payments: every new order has a matching charge in Stripe. Customers reach support by email. One message: Jane Doe is unhappy with a pair of headphones she ordered and wants a full refund.

Before AI, a human would answer that email directly. The obvious next step is to hand the task to a conversational model instead - paste the email into an LLM, describe the agent's role and the expected reply format, and ask for a draft response. That produces a good reply, fast.

## A draft reply is not a resolution
Drafting a reply is real progress, but a support team is made up of many people, and centralizing that practice means automating it, not just speeding up one person's typing. More importantly, this kind of prompting is completely decoupled from the systems that matter: the back office, and Stripe. Ask the model to also send the email and issue the refund, and the answer is blunt - it is just a language model, and it has no way to act on the company's systems.

That's the real limit, and it's also the argument for an agent instead of a prompt. An agent earns its place when several conditions line up: the input is unstructured or heterogeneous enough that a classic, rules-based system can't parse it; the task requires deciding between several possible actions - refund, ask for more context, escalate to a technical team; it needs to interface with several internal systems at once; the volume or human cost involved is high enough to justify the token cost of running an LLM; and the situation calls for a system that can adapt its own behavior to a variable context rather than follow a fixed script.

![A diagram listing situations where switching to an agent makes sense](https://images.ctfassets.net/0uuz8ydxyd9p/7IwmMRLgl0DeyMYGFNeObb/0467c791fbda43cdbaed877df4c7df96/image3.png){.zoom}

## Meet OSCAR
This support agent is named OSCAR: **O**perator **S**olving **C**omplaints **A**utonomously and **R**eliably. Given a complaint email, OSCAR looks up the relevant order in the backend, switches its status to "refunding," calls Stripe to issue the refund, updates the order status back in the back office, and replies to the customer confirming the resolution.

![A diagram showing the workflow of OSCAR](https://images.ctfassets.net/0uuz8ydxyd9p/5aQLzxD8ALxUhERYgH5B1v/6bdecb1bb414355220e03e45b23b1930/image1.png){.zoom}

## How an agent is built
An LLM - ChatGPT, Gemini, Claude, any of them - is capable of exactly one thing: taking text in and producing text out. On its own, it has no way to check an order or call Stripe. An agent is the layer built around that brain to give it those capabilities: an orchestrator combining a goal (the prompt describing the task), tools (the concrete ways it can act on the outside world), and memory (a sense of where it stands in solving that goal).

## How the agentic loop works
The mechanism connecting these pieces is the agentic loop: the agent sends its goal, its available tools, and the current context to the LLM; the LLM reasons about what to do next; the agent executes whatever tool call the LLM requests; the result is fed back into the context; and the cycle repeats until the LLM signals that the goal has been met.

![A diagram showing the relationship between the agent and the llm](https://images.ctfassets.net/0uuz8ydxyd9p/1TTNXDfHQdzBniVzZkBPBv/9886d9a44841f45e77f7a30d96552cea/image2.png){.zoom}

Concretely, for OSCAR: the context is the complaint email, the system prompt spells out the rules for handling these cases, and the tool list describes each available action. The LLM reads the email, recognizes that the customer wants a refund, and starts planning - its first move is to request more information about the order. That's exactly what the `check_order` tool is for. The agent calls it with an order ID inferred from the email, gets a result back, and hands that result to the LLM, which keeps planning until it has everything it needs to close the case.

This is the shift from manually prompting a chat model - hard to scale, hard to automate - to an agent that brings real autonomy, and more importantly, a real connection to the systems of record behind it.

## A working prototype in about a hundred lines 
The first version of Oscar is small: a system prompt describing the agent's role and rules, four tools, and an agent framework handling the orchestration loop so it doesn't have to be built by hand. This implementation uses `Spring AI`, a Java agent framework built on top of the widely used `Spring` framework, with Anthropic's `Claude Sonnet` as the underlying model, accessed through `OpenRouter`.

```java
@Component
public class OscarAgent {

  static final String SYSTEM_PROMPT = """
    You are a customer support agent for Amazoom, an e-commerce platform.
    When you receive a claim, execute these steps in strict order:
    1. Identify the order number in the message (format #XXXXX or XXXXX).
    2. Check the order with check_order.
    3. Update the status to "pending" with update_status(order_id, "pending").
    4. Process the Stripe refund with process_refund.
    5. Update the status to "refunded" with update_status(order_id, "refunded").
    6. Send a professional reply email with send_reply, mentioning
       the order number, the refunded amount, and that a return label
       will be sent within 24 hours.
    """.strip();

  private final ChatClient chatClient;

  public OscarAgent(ChatModel chatModel,
                    CheckOrderTool checkOrder) {
    this.chatClient = ChatClient.builder(chatModel)
      .defaultSystem(SYSTEM_PROMPT)
      .defaultTools(checkOrder)
      .build();
  }

  public String execute(String message) {
    return chatClient.prompt().user(message).call().content();
  }
}
```

One clarification worth keeping in mind: many providers, including Anthropic's models routed through OpenRouter, are reachable over the OpenAI-compatible chat completions protocol. Speaking that protocol says nothing about which model or provider is actually answering - it's a wire format, not a brand.

Each tool is a small piece of code wrapping an existing API call, paired with a natural-language description telling the LLM what the tool does and when to use it. `check_order`, for instance, does nothing more than fetch an order by ID.

```java
@Component
public class CheckOrderTool {
  private static final Logger log = LoggerFactory.getLogger(CheckOrderTool.class);

  private final AmazoomClient amazoom;

  public CheckOrderTool(AmazoomClient amazoom) {
    this.amazoom = amazoom;
  }

  @Tool(name = "check_order",
    description = "Retrieves the details of an order (product, amount, status) from its ID.")
  public OrderLookup checkOrder(@ToolParam(description = "Order ID") String orderId) {
    log.info("Fetching order {}", orderId);
    return amazoom.findOrder(orderId)
      .map(OrderLookup::found)
      .orElseGet(() -> OrderLookup.notFound(orderId));
  }
}
```

The last piece is what actually runs the agent: a small server exposing a single endpoint. Each incoming complaint email hits that endpoint, which starts the agent in a background thread and immediately returns an acknowledgment.

```java
@RestController
public class ClaimController {
  private static final Logger log = LoggerFactory.getLogger(ClaimController.class);

  private final OscarAgent agent;
  private final AmazoomClient amazoom;

  // Constructor...

  @PostMapping("/claim")
  @ResponseStatus(HttpStatus.ACCEPTED)
  public ClaimAckResult handleClaim(@RequestBody EmailRequest email) {
    String message = "Claim received from %s:\n\n%s".formatted(email.fromAddress(), email.body());
    Thread.startVirtualThread(() -> process(message));
    return ClaimAckResult.accepted();
  }

  private void process(String message) {
    try {
      amazoom.publishEvent(AgentEvent.started());
      // Call agent
      var result = agent.execute(message);
      amazoom.publishEvent(AgentEvent.done(result));
    } catch (Exception e) {
      log.error("Claim processing failed", e);
      try {
        amazoom.publishEvent(AgentEvent.failed(e.getMessage()));
      } catch (Exception publishError) {
        log.error("Could not report the failure to Amazoom", publishError);
      }
    }
  }
}
```

Running end to end, the agent reads the email, checks the order, issues the Stripe refund, updates the order status, and sends a confirmation email back to the customer - with no human in the loop. Around a hundred lines of code are enough to automate the whole exchange.

**What's an ADK?** An Agent Development Kit plays the same role for agents that an SDK plays for APIs: a standard structure for defining an agent's goal, tools, and context, so agents can be built consistently instead of reinvented each time. Several vendors offer one, and the right choice usually comes down to which ecosystem a team already works in - Spring AI's appeal for a Java team is that it extends a library they already know.{.caption}

Two things are worth checking before committing to one. First, whether the ADK ties the implementation to a specific model provider - staying model-agnostic keeps the door open to switching later for cost or performance reasons, in a field that moves fast enough for that to matter. Second, what its typed or structured output actually guarantees. A framework that enforces a schema, as Spring AI does, constrains *syntax*, not *semantics*: the model can still hallucinate plausible-looking data to fill a required field even when the output shape is technically correct. And switching models is never entirely free, even with a provider-agnostic framework - prompts are tuned for the model they were written against, so a provider or model change is a reason to retest them, not just swap a configuration value.

## Stripe goes down, and the agent just stops
A hundred lines of code and a working refund flow can look, from the outside, like the whole problem is solved. It isn't. Take the same agent, the same tools, the same prompts, and make one dependency fail: Stripe goes down mid-refund. Nothing recovers. The order is stuck in "refund in progress," no refund is actually issued, the customer gets no notice, and the agent neither retries, nor notifies anyone, nor fixes itself.

Restarting the agent process doesn't help either - it has no memory of what it had already done, so it can't resume where it left off. Killing the process mid-task produces the exact same outcome: whatever partial progress existed is simply lost.

The underlying issue is that this first version of the agent has no memory and no resilience: it dies with the process, and it has no way to know what state it was in when it crashed. Fixing that by hand would mean writing custom retry logic around every external call, tracking which side effects already happened, and reconciling inconsistent state after every failure - __Did Stripe process the refund before the failure? Did the order get updated? Is the refund already issued somewhere?__ Cracks like these appear everywhere once an agent leaves the demo environment.

Samuel Colvin, the creator of PydanticAI, has a name for this: *agent engineering*. Building an agent that survives production is mostly software engineering - deciding on the right structure, handling failure modes, making a simple prototype production-ready - not prompt engineering.

## What else production demands
Observability is the first gap: nothing shows what the agent actually decided, what actions it took, or what parameters it used to call a given tool. The only visible calls are ordinary backend calls - the agent itself logs nothing about its own reasoning.

A second set of problems is specific to LLMs: growing context windows dilute relevance and increase the risk of hallucination; memory has to be managed explicitly to support any kind of resumption; token limits and provider SLAs are real constraints, not edge cases.

A third set is the ordinary cost of building anything that talks to the outside world: timeouts, retries across every external call, a third-party service that's simply down, coordinating asynchronously between an external system and an agent that is, so far, entirely synchronous, and respecting rate limits.

And finally, there's the lifecycle of the agent process itself - version upgrades, restarts, and specifically what happens to work already in progress when either of those occurs.

Taken together, these problems define what's increasingly called *reliable AI*: an agent that can survive failures and recover its state - durable execution - and that exposes enough of its own behavior to be debugged when it doesn't do what's expected - observability.

## None of this is new, but it's expensive to build twice
None of these problems is unique to AI. Software engineering already has patterns for all of it: break the agent's work into discrete steps and log each one to an external aggregator such as Datadog or SigNoz; wrap external calls in proper error handling; persist intermediate state to a database or broker so an in-progress run can survive a crash; build recovery logic for the post-incident case; track call counts to enforce rate limits; add an audit trail specifically for AI decisions, plus a circuit breaker to fall back to a different model if needed; and apply ordinary GitOps discipline to how instances are deployed and restarted.

For a team already running microservices in production, none of this is conceptually new. The problem is that it's a lot of work, it's highly technical, and none of it is core business - it's not where a product's value gets created for its users. That's the case for looking at whether a workflow engine like Temporal can absorb this plumbing instead of every team rebuilding it from scratch.

<img src="https://images.ctfassets.net/0uuz8ydxyd9p/1sjMr4KgY3EO1rY00JYvVS/5db4317daaf1b93a797b087f75ef9488/image4.jpg" alt="A diagram listing the different plumbing that Temporal can take care of" style="display: block; margin: 0 auto; width: 60%;" />{.zoom}

## Adding durability with Temporal

> “Retry behavior comes free with the integration, without changing the logic at all”

The Temporal Spring AI integration lets us preserve the agent’s business logic while adding durable execution. Model calls run through Temporal Activities, and tools that call external systems are registered as Activity-backed tools.  Two Temporal concepts matter here: the *Workflow Definition*, which describes what should happen during a run, and the *Worker*, the process that actually executes that *Workflow*.

Let’s create Oscar 2!

```java
@WorkflowImpl(taskQueues = TaskQueues.AGENT)
public class Oscar2WorkflowImpl implements Oscar2Workflow {

    static final String SYSTEM_PROMPT = "(same system prompt...)";

    private final ChatClient chatClient;

    @WorkflowInit // New: annotation
    public Oscar2WorkflowImpl(String message) {
      // New: Wrap our tool in a Temporal "Activity" Stub
      var checkOrderTool = Workflow.newActivityStub(CheckOrderTool.class, AgentActivityOptions.TOOLS);
        // Same logic (just TemporalChatClient instead of ChatClient)
        this.chatClient = TemporalChatClient.builder(ActivityChatModel.forDefault())
                .defaultSystem(SYSTEM_PROMPT)
                .defaultTools(checkOrderTool)
                .build();
    }

    @Override
    public String execute(String message) {
        // Same logic!
        return chatClient.prompt().user(message).call().content();
    }
}
```

Wait… What? That’s it?

Yes. With only a couple lines changed (basically: wrapping tools and putting annotations on top of some methods), without any change to business logic, we have just added a bulletproof durable execution stack to our agent.

Wrapping the same agent this way, with the same tools and the same prompts, and replaying the exact same Stripe outage will this time produce a different outcome: the agent automatically retries the failed call, waits for Stripe to recover, and completes the refund without any manual intervention. Retry behavior on external calls comes free with the integration, without changing the agent's logic at all.

## Inspecting model calls, tool calls, and failures
Temporal’s Web UI lets us inspect recorded inputs and results for model calls and Activity-backed tools. It also exposes retry information and failure details. Intermediate Activity retry attempts aren’t individually recorded in Event History; detailed diagnostics for each attempt require Worker logs or additional instrumentation.

That gives an agent both resilience and a built-in audit trail, without any additional logging code. The combination matters more as the number of agents running in production grows - being able to see why a specific agent made a specific decision is what makes dozens of autonomously running agents debuggable at all.

## Surviving a restart
Production agents get restarted routinely, for patches, upgrades, or unrelated deploys. Killing the Temporal-wrapped agent mid-run - after it has already retrieved order information but before it has completed the refund - and then restarting it produces a very different outcome than before: the agent picks up exactly where it left off and finishes the task.

None of that resumption logic was written by hand. It comes entirely from the Spring AI / Temporal integration wrapping the agent.

## The cost of waiting for human approval
When you build an agent, you will often want a human in the loop at some point. Adding a required human approval step before any refund raises a different problem: how to wait on an external decision without burning resources or hand-rolling a second memory system.

The naive option is polling: the agent asks the back office, on a fixed interval, whether approval has happened yet, until it gets an answer. That's viable for a demo and expensive at any real scale - multiply it by hundreds of concurrent agents, or by approvals that take hours or days to arrive, and the wasted load becomes significant.

The next naive option is store-and-rehydrate: run the agent up to the point where only external approval is missing, persist its entire context to a database, and free the process. Once approval comes in, a webhook wakes a new agent instance, reloads the stored context, and resumes the work. It's workable, but it means building and maintaining storage, webhook wiring, restart logic, and cleanup - the same non-core-business plumbing as before, reshaped around a different problem.

## Handling human approval with Temporal
With Temporal, the same requirement breaks into three phases inside a single workflow: 
1. Gather information and decide on a plan; pause and 
2. Wait for an external decision, with a configurable timeout after which a default behavior applies; 
3. Branch on that decision - either proceed with the refund as before, or send the customer an email explaining that the request was declined.

```java
@Tool(name = "request_human_approval",
            description = "Requests approval from a human operator before processing a refund.")
    public String requestHumanApproval(@ToolParam(description = "Order ID") String orderId,
                                       @ToolParam(description = "Order amount, in euros") double amount,
                                       @ToolParam(description = "Product name") String product) {
	 // 1. send refund request to our Amazoom backend
        refundRequestService.notify(
                new RefundRequest(orderId, amount, product, Workflow.getInfo().getWorkflowId()));
	 // 2. waiting for an approval (does not consume any compute!)
        boolean received = Workflow.await(APPROVAL_TIMEOUT, () -> workflow.getRefundApprovalState() != null);
	 // 3. return result (will allow agent to carry on)
        return received && workflow.getRefundApprovalState()
                ? Oscar3WorkflowImpl.APPROVED
                : Oscar3WorkflowImpl.REFUSED;
    }
```

The three-phase workflow: gathering information, the pause step with its timeout, and the branch on the external approval decision.

Approving the request through that external signal wakes the paused workflow and lets it complete the refund.

## The wait state survives even if the agent doesn't
This isn't polling under the hood. 

If you were to kill the agent process entirely while the workflow was waiting on human approval, then approving the request anyway, nothing bad would happen!

When restarting the agent afterwards, it would resume correctly, “remember” that the request was approved (as Temporal is our middle man here), and complete the refund. The state isn't held by the process; it's held durably by Temporal itself, which is how it survives beyond a crash.

In Temporal's UI, that pause shows up as a distinct waiting step in the workflow's timeline, with the timeout and the eventual decision both visible.

Durable execution doesn't remove the need to manage context, though: the more steps a workflow accumulates, the larger the context sent to the LLM grows. Compacting or pruning that context at the right points remains good practice, independent of how reliably the workflow itself survives failures.

__What else does this pattern cover?__ The same building blocks extend to other production concerns: the saga pattern, for cleanly compensating a multi-step transaction after a failure partway through; rate-limit handling; and load distribution across the many agent workflows a system might run concurrently in production.

## Most of the agent will still rely on you though
Temporal brings the power of durable-execution to agent engineering, but doesn’t replace your agent logic. Prompt engineering still determines how well the agent reasons. Tool design still determines how reliably it can act. And none of the above says anything about security - worth its own look before shipping an agent that can move money!

## The refund that shouldn't have been approved
Consider a customer requesting a refund for an order that falls outside the marketplace’s refund policy. The agent accepts the customer’s explanation and calls the refund tool. If the backend checks only whether the payment exists, without enforcing refund eligibility, it can process a refund the company’s policy should have blocked.

The underlying assumption failed: an LLM-driven agent is a new kind of frontend to a company's systems, and a frontend has never been a trusted source of truth. The same discipline that applies to any user-facing input applies here.

> "The agent proposes, the backend disposes."

## Where security enforcement belongs
Guardrails on the agent side - instructions telling it what not to do - improve output quality, but they are not a security boundary; they can be bypassed or simply reasoned around. Real enforcement has to sit in the tools and the back office themselves, which must independently validate and authorize every action an agent requests, exactly as they would for any other untrusted caller. The deterministic backend, not the agent, is what guarantees the integrity of every operation.

## Takeaways: three principles for not reinventing the wheel
- __Scope AI to what it's actually good at__, and keep everything else deterministic. Don't reimplement with an LLM what a classic, testable rule can already do - reserve AI for parsing messy input and making judgment calls, and let deterministic code handle everything that can be specified precisely.
- __Build for reliable AI__: durable execution and observability, applied at least as rigorously as on any existing production system - arguably more, given how unpredictable model behavior can be.
- __Keep ordinary engineering discipline__. Testing, error handling, staged rollouts, and the rest of standard practice still apply to agents; they're what makes an agentic project succeed, not any AI-specific trick.

Don't take the risk of focusing on plumbing. Time spent re-implementing durable execution, retries, and observability by hand is time not spent on the feature that actually has business value - which is the case for treating a workflow engine like Temporal as infrastructure, not as an optional extra. 

Want to learn more? Join the webinar with Temporal and Takima on 11/26: https://pages.temporal.io/webinar-zero-to-production.html
