Redouble AI Nucleo documentation

Contents

Nucleo runs AI agents inside a Java application. These pages are in the order a reader meets it: what it is, the demo running on your own account, a set of examples, and then one part per question an engineer asks on the way to shipping an agent - how to write one, how the application keeps control of it, which model serves it, what a model call carries, how many can run at once, how to see what they did, and how to host the runtime. Each page builds on the ones before it, and the links at the bottom of every page walk this order.

Examples

Small programs to read and copy from, each a main in nucleo-examples: a first question to a model, a first tool, agent and doer, then one program for each thing the runtime keeps under the application's control. The code on every page is the code that compiles; the build fails when the two differ.

Writing an agent

You wrap operations you already trust as typed tools and hand a set of them to a thinker, an agent whose model decides which tool to call next; a doer composes tools and thinkers in plain Java. The answer comes back as the Java object you declared, and data a tool produced travels between agents unaltered.

The process stays in charge

The application decides what an agent may touch, and the model cannot widen it: a scope fixed when the work starts, guardrails that run as Java before every tool call under the caller's identity, and failures that tell the model what went wrong and whether trying again can help.

Models

Code asks for a grade of model, a rung on a ladder from MICRO to MEGA, and the deployment's catalog says which entry serves it, at what price and through which provider. A discovery run writes the catalog from the account's own listings, and a benchmark measures which grade a job needs.

Inside a model call

What one call to a model sends and receives: the conversation and its content blocks, how the tools and the objective are shown to the model, prompt caching, compaction when a conversation outgrows its window, and the client layer that turns all of it into each vendor's request, admitted against the provider's rate limits before it is sent.

Decision models

A third kind of model beside chat and embeddings: it reads a state and typed questions and answers with a probability for each option, writing no text. Code puts the options in front of it, and a whole agent can run on one.

Hundreds of agents in one JVM

Every piece of work is a job on a virtual thread. A job declares everything it needs and is admitted with all of it at once, or waits holding nothing, and a provider's rate limits are respected before a request is sent. The same admission covers the connections a job holds: HTTP, a DataSource, Hibernate.

Seeing what happened

Every job publishes typed events on a message bus as it runs. Observers turn them into log lines, spans, metrics, and a cost ledger that can cap what a workflow spends, and nothing an observer does slows a job.

Hosting Nucleo

The runtime inside an application: one configurator for every setting, credentials from the store the deployment already uses, and the Spring Boot and Quarkus integrations that bind the dispatcher's lifecycle to the container's.

Beyond the process

For a tool that lives outside the process, and for a tool of this one offered to an outside client: the MCP client with its transports and authorization, the MCP server with its schema dialects, and the chat protocol a host exposes to a frontend.

Extensions

Tool sets for particular domains, each in an artifact of its own.

The demo, end to end

The demo application puts the parts above to work: what each of its steps shows, the decision agent, and the Quarkus host that serves the same engine on the JVM or as a native image.

Inside the runtime

For people working on Nucleo itself: how each part does what its guide describes, in the same order as the guides. A reader using Nucleo never needs these pages.

Appendix

^