8000 GitHub - jwcarman/nessy: Nessy — an AI agent harness framework for Java · GitHub
[go: up one dir, main page]

Skip to content
jwcarmanPublic

Latest commit

 

History

2,351 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Nessy mascot

Nessy

CI Maven Central Javadoc Docs License Java

Maintainability Rating Reliability Rating Security Rating Vulnerabilities Quality Gate Status Coverage

An agent harness framework for Java.

Read the docs

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.

The five-minute example

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())));
}

Try it

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=secret

chat-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:java

chat-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:run

mcp: a terminal agent whose tools come from somebody else's server. 8000 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:java

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

Install

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

What Nessy gives you

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

Roadmap

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.

Contributing

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.

License

Nessy is licensed under the Apache License 2.0.

The name

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.

Releases

Packages

Used by

Contributors

Languages

0