Adaptive Agent Harness

繁中 · English · 简中 · Español · Português · Français · Deutsch · 日本語 · 한국어 · Русский · العربية · Italiano · Tiếng Việt · ไทย · Čeština · Suomi · Norsk · Lietuvių

The canonical README is English. The language switcher intentionally places Traditional Chinese first.

The 30-second answer

Most agents are asked to solve large problems with one expensive, forgetful interface: the prompt.

Adaptive Agent Harness gives them a programmable workbench instead. A host can use two sibling surfaces side by side: persistent IPython workspaces for stateful computation, and bounded RLM jobs for brokered evidence and model calls. Durable receipts and a small MCP surface make both governable and reconnectable.

The current public alpha does not execute an RLM job inside an IPython workspace or share state between them automatically. A host must transfer selected evidence, values, or artifacts explicitly.

The result is a practical foundation for agents that need to:

• reason over inputs larger than a single context window;
• turn repeated tool-call chatter into compact Python programs;
• keep variables, tables, helper functions, and evidence alive across steps;
• survive a frontend disconnect without confusing it with cancellation;
• resume only from a certain, receipt-backed boundary;
• leave final authority, credentials, effects, and delivery with the host.

The Python distribution is currently named adaptive-agent-runtime. This repository is its public project home under the Adaptive Agent Harness name.

What is an RLM?

A Recursive Language Model (RLM) treats a long prompt or corpus as data in an external environment. Instead of squeezing everything into the model's active context, the model can write programs that:

1. inspect the data;
2. filter, split, join, rank, or summarize it;
3. call a model or subagent on selected slices;
4. combine the returned evidence;
5. repeat within explicit limits.

The important idea is not “infinite recursion.” It is programmatic inference-time scaling: spend model calls where they add value, and use ordinary computation everywhere else.

A simple mental model:

Traditional long-context agent
  prompt -> one model call -> more prompt -> another model call

RLM-style agent
  long input -> Python examines it -> selected model/subagent calls
             -> Python combines evidence -> bounded answer + trace

The term comes from Zhang, Kraska, and Khattab's Recursive Language Models work. Adaptive Agent Harness implements a bounded, brokered RLM runtime; it does not claim that every workload needs recursion or that more calls automatically produce a better answer.

Why IPython?

Long-running agents also need somewhere to think with data, not merely talk about it. IPython complements the RLM surface by giving the host a separate persistent computational workspace:

• variables stay available across execution steps;
• DataFrames, arrays, parsed documents, and graph results can be inspected directly;
• helper functions can replace repetitive tool-call loops;
• the model can test a hypothesis, inspect the result, and refine the next step;
• compact references can stay in context while full data remains in the workspace;
• selected JSON-like state can be checkpointed without pretending arbitrary live Python objects are portable.

A chat transcript is a record of what was said. An IPython workspace is a working set of what has been computed.

That distinction matters for long research, codebase analysis, data investigation, evaluation, and any task where the agent would otherwise keep rereading the same material.

Why RLM × IPython?

Here, “×” means host composition, not an in-process RLM/workspace binding. Each sibling surface covers a different failure mode:

A host can compose them by passing selected, explicit evidence or artifacts between the surfaces. There is no implicit shared namespace or automatic RLM-to-IPython execution path.

flowchart LR
    U[User task] --> H[Host agent / harness]
    H --> A[Adaptive Agent Harness]
    A --> R[Bounded RLM job]
    A --> I[Persistent IPython workspace]
    R --> B[Brokered model / subagent / evidence calls]
    I --> P[Python transforms, tests, tables]
    B --> E[Receipts + trace]
    P --> E
    E --> H
    H --> D[Authorize effects and deliver]

The governing rules are deliberately simple:

The host composes the sibling surfaces explicitly; Python is a workspace language, and the host remains the authority boundary.

What you get

A programmable agent workbench

• persistent plain-Python and IPython workspaces;
• bounded code execution with generation and revision checks;
• NumPy and pandas available in the default runtime;
• deterministic JSON-subset checkpoints with explicit exclusions;
• artifact-backed handling for larger or non-inline results.

A brokered RLM engine

• persisted RLM jobs, steps, usage, and terminal results;
• explicit model-request, subagent, artifact, and evidence broker contracts;
• per-operation wall-time, model-call, token, child-operation, and artifact budgets;
• retained handles and receipts instead of “the tool probably ran”;
• reconciliation when a call may have started but no authoritative receipt exists.

Durable operations

• stable logical operation IDs separate from attempts, workers, leases, and frontend connections;
• accepted work that can outlive one MCP request;
• cursor-readable events, status, cancel, and reconcile operations;
• a durable supervisor with ephemeral authenticated frontends;
• exact process-start identity rather than PID-only ownership;
• successor attempts that preserve deadline, cancellation, and cumulative usage.

Portable contracts

• 30 MCP tools on the current v7 surface;
• versioned schemas and digest-bound assets;
• bundled operation guidance for Codex and Hermes profiles;
• deterministic reference brokers for development and conformance testing;
• host-neutral boundaries that do not require AHC, Prime Agent, or NOOA.

Where it shines

Adaptive Agent Harness is a strong fit for:

• long-document research — search, slice, compare, and recursively synthesize evidence;
• codebase investigation — retain symbol sets, call paths, test evidence, and candidate changes;
• data analysis — move between natural-language questions and DataFrame operations;
• evaluation pipelines — keep inputs, scores, receipts, and artifacts bound to one operation;
• agent infrastructure experiments — test durable execution and recovery without building a second user-facing agent OS;
• controlled worker integration — place richer workers behind explicit budgets, handles, and host acceptance.

It is intentionally narrower than a full autonomous coding agent. That is useful when you already have an orchestrator and need a dependable computation and evidence plane underneath it.

How this relates to other RLM projects

We learned from public work without pretending the projects are interchangeable:

• Prime Agent demonstrates the product value of a persistent IPython environment, programmatic tool use, native child agents, and daemon-backed continuity. Prime is a fuller coding/research agent experience. Adaptive Agent Harness is the narrower runtime/control layer and can complement a worker like Prime rather than replace it.
• NVIDIA Object Oriented Agents (NOOA) demonstrates a Python-native, typed object model for agent capabilities and CodeAct-style orchestration. NOOA is design input only here: there is no bundled NOOA adapter or dependency.
• Recursive Language Models supplies the core inference paradigm: treat long context as an external environment that the model can programmatically inspect and recursively query.

See Why RLM + IPython for the deeper design rationale and source notes.

Quick start

Public alpha: use a pinned tag, inspect the capabilities returned by your host, and start with disposable workspaces. This project executes model-authored Python and is not a security sandbox.

Install from the first public tag

uv tool install --force \
  "git+https://github.com/phenomenoner/[email protected]"

Codex App setup

aar-codex-setup

Restart Codex App if the setup receipt says configuration changed, then call aar_capabilities in a fresh task.

Develop from source

git clone https://github.com/phenomenoner/adaptive-agent-harness.git
cd adaptive-agent-harness
uv sync --locked
uv run aar-contract verify
uv run pytest -q

Start with the MCP workflow

1. Call aar_capabilities and bind to the returned runtime generation and capability digest.
2. Create or attach a workspace, or submit a bounded rlm.execute operation.
3. Keep the returned operation handle.
4. Read status/events from a fresh authorized connection when needed.
5. Reconcile uncertainty before retrying any effect-shaped work.

Detailed install and host notes:

• Codex installation
• Host compatibility
• Architecture
• Operation skill
• Technical verification status

Architecture

Adaptive Agent Harness follows a small-waist design:

Host / orchestrator
  ├─ owns identity, provider credentials, approvals, effects, delivery
  └─ connects through MCP or a native adapter
          |
          v
Adaptive Agent Harness
  ├─ operation registry + event log + receipts
  ├─ bounded RLM engine + broker journal
  ├─ programmable workspace manager
  ├─ durable supervisor + exact worker identity
  ├─ checkpoints, artifacts, assets, export/import
  └─ capability, grant, budget, deadline, and generation fencing
          |
          v
Plain Python / IPython workers and host-authorized brokers

The MCP frontend is intentionally replaceable. It does not own the continuity database or the worker lifecycle; the durable supervisor does.

Project status

Current public alpha: 0.3.0a0.

Reproduced from this public candidate:

• Python 3.11 through 3.14 coverage;
• 30-tool MCP v7 surface;
• additive SQLite schema through v5;
• full repository run: 245 passed, 1 platform-gated skip;
• a clean exact-wheel supervisor/frontend probe on Linux/WSL;
• durable supervisor, frontend replacement, process-loss, stale-writer, receipt-reuse, and policy-bound RLM successor scenarios.

Earlier native-Windows and installed-Hermes compatibility rows are retained asmaintainer-reported historical context. Their supporting host receipts are not included in thispublic repository, so those rows are not independently auditable from this tree and are not releasecriteria for the public source candidate.

Still open:

• portable automatic restoration of broader IPython workspace state into a new generation;
• general external-effect reconciliation adapters;
• multi-tenant security isolation;
• generic exactly-once effects;
• package-registry publication and stable API guarantees.

Read TECHNICAL-STATUS.md, HOST-COMPATIBILITY.md, and WAL.md before making production claims.

What this project does not do

• It is not a security sandbox.
• It does not hold your provider credentials by design.
• It does not execute arbitrary external effects or deliver user messages on its own.
• It does not promise universal exactly-once semantics.
• It does not resurrect arbitrary Python stacks, sockets, generators, or native process memory.
• It does not make Prime Agent, NOOA, CodeGraph, Hermes, Codex, or AHC a runtime dependency.

The authority statement is:

Adaptive Agent Harness computes and proposes. The host authorizes and delivers.

Contributing

Issues, focused pull requests, compatibility reports, and reproducible failure fixtures are welcome. Please read CONTRIBUTING.md and SECURITY.md first.

Useful contribution areas:

• additional host profiles and black-box compatibility rows;
• checkpoint eligibility and exclusion ergonomics;
• broker/effect reconciliation adapters;
• bounded RLM strategies and evidence-heavy benchmarks;
• worker backends and artifact stores;
• documentation and translation corrections.

License

MIT © 2026 phenomenoner.

References

• Alex L. Zhang, Tim Kraska, and Omar Khattab, Recursive Language Models, arXiv:2512.24601.
• Prime Agent, Prime Intellect.
• NVIDIA Object Oriented Agents, NVIDIA-NeMo.
• Model Context Protocol.