# Nucleo documentation

> 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.

- [Overview](index.html)
- [Why Nucleo](philosophy.html)
- [Contents](contents.html)
- [Set up and run the demo](agents.html)

## 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.

- [Hello, model](examples-hello.html)
- [Your first tool](examples-tool.html)
- [Your first agent](examples-agent.html)
- [Your first doer](examples-doer.html)
- [Data the model cannot alter](examples-artifacts.html)
- [An agent that stays inside its case](examples-scope.html)
- [Overlapping scopes](examples-scopes.html)
- [A dollar cap on a workflow](examples-cap.html)
- [One decision](examples-decision.html)
- [Racing a grade](examples-benchmark.html)
- [Any thinker in a benchmark](examples-scoring.html)
- [Your tools over MCP](examples-mcpserver.html)
- [Calling an MCP server](examples-mcpclient.html)
- [An MCP tool wrapped as your own](examples-mcpwrap.html)

## 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.

- [Tools, thinkers and doers](tools.html)
  - [The kinds of thinker](tools-thinking.html)
  - [Which tools an agent is offered](tools-registry.html)
- [Answers as Java objects](harness-schema.html)
- [Artifacts: data the model cannot alter](harness-artifacts.html)
  - [Artifact tools](harness-artifacts-tools.html)
- [Prompts](prompt.html)
  - [Prompt sources](prompt-sources.html)
  - [Skills and skilljars](prompt-skill.html)
- [Built-in tools](tools-builtin.html)

## 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.

- [Scope and the trust boundary](tools-guardrails.html)
- [Writing a guardrail](guardrails.html)
- [Failures that behave](exceptions.html)
  - [When a job runs again](harness-errors-retry.html)
  - [HTTP errors as typed failures](harness-errors-http.html)

## 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.

- [The catalog, grades and the picker](harness-models.html)
  - [Discovering an account's models](harness-models-discovery.html)
- [Measuring the grade a job needs](tools-benchmark.html)
- [Anthropic](providers-anthropic.html)
- [Amazon Bedrock](providers-bedrock.html)
  - [Claude on Bedrock through the Anthropic SDK](providers-bedrock-anthropic.html)
- [OpenAI](providers-openai.html)

## 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.

- [Conversations: what every call carries](harness-conversation.html)
  - [When a conversation outgrows its window](harness-conversation-compaction.html)
- [Model clients and rate limits](harness-llm.html)
  - [How each part of a message reaches a provider](harness-llm-encode.html)

## 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.

- [What a decision model is](tools-deciding.html)
- [The decision wire](harness-decision.html)
- [Connecting a decision model](providers-systemone.html)

## 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.

- [The job runtime](harness.html)
- [Admission](harness-admission.html)
  - [Why admission has this shape](admission.html)
- [The HTTP connection pool](http.html)
- [Connections from a DataSource](jdbc.html)
- [Hibernate sessions](hibernate.html)

## 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.

- [Events: what a running job reports](events.html)
  - [Heartbeats: work that runs later](events-heartbeat.html)
  - [Retry events: a job running again](events-retry.html)
- [Logs, traces, metrics and cost](harness-observability.html)
  - [Why observability has this shape](observability.html)
- [Reporting progress from a job](progress-guidelines.html)

## 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.

- [Settings: where to tune anything](nucleo.html)
- [Where credentials come from](secrets.html)
- [Running inside Spring Boot](spring.html)
- [Running inside Quarkus](quarkus.html)

## 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.

- [Using tools from MCP servers](mcp.html)
  - [Connecting to an MCP server as an agent](mcp-auth.html)
- [Offering your tools over MCP](mcp-server.html)
  - [Schema dialects for MCP clients](serial.html)
- [Building a chat endpoint](chat.html)
  - [Chat frames on the wire](chat-messages.html)

## Extensions

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

- [Literature search: PubMed and bioRxiv](ext-lit.html)
- [Patents: EPO Open Patent Services](ext-patent-epo.html)
- [Patents: USPTO Open Data Portal](ext-patent-usptoodp.html)

## 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.

- [The demo, step by step](demo.html)
  - [An agent on a decision model](demo-decide.html)
  - [The demo on Quarkus](demo-quarkus.html)

## 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.

- [Inside tools, thinkers and doers](tools-internals.html)
  - [Inside the thinker families](tools-thinking-internals.html)
  - [Inside palettes and the tool registry](tools-registry-internals.html)
- [Inside the serializer](serializer.html)
- [Inside artifacts](harness-artifacts-internals.html)
  - [Inside the artifact tools](harness-artifacts-tools-internals.html)
- [Inside prompts](prompt-internals.html)
  - [Inside skills](prompt-skill-internals.html)
- [Inside the trust boundary](tools-guardrails-internals.html)
- [Inside guardrail enforcement](guardrails-internals.html)
- [Inside the exception hierarchy](harness-errors-internals.html)
  - [Inside retry signals](harness-errors-retry-internals.html)
  - [Inside HTTP status exceptions](harness-errors-http-internals.html)
- [Inside the catalog and the picker](harness-models-internals.html)
  - [Inside the discovery](harness-models-discovery-internals.html)
- [Inside the benchmark](tools-benchmark-internals.html)
- [Inside the Anthropic provider](providers-anthropic-internals.html)
- [Inside the Bedrock provider](providers-bedrock-internals.html)
  - [Inside Claude on Bedrock through the Anthropic SDK](providers-bedrock-anthropic-internals.html)
- [Inside the OpenAI provider](providers-openai-internals.html)
- [Inside conversations](harness-conversation-internals.html)
  - [Inside compaction](harness-conversation-compaction-internals.html)
- [Inside the model clients](harness-llm-internals.html)
  - [Inside per-block encoding](harness-llm-encode-internals.html)
- [Inside decision calls and the decision thinker](tools-deciding-internals.html)
- [Inside the decision wire](harness-decision-internals.html)
- [Inside the System One provider](providers-systemone-internals.html)
- [Inside the job runtime](harness-internals.html)
- [Inside admission](harness-admission-internals.html)
- [Inside events](events-internals.html)
  - [Inside heartbeat events](events-heartbeat-internals.html)
  - [Inside retry events](events-retry-internals.html)
- [Inside observability](harness-observability-internals.html)
- [Inside settings](nucleo-internals.html)
- [Inside credentials](secrets-internals.html)
- [Inside the Spring Boot starter](spring-internals.html)
- [Inside the Quarkus extension](quarkus-internals.html)
- [Inside the MCP client](mcp-internals.html)
  - [Inside MCP authorization](mcp-auth-internals.html)
- [Inside the MCP server](mcp-server-internals.html)
- [Inside the chat surface](chat-internals.html)
  - [Inside the chat messages](chat-messages-internals.html)
- [Inside literature search](ext-lit-internals.html)
- [Inside the EPO tools](ext-patent-epo-internals.html)
- [Inside the USPTO ODP tools](ext-patent-usptoodp-internals.html)
- [Inside the demo](demo-internals.html)
  - [Inside the decision agent](demo-decide-internals.html)
  - [Inside the Quarkus host](demo-quarkus-internals.html)

## Appendix

- [Contributing](contributing.html)
- [Code of conduct](code-of-conduct.html)
- [Security](security.html)
- [Changelog](changelog.html)
- [Utilities](util.html)
- [The site generator](docs.html)