How to add an AI agent to a Micronaut application

<!-- Versions come from the Micronaut platform parent (io.micronaut.platform:micronaut-parent) -->
<dependency>
  <groupId>io.micronaut.langchain4j</groupId>
  <artifactId>micronaut-langchain4j-core</artifactId>
</dependency>
<dependency>
  <groupId>dev.langchain4j</groupId>
  <artifactId>langchain4j-anthropic</artifactId>
</dependency>
<dependency>
  <groupId>io.micronaut.reactor</groupId>
  <artifactId>micronaut-reactor</artifactId>
</dependency>

<!-- In the maven-compiler-plugin configuration -->
<annotationProcessorPaths combine.children="append">
  <path>
    <groupId>io.micronaut.langchain4j</groupId>
    <artifactId>micronaut-langchain4j-processor</artifactId>
    <version>${micronaut.langchain4j.version}</version>
  </path>
</annotationProcessorPaths>

anthropic.api-key=${ANTHROPIC_API_KEY}
# Check the CSRF token on JSON requests too (the default covers form posts only)
micronaut.security.csrf.filter.content-types=application/x-www-form-urlencoded,multipart/form-data,application/json
micronaut.security.csrf.signature-key=${CSRF_SIGNATURE_KEY}

package com.example.shop;

import dev.langchain4j.model.anthropic.AnthropicStreamingChatModel;
import dev.langchain4j.model.chat.StreamingChatModel;
import io.micronaut.context.annotation.Factory;
import io.micronaut.context.annotation.Value;
import jakarta.inject.Singleton;
import java.time.Duration;

@Factory
class ModelFactory {

    @Singleton
    StreamingChatModel streamingChatModel(@Value("${anthropic.api-key}") String apiKey) {
        return AnthropicStreamingChatModel.builder()
                .apiKey(apiKey)
                .modelName("claude-sonnet-5-5")
                .timeout(Duration.ofSeconds(60))
                .build();
    }
}

package com.example.shop;

import dev.langchain4j.agent.tool.P;
import dev.langchain4j.agent.tool.Tool;
import dev.langchain4j.invocation.InvocationParameters;
import jakarta.inject.Singleton;
import java.util.List;

@Singleton
public class OrderTools {

    private final OrderService orders;

    OrderTools(OrderService orders) {
        this.orders = orders;
    }

    // InvocationParameters is filled in by the controller for each request; the model never sees it.
    @Tool("List the signed-in user's recent orders")
    public List<Order> listOrders(@P(value = "open, shipped or cancelled", required = false) String status,
                                  InvocationParameters request) {
        return orders.list(request.get("userId"), status);
    }

    @Tool("Ask the user to confirm cancelling one of their open orders. Nothing is cancelled until they confirm.")
    public String cancelOrder(String orderId, InvocationParameters request) {
        Order order = orders.find(request.get("userId"), orderId); // null unless the order belongs to this user
        if (order == null || !order.isOpen()) return "There is no open order " + orderId + " for this user.";
        List<String> pending = request.get("pendingCancellations");
        pending.add(orderId);
        return "The user has been asked to confirm cancelling order " + orderId + ".";
    }
}

package com.example.shop;

import dev.langchain4j.invocation.InvocationParameters;
import dev.langchain4j.service.MemoryId;
import dev.langchain4j.service.SystemMessage;
import dev.langchain4j.service.TokenStream;
import dev.langchain4j.service.UserMessage;
import io.micronaut.langchain4j.aiservices.AiServiceCreationContext;
import io.micronaut.langchain4j.aiservices.AiServiceCustomizer;
import io.micronaut.langchain4j.annotation.AiService;
import jakarta.inject.Singleton;

@AiService(tools = OrderTools.class, customizer = OrderAgent.Limits.class)
public interface OrderAgent {

    @SystemMessage("You help the signed-in user manage their orders. Use the tools; never guess order data.")
    TokenStream chat(@MemoryId String userId, @UserMessage String message, InvocationParameters request);

    @Singleton
    class Limits implements AiServiceCustomizer<OrderAgent> {
        @Override
        public void customize(AiServiceCreationContext<OrderAgent> context) {
            context.aiServices().maxToolCallingRoundTrips(5);
        }
    }
}

package com.example.shop;

import dev.langchain4j.invocation.InvocationParameters;
import io.micronaut.http.HttpResponse;
import io.micronaut.http.MediaType;
import io.micronaut.http.annotation.Body;
import io.micronaut.http.annotation.Controller;
import io.micronaut.http.annotation.Post;
import io.micronaut.security.annotation.Secured;
import io.micronaut.security.authentication.Authentication;
import io.micronaut.security.rules.SecurityRule;
import io.micronaut.serde.annotation.Serdeable;
import java.util.List;
import java.util.Map;
import java.util.concurrent.CopyOnWriteArrayList;
import reactor.core.publisher.Flux;

@Controller
@Secured(SecurityRule.IS_AUTHENTICATED)
class AgentController {

    @Serdeable record AgentRequest(String message) {}
    @Serdeable record AgentEvent(String type, String value) {}

    private final OrderAgent agent;
    private final OrderService orders;

    AgentController(OrderAgent agent, OrderService orders) {
        this.agent = agent;
        this.orders = orders;
    }

    @Post(uri = "/agent", produces = MediaType.TEXT_EVENT_STREAM)
    Flux<AgentEvent> chat(@Body AgentRequest request, Authentication user) {
        String userId = user.getName(); // your stable user ID
        List<String> pending = new CopyOnWriteArrayList<>();
        InvocationParameters params = InvocationParameters.from(Map.of("userId", userId, "pendingCancellations", pending));

        Flux<AgentEvent> text = Flux.create(sink -> agent.chat(userId, request.message(), params)
                .onPartialResponse(chunk -> sink.next(new AgentEvent("text", chunk)))
                .onCompleteResponse(response -> sink.complete())
                .onError(sink::error)
                .start());
        // After the model finishes, ask the browser to confirm any cancellation the model proposed.
        Flux<AgentEvent> confirmations = Flux.defer(() -> Flux.fromIterable(pending))
                .map(orderId -> new AgentEvent("confirm-cancel", orderId));

        return text.concatWith(confirmations)
                .onErrorResume(e -> Flux.just(new AgentEvent("error", "The agent stopped before finishing.")));
    }

    // Your normal endpoint: authenticated, checked by the CSRF filter, scoped to the user.
    @Post("/orders/{orderId}/cancel")
    HttpResponse<Void> cancel(String orderId, Authentication user) {
        orders.cancel(user.getName(), orderId);
        return HttpResponse.noContent();
    }
}

<head>
  <meta name="csrf-token" th:content="${csrfToken}">
  <script src="/agent.js" defer><\/script>
</head>
<body>
  <div id="agent-log" aria-live="polite"></div>
  <form id="agent-form">
    <input name="message" aria-label="Ask the agent" autocomplete="off" required>
    <button>Send</button>
  </form>
</body>

const csrfHeader = "X-CSRF-TOKEN";
const csrfToken = document.querySelector('meta[name="csrf-token"]').content;
const log = document.getElementById("agent-log");

document.getElementById("agent-form").addEventListener("submit", async (event) => {
  event.preventDefault();
  const input = event.currentTarget.elements.message;
  const reply = log.appendChild(document.createElement("p"));
  const res = await fetch("/agent", {
    method: "POST",
    headers: { "Content-Type": "application/json", [csrfHeader]: csrfToken },
    body: JSON.stringify({ message: input.value }),
  });
  input.value = "";
  if (!res.ok) {
    reply.textContent = "The agent is unavailable.";
    return;
  }
  for await (const { type, value } of readEvents(res)) {
    if (type === "text" || type === "error") reply.textContent += value;
    if (type === "confirm-cancel") log.appendChild(confirmButton(value));
  }
});

// The cancellation itself goes through your normal endpoint, with the session cookie and CSRF token.
function confirmButton(orderId) {
  const button = document.createElement("button");
  button.textContent = `Cancel order ${orderId}`;
  button.addEventListener("click", async () => {
    button.disabled = true;
    const res = await fetch(`/orders/${encodeURIComponent(orderId)}/cancel`, {
      method: "POST",
      headers: { [csrfHeader]: csrfToken },
    });
    button.textContent = res.ok ? `Order ${orderId} cancelled` : "Could not cancel the order";
  });
  return button;
}

// Reads the text/event-stream body: one JSON object per "data:" line.
async function* readEvents(res) {
  const reader = res.body.pipeThrough(new TextDecoderStream()).getReader();
  let buffer = "";
  for (;;) {
    const { value, done } = await reader.read();
    if (done) return;
    buffer += value;
    const lines = buffer.split("\n");
    buffer = lines.pop();
    for (const line of lines) {
      if (line.startsWith("data:")) yield JSON.parse(line.slice(5));
    }
  }
}

<head>
  <meta name="csrf-token" th:content="${csrfToken}">
  <!-- Page hooks first, then the loader, then your application's scripts -->
  <script src="/agent-identity.js"><\/script>
  <script src="/agent-auth-headers.js"><\/script>
  <script src="https://embed.bunkhouse.ai/embed.js" data-public-key="pk_YOUR_SITE_PUBLIC_KEY"><\/script>
  <script src="/app.js" defer><\/script>
</head>

Read https://api.bunkhouse.ai/agent-trial.md and follow it to run a Bunkhouse agent trial on my dummy Micronaut page at http://localhost:8080.

Use a page with disposable data: everything the assistant reads is sent to your agent.