An agent harness framework for Java.
The documentation site is the manual: concepts, guides, examples, and reference, in one place. This README is just the front door: enough to run something real and decide what to install.
Two harness doors, and they are peers. DirectHarness<I, O>.ask runs a
turn on the calling thread and hands back an AskOutcome<O> — for a caller
standing there waiting on an answer. QueuedHarness<I>.tell returns a
TellOutcome — Accepted or Terminated — for work nobody is waiting on. Build one once, keep
it, and ask it things:
export ANTHROPIC_API_KEY=...record Add(int left, int right) {}
class AddTool implements Tool<Add> {
public ToolName name() { return new ToolName("add"); }
public String description() { return "Adds two integers"; }
public Class<Add> inputType() { return Add.class; }
public Awaited<ToolResult> call(ToolCallRequest<Add> request) {
Add input = request.input();
return Awaited.ready(ToolResult.ok(new Block.Text(String.valueOf(input.left() + input.right()))));
}
}
CodecFactory codecs = new JacksonCodecFactory(JsonMapper.builder().build());
DirectBackend backend = new InMemoryDirectBackend(codecs); // nothing durable
DirectHarnessFactory factory = DefaultDirectHarnessFactory.of(config -> config
.backend(backend)
.provider(ProviderId.of("anthropic"), AnthropicInferenceProvider.fromEnv()));
DirectHarness<String, String> harness = factory.<String>create(
new AgentType("assistant"),
config -> config
.systemPrompt("You are a terse assistant.")
.inference(in -> in.provider("anthropic").model("claude-sonnet-5-5"))
.tool(new AddTool()));
AskOutcome<String> outcome = harness.ask(AgentId.random(), "what is 2+2?");The example needs Java 25 and four dependencies: nessy-engine,
nessy-backend-inmemory, nessy-inference-anthropic and
org.jwcarman.codec:codec-jackson (version 0.10.0; the BOM below does not
manage it). Getting Started
has the pom and the imports.
ask never throws for anything it understands: a model declining, a turn
running out of budget or the agent already being busy are AskOutcome arms —
Answered, Refused, Failed, Busy, Terminated — to branch on, not faults. See
The Harness for the
queued door, which trades that returned outcome for a backlog and answers
narrated to listeners.
For a terminal agent, one call does the whole bootstrap: provider, harness and
loop. It needs nessy-console and one provider adapter on the classpath, and
the conversation stays in memory:
public static void main(String[] args) {
Repl.run(config -> config
.systemPrompt("You are a helpful assistant.")
.tool(new AddTool())
.tool(new SendEmailTool(), binding -> binding
.approver(ConsoleApprover.atTheTerminal())
.action(email -> "Send an email to " + email.to())));
}nessy-examples has six modules. The ones that talk to a model want an
OpenAI-compatible endpoint, LM Studio on :1234
or Ollama on :11434 works and costs nothing, and a
PostgreSQL to keep the agents in:
export NESSY_PROVIDERS_LMSTUDIO_ENABLED=true
export NESSY_PROVIDER=lmstudio
export NESSY_MODEL=<a model id your endpoint serves>
export SPRING_DATASOURCE_URL=jdbc:postgresql://localhost:5432/nessy
export SPRING_DATASOURCE_USERNAME=nessy
export SPRING_DATASOURCE_PASSWORD=secretchat-cli: a terminal agent with a notebook, a plan and the date as
ambient background, gated on a tool that asks at the prompt:
./mvnw -q -pl :nessy-example-chat-cli -am compile exec:javachat-web: the same agent as a page, on the queued door. A message
is told and the request returns. A resumable SSE stream says what the agent
is doing and when the turn has answered, and the page reads the answer from
the agent's state. The email tool's approval waits in Nessy, so the page lists it as a
card and it survives a closed tab or a restart.
./mvnw -q -pl :nessy-example-chat-web -am install -DskipTests
./mvnw -q -pl :nessy-example-chat-web spring-boot:runmcp: a terminal agent whose tools come from somebody else's server.
It connects to DeepWiki's public MCP endpoint, grants the three tools it
advertises, and gates the one that spends DeepWiki's own model budget:
./mvnw -q -pl :nessy-example-mcp -am compile exec:javapolicy: the gate as data. A PolicyApprover that asks Open Policy
Agent, so the rules are Rego reviewed by whoever owns the risk rather than
Java that ships with a release. No model and no key: it runs the real OPA
binary in a container.
./mvnw -pl :nessy-example-policy test -Dnessy.excludedGroups=watchman: the Spring Boot soak. It lives on a real box, does rounds on
a timer, proposes remediations it is not allowed to run itself, and waits
for a person to answer through a page. nessy-examples/watchman/soak.sh
runs it and then asserts what happened, including that something
actually parked.
chapter-lab: a command-line lab that replays one long recorded
conversation through the engine under the chapter policy and summariser you
choose, then asks questions with known answers from the context the engine
built. Its own README says what it needs and how to run it.
Every module shares groupId org.jwcarman.nessy and is published to Maven
Central.
Import the BOM to align versions, then pick the artifacts your application actually needs:
<dependencyManagement>
<dependencies>
<dependency>
<groupId>org.jwcarman.nessy</groupId>
<artifactId>nessy-bom</artifactId>
<version>0.7.0</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>Tool and policy authors compile against nessy-api alone; adapter authors
add nessy-inference-spi; an application building an agent depends on
nessy-engine plus one provider adapter and one backend.
| Artifact | What it is for |
|---|---|
nessy-api |
the shared vocabulary: Tool, Approver, Awaited, blocks, NarrationListener, AskOutcome |
nessy-inference-spi |
adapter authors: InferenceProvider |
nessy-backend-spi |
backend authors: DirectBackend, QueuedBackend, Chapters for an agent's closed chapters, and Leases for work that must run once across processes |
nessy-backend-jdbc |
one PostgreSQL DataSource behind either door, and Schemas |
nessy-backend-inmemory |
the same stores with nothing behind them but the process |
nessy-engine |
the two doors' factories, and the fold behind them |
nessy-inference-anthropic, nessy-inference-openai, nessy-inference-gemini, nessy-inference-bedrock |
the provider adapters; the OpenAI module speaks Chat Completions and the Responses API, and reaches every OpenAI-compatible endpoint |
nessy-console |
terminal applications: Repl.run |
nessy-spring-boot-starter |
the one dependency a Boot application adds; no code of its own |
nessy-spring-boot-autoconfigure |
the beans, the nessy.* properties, and every optional module's auto-configuration |
nessy-prompt, nessy-prompt-spring, nessy-prompt-mustache |
prompts as templates, and two engines |
nessy-embedding-spi, nessy-embedding-openai, nessy-embedding-gemini, nessy-embedding-bedrock, nessy-embedding-voyage |
text into vectors: the Embedder seam, and four embedders; the OpenAI one reaches any OpenAI-compatible endpoint |
nessy-memory-notebook |
notes an agent keeps and recalls by heading |
nessy-planning |
the Planning pattern: a plan an agent writes and works through across turns |
nessy-narration-odyssey |
agent events as resumable streams, for a browser |
nessy-approval-risk |
the risk gate: two thresholds with a person in between |
nessy-approval-policy |
deciding a tool call by policy: approve, deny, or delegate |
nessy-approval-policy-opa |
an engine backed by Open Policy Agent |
nessy-tool-mcp |
importing a remote MCP server's tools |
| Capability | Site page |
|---|---|
| Agent as scope: one lock per id, durable state instead of a live instance | Agent as Scope |
| Durable computation: effects as rows, deadlines as columns, recovery without a sweep | Durable Computation |
| Tools: structured calls, typed inputs, and deferring to the world | Tools |
| Authorization: approvers, answering a waiting call, and describing what a person is consenting to | Authorization |
| Risk: an assessment over the NIST SP 800-30 matrix, and two thresholds with a person in between | Authorization |
| Context: six strata, from instructions to ambient, history cut into summarised chapters, and keeping the cache | Context |
| Memory: what an agent recalls, memory and state sources, notes, and embeddings | Memory |
| Planning: a plan the model holds, and the family of patterns to come | Planning |
| Storage: a table per thing, a codec seam for encryption, every model call on record | Storage |
| Providers: four adapter modules, both OpenAI shapes, every OpenAI-compatible endpoint, and thinking as a provider setting | Providers |
| Prompts: a system prompt fixed at build, as a template with holes and variables for the values | Prompts |
| Narration: listeners, the builder, and streams a browser can resume | Narration |
| MCP: import a remote server's tools as ordinary tools | MCP Clients |
| The harness: two doors, kept not closed; outcomes, coalescing, and approval desks | The Harness |
| Trajectories: a deterministic behavioral fingerprint on every completed turn, and behavior across turns as a query | Trajectories |
| Observability: GenAI semantic conventions, traces that cross the outbox, and the record | Observability |
Spring Boot: a harness and every optional module from nessy.* properties and beans |
Spring Boot |
Where this is all headed lives in ROADMAP.md: memory that learns, planning that replans, delegation that scales, and the road to a first release.
Contributions are welcome. See CONTRIBUTING.md for how to get started, and CODE_OF_CONDUCT.md for the standards we hold this project to. Please report security issues per SECURITY.md rather than filing a public issue.
Nessy is licensed under the Apache License 2.0.
What's in a name? Look at the middle of the word harness: the name was hiding inside the thing the whole time. And once your agent framework is named Nessy, the mascot picks itself: a certain famously elusive resident of Loch Ness, here wearing (what else?) a harness. Like her namesake, she's mostly calm water on the surface with a great deal going on underneath.