Agent Apprenticeship: turning real agent runs into reusable experience

What Agent Apprenticeship solves, and who it is aimed at

Most agent usage ends the same way. You give a CLI agent a task, it produces something, you read the output, and the run disappears. Nothing about how the agent got there survives into the next task except whatever you happen to remember. Agent Apprenticeship is built around the opposite assumption: that a finished run is raw material, and that the material should be captured in a form another run can consume.

The README frames this as "real-world agent work experience, looped into collective learning." The unit of capture is the Experience Compilation, produced at the end of a run and written to a local run folder. From there it can be inspected, checked, exported in full, or installed as Runtime Training. The intended audience is not someone writing their first prompt. It is someone already running Codex, Cursor, Claude Code, OpenClaw, OpenCode, Hermes Agent or a custom command template, who wants the loop around that agent to be structured and the result to be reusable.

The project also positions itself around task-level economic value, stating that for every task executed it can estimate economic value, especially across specialized domains. That framing appears in the README rather than in the repository layout, and it is worth treating as a stated goal rather than a measured result.

The loop: apprentice agent, mentor model, experience compilation

Three moving parts define the architecture, and the CLI exposes each one separately.

The first is the Apprentice Agent, the thing that actually does the work. The README lists Codex, Cursor, Claude Code, OpenClaw, OpenCode, Hermes Agent and Custom. The CLI auto-detects installed agent CLIs, and if it finds more than one you pick during setup. Custom takes a command template, so the apprentice does not have to be one of the named tools.

The second is the Mentor Model Provider, configured with apprentice configure model. This is the evaluating side of the loop. The README describes apprentice agents working with mentor agents, users, or human experts, and it exposes an Apprenticeship Mode setting with Autonomous, Expert-Led and Organization Custom. So the judgement step can be automated, human, or defined by an organization's own rules.

The third is the artifact. A run ends with a local run folder and an Experience Compilation path printed to the terminal. The compilation is the object that moves between runs: apprentice ecosystem inspect reads it, apprentice bundle check validates it, apprentice ecosystem export --full emits the complete version, and apprentice learn install turns it into Runtime Training that a later run can use. Loop depth is bounded, set through apprentice settings or overridden per session with AA_MAX_ITERATIONS.

The repository ships schemas/ alongside src/ and examples/minimal_experience_compilation/, which is what makes the compilation format inspectable rather than opaque. If you want to know exactly what a compilation contains before installing one, the schema directory is the place to look.

Installing Agent Apprenticeship and running a first task

The documented entry point is npx, which pulls the package and starts setup. The npm package requires Node 18 or newer, and the underlying Python package requires Python 3.11 or newer.

npx agent-apprenticeship init

If you would rather not go through the interactive setup, the README gives a defaults flag.

npx agent-apprenticeship init --defaults

There is also a global install path. Note that the installed command is apprentice; the long form agent-apprenticeship remains available as an alias, and pyproject.toml additionally registers aa-trace.

npm install -g agent-apprenticeship
apprentice init

Before running anything, check the setup. apprentice settings prints your configuration and apprentice doctor checks it. Mentor provider keys go in ~/.agent-apprenticeship/.env.local, with OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY and OPENROUTER_API_KEY shown as the recognized names. The README also allows exporting a key in the current shell session instead.

apprentice settings
apprentice doctor

Then run a task. The README's example is a market map request, and the CLI prints a run id you can follow.

apprentice run "Create a short market map for AI procurement tools."
apprentice watch <run_id>

When the run finishes, the terminal prints the local run folder and the Experience Compilation path. Inspect and validate it before doing anything else with it.

apprentice ecosystem inspect <experience_compilation_path>
apprentice bundle check <experience_compilation_path>

Installing it as Runtime Training is what closes the loop, and the README's next example is a fresh run that should benefit from what was installed.

apprentice learn install <experience_compilation_path>
apprentice run "Create a release checklist for an AI agent project."

Where the loop breaks: limits and the wrong use case

The most consequential constraint is that the value of Runtime Training depends on the quality of the compilation, and the quality of the compilation depends on the mentor. If the mentor model is weak, or if Expert-Led mode is selected and nobody actually reviews, you are installing a record of a mediocre run and calling it experience. The CLI gives you apprentice bundle check, but a passing bundle check tells you the artifact is well-formed, not that its contents are worth learning from.

Cost is the second constraint. Every run involves an apprentice agent plus a mentor model, and AA_MAX_ITERATIONS bounds how many loops a run may take. Raising that number multiplies both sides of the bill. The README does not describe a budget cap, so loop depth is the only documented lever.

The third constraint is that this is a loop framework, not a task tool. If your work is a single prompt whose output you read and discard, the setup cost of configuring an apprentice, a mentor provider, a contribution mode and a loop depth buys you nothing. A plain agent CLI is the better choice there.

There is also a real gap in the documentation. The README describes contribution modes, Public Ecosystem and Private Internal Only, and describes pulling and installing shared experience, but it does not document how contributed experience is reviewed before it enters the ecosystem, and it does not document rollback for an installed Runtime Training. If you install a compilation that degrades your agent, the README does not say how to undo it.

How it differs from a plain agent CLI or a trace logger

The obvious comparison is to the agent CLIs themselves. Codex, Cursor and Claude Code each run a task and stop. Agent Apprenticeship sits above them: it invokes the agent, wraps the invocation in a bounded loop, routes the result through a separate mentor model, and emits an artifact with a schema. You can absolutely keep using the underlying CLI directly; the difference is that the direct path leaves no installable object behind.

A second comparison is to trace and observability tooling, which also captures agent runs. The divergence is what happens after capture. A trace tool is for looking at what happened. An Experience Compilation is written to be installed with apprentice learn install and consumed by a later run. The README's phrasing is that execution turns into shared improvement, and the mechanism for that is install, not inspection.

A third comparison is to running your own evaluation harness around an agent. That gives you control over the judge and the metrics, and it is more work to build. Agent Apprenticeship supplies the loop, the modes, the schemas and the compilation format out of the box, at the cost of accepting its opinion about what a run should produce.

Maintenance, licensing and the cost of upgrading

The repository is not archived, and the last push was on 2026-07-06. The most recent release is v0.2.0, tagged on 2026-07-03, while package.json and pyproject.toml both declare version 0.2.1. That version mismatch between the release tag and the manifests is worth knowing before you pin a dependency, because the two do not agree.

The licence is MIT, declared in package.json and present as a top-level LICENSE file, which permits commercial use and modification. That is a statement about the licence text, not advice about your situation; if you plan to contribute experience derived from client work, read the contribution modes and your own obligations rather than relying on the licence alone.

Upgrade cost is concentrated in the artifact format. Because compilations are governed by schemas/ and validated with apprentice bundle check, a format change between versions is the thing most likely to break an existing workflow. There is no documented migration path between compilation format versions, so the practical approach is to treat installed Runtime Training as version-coupled to the CLI that produced it. Python 3.11 and Node 18 are the floors to check before upgrading.

Editorial conclusion

Adopt Agent Apprenticeship if you already drive Codex, Claude Code, Cursor or a custom agent CLI and want each run to leave behind an inspectable, installable artifact instead of a transcript you never reopen. Skip it if your work is a single prompt with no evaluation step, or if you cannot accept that the loop and the mentor model are two more moving parts that can fail independently of your agent. Before you trust a run, check three things: that apprentice doctor passes with the provider key you intend to use, that the Experience Compilation printed at the end of the run exists on disk, and that apprentice bundle check reports it as usable before you install it with apprentice learn install.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. ray-r-ren/agent-apprenticeship on GitHub
4. README
5. Releases