Agnes Harness

English | 简体中文

Upgrading from the previous version? This is a new release with no data migration. Read the upgrade guide first: back up and clean up the old environment, then start fresh.

LLM is the brain. Jev is the cerebellum. Harness is the memory. MHS is the body.
_{One open-source foundation for business agents, enterprise delivery and the physical world. See the architecture}

Taking AI into a real deployment is rarely about the model alone. It is about the customer's systems, the people who approve the work, and the details that differ at every site. Agnes Harness (AGH) connects models, tools, task state and business interfaces: put the differences into plugins, let the harness run and record the work, and carry what you validated into the next deployment.

_{Read the code, ask before running a command, verify, answer, and record every step.}

Contents

• What AGH is, and what it is not
• Architecture: brain, cerebellum, memory and body
• What AGH does for a deployment team
• Write a plugin
• Demo videos and reproduction
• Public benchmark
• Run from source
• New product and old environments
• Current status and roadmap
• FAQ
• Community and license

What AGH is, and what it is not

AGH is an open-source agent harness built for Forward Deployed Engineering (FDE): working in users' environments to turn systems integration, a usable interface and ongoing iteration into delivered software. Everything a deployment adds is a plugin: tools, agent loops, model adapters, Web panels, Skills, connections and services. A plugin can also declare agents you launch directly, and an application that a deployment administrator adopts as the workbench. Explore FDE and application scenarios →

What it is not, so you can choose the right trial:

• Not a hosted service. AGH is a developer preview that you build from source and run in your own environment.
• Not a sandbox for arbitrary plugin code. Ordinary backend plugins run as trusted in-process code; approvals and the command sandbox apply to the supported execution paths. See security and trust.
• Not a certified device driver. MHS is AGH's own device protocol, independent of MCP. Device controllers keep real-time control and physical safety.
• Not finished. APIs, configuration and plugin interfaces are evolving and may change.

Architecture: brain, cerebellum, memory and body

The brain, cerebellum, memory and body describe AGH's vision: combine reasoning, structured decisions, persistent task context and physical capabilities. Harness is the runtime; Jev and MHS join it as official plugins.

Role	What it means in AGH	Current scope
LLM / brain	Understand requests, reason about the task and propose actions	Model accounts and model-adapter plugins
Jev / cerebellum	TypeSafe Jev chooses each step; the conversation model only writes, fills parameters or reviews	Official optional loop plugin @agnes/jev-loop, installed from the Marketplace (guide)
Harness / memory	Session history, task state, execution records and reusable methods in Skills	The runtime itself: it runs, records, recovers and governs execution
MHS / body	Connect device capabilities so tasks can read physical state and request actions	Official plugin; integration in progress

Clients (Web, CLI, terminal UI, SDK) connect to one App Server per home. Core owns durable facts, authorization and recovery. Workers host plugin generations; even the default loop is a plugin, @agnes/loop-default. Plugin code is pinned per session; MCP definitions and Skills are live resources filtered by the session's composition.

Follow the request path and source ownership in the architecture guide and plugin contracts, or explore the source map.

What AGH does for a deployment team

1. Your business agent is a plugin

The agent needs your order lookup, your knowledge base, your internal API. Writing that into the agent itself means forking it for every customer.

In AGH, package a business loop, tools, model adapters, persona and Skills into one installable plugin, or connect an existing service through MCP. Each session gets the capabilities it selected; a support agent's tools do not appear in an unrelated session. Installing a plugin shows its version, source, integrity digest, capabilities and license before anything runs. Business events can start work too: opt-in GitHub and generic webhook triggers open ordinary sessions under the normal policy.

Plugin mechanism script · Developer teaching examples · Acme application

2. Upgrade without replacing work in progress

New sessions use the reviewed new plugin code; saved sessions keep their backend code (tools, hooks, loops and seams) across restarts. Uncertain external effects require reconciliation before another dispatch.

Run the hot-upgrade demo · Sessions and recovery · Plugin lifecycle

3. Work starts on the Web and continues in the terminal

CLI, Web and SDK share the same backend sessions. Resume a Web session in the terminal with /resume <id> and the history, tool records and results are already there; whatever you add in the terminal shows up in the Web thread.

4. "What did the AI change, and who approved it?"

Running a command waits for your approval by default: allow once, allow for the session, or deny. The Trace view keeps a timeline of model calls, tools and approvals. Package trust, tool approvals, execution constraints and session records give the integration explicit points of control. See security and trust.

5. The next deployment starts from the last one

Ask the agent to draft a Skill or plugin, test it, then review its files and permissions before publication. Provenance keeps the drafting session and the human review. Learned file memory can retain workspace preferences, with agent access off by default.

Run the growing-skills demo · Candidate review · Skills · Memory

6. Each role needs its own screen

A support lead and a warehouse operator do not want the same interface. Add frontend panels to the Web workbench and connect them to backend services with full-stack plugins. The conversation dialog also takes voice: dictation, read-aloud and a hands-free voice conversation.

7. The site also has devices

From inspection to instrument coordination, field work connects device state, human judgment and business workflows. Agnes MHS (Model Hardware Standard) is AGH's own open device protocol: a device connects to AgnesHub, registers its state, tools and data sources, and takes calls; MOS (Model Observation Standard) streams what it observes. In this release MHS becomes an official plugin, and its integration is in progress.

Write a plugin

From a built source checkout, add an echo tool in an isolated home. No agent or application declaration is needed:

export AGH_SOURCE="$PWD"
export AGH_HOME="$(mktemp -d /tmp/agh-hello.XXXXXX)"
export AGH_HOME="$(cd "$AGH_HOME" && pwd -P)"
export AGNES_PROFILE=local-dev
AGH_WORKSPACE="$(mktemp -d /tmp/agh-hello-workspace.XXXXXX)"
cd "$AGH_WORKSPACE"
mkdir -p .agh/plugins
node "$AGH_SOURCE/templates/create-agh-plugin.mjs" tool hello-tool .agh/plugins/hello-tool --local
node "$AGH_SOURCE/agnes.mjs" dev .agh/plugins/hello-tool
node "$AGH_SOURCE/agnes.mjs" --new -p 'call plugin_hello_tool {"message":"hello"}'

The same template also starts a tool with a panel, an agent loop, a model adapter, or an MCP-and-Skills plugin. Each tutorial below includes source code, steps and expected results.

Example	What you will see	What you can build from it
A tool	Invoke demo_text_stats and receive character and word counts	Order lookup, data retrieval or another business function
A panel	Load your own sidebar panel and update its version	Task information and business state for one role
A full-stack plugin	Read a backend result from a panel, then inspect updates and rollback	A business service packaged with its interface

Plugin quickstart · Plugin development · Try without a model account

Share your plugin. Put it in its own GitHub repository with package.json at the root, release it with vX.Y.Z tags, and add the GitHub topic agh-plugin so it appears on github.com/topics/agh-plugin. Anyone can then install a release with agh plugins add git:https://github.com/<owner>/<repo>#vX.Y.Z. Official plugins are also listed in the AGH plugin market index.

Demo videos and reproduction

MHS Mars rescue: coordinating devices

Have the agent send the hopper to find an astronaut, then coordinate the robot and airlock to bring them back. AGH runs the task, AgnesHub calls devices through MHS, and MOS returns camera images, poses and other observations. The video was recorded on the previous release; reproduction steps return with the MHS plugin.

The demo guide lists the runnable product demos and developer scripts. They use fresh isolated homes and a deterministic local model by default, and send no external business messages.

Public benchmark

On the public Agents' Last Exam (ALE) leaderboard, which evaluates complete agent systems (model, harness and tools) on professional tasks, Agnes Harness with Agnes 2.5 Pro Beta reaches a 21.7% overall pass rate and a 42.7 overall score.

_{Results depend on model versions, settings and tool configurations. See the leaderboard for current figures.}

Run from source

The runtime supports Node.js 24.10+. Source builds use the exact patch in .node-version through mise, pnpm 10.34.5 and your platform's native build tools (installation). Before running AGH, read security and trust. From the repository root:

mise trust
mise install
mise exec -- node tools/toolchain/run.mjs install --frozen-lockfile
mise exec -- node tools/toolchain/run.mjs --filter @agnes/cli build:local
mise exec -- node agnes.mjs serve

Open the printed local URL. The first-run guide walks through account setup, model selection and your first session; every step can be skipped. Model tests and real-model conversations may incur charges. Try your first request:

Read this project and describe its main directories. Do not modify files or run installation commands.

Keep serve running. Another terminal with the same AGH_HOME and AGNES_PROFILE can run node agnes.mjs for the terminal UI, or node agnes.mjs sessions --json to find the shared history. See the quickstart for the complete sequence. The documentation is available in English and 简体中文.

New product and old environments

Sessions, plugins, settings and accounts from the previous product do not carry over. Follow the upgrade guide to stop the old daemon, back up and move the old home and any applicable external directories, then configure a fresh environment. It covers macOS, Linux and Windows paths and the exact refusal messages. Startup never deletes or converts the old environment.

E_HOME_VERSION is a home-layout refusal; E_DATA_DIR_STALE / E_DATA_DIR_NEWER within a supported home use the separate data-format recovery procedure.

Current status and roadmap

AGH is a developer preview.

Area	State
Web workbench, CLI and terminal UI, SDK on shared sessions	Available
Agent loop, tool approvals, Trace, recovery	Available
Plugins: tools, loops, model adapters, panels, Skills, hooks, MCP, services	Available, with documented constraints
Plugin upgrades that keep running sessions on their pinned code	Available
Agent-drafted Skills and plugins with human review	Available
Webhook triggers, voice in the dialog	Available, opt-in
Jev loop	Official optional plugin
MHS device integration	Official plugin, integration in progress
Command sandbox and execution constraints	Platform-dependent
Platforms	macOS and Linux have maintained checks; Windows is not yet tested end to end

Next: connect the MHS plugin, test Windows end to end, and publish a public package release.

External effects are never promised exactly once, and ordinary plugin JavaScript is not isolated. See supported scope and known limitations, the verification guide and network deployment.

FAQ

Can I use AGH in production? Not yet. AGH is a developer preview without a public package release, installer or upgrade commitment. Validate deployment, audit and isolation requirements in your own environment.

Will my old sessions and settings carry over? No. This release starts from a fresh home; see New product and old environments.

Are plugins sandboxed? Ordinary backend plugins run as trusted in-process code, so install only packages you trust. Approvals and the command sandbox apply to the supported execution paths; they do not isolate arbitrary plugin code.

Which models can I use? Models connect through model accounts and model-adapter plugins, and each provider's catalog determines the available capabilities. The demos on this page were recorded with Agnes AI agnes-3.0-flash; quality and tool selection vary by model.

Can MHS control devices today? MHS is being connected as an official plugin in this release. Even when it is connected, canceling an AGH task does not establish that a device stopped safely; device controllers keep interlocks and emergency stops.

Community and license

AGH is open source. Star the project and Watch for updates if you are bringing AI into real deployments.

• Try it and give feedback: run an example and open an Issue for bugs and use cases.
• Build and share plugins: develop plugins, connect tools and build workbenches in your own projects under the license.
• Contribute code: the core is developed by the maintainer team for now; code and documentation pull requests are by invitation. See the contribution policy.

Report vulnerabilities privately under the security policy.

Project-authored code is licensed under the Apache License 2.0. Third-party components, adapted files and some examples retain their own license terms; see NOTICE and licensing details.