Agent Apprenticeship: Turning Agent Runs Into Reusable Training Experience
The living ecosystem where AI agents complete tasks through workflow loops, improve through iterative execution, are evaluated by mentor agents or humans in the loop, and turn completed work into reusable work experience and data to improve future agents.
At a glance
- What is it?
- Agent Apprenticeship is an MIT-licensed Python tool that wraps local coding agents in a mentor-reviewed workflow loop and exports each run as an Experience Compilation that can be reinstalled as Runtime Training. The mechanism is clear from the README; the economics and dataset quality claims are not verifiable from the material alone.
- Who is it for?
- Adopt Agent Apprenticeship if you already run a local coding agent such as Codex, Cursor or Claude Code and want each run to leave a structured artifact you can reinstall with apprentice learn install rather than a chat log you will never reopen.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 71 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The gap Agent Apprenticeship targets: agent runs that vanish when the terminal closes
Most local agent sessions end the same way. You give a coding CLI a task, it edits files, you accept or reject the diff, and the transcript sits in a log directory that nobody reads again. The next task starts from zero context. Agent Apprenticeship is aimed at that gap. The README frames it as "real-world agent work experience, looped into collective learning," and the concrete promise is narrower than the slogan: each run produces an Experience Compilation, and that artifact can be reinstalled as Runtime Training for a later run. The intended user is someone already running Codex, Cursor, Claude Code, OpenClaw, OpenCode or Hermes Agent locally, who wants the output of those runs to accumulate instead of resetting. It is not a hosted agent platform. It is a wrapper plus a local store plus an optional exchange layer, and the README's own command list reflects that: init, configure, run, watch, inspect, export, learn install.
What actually happens between apprentice run and learn install
The loop has four visible stages. First, apprentice run takes a task string and dispatches it to a configured Apprentice Agent. Second, the run iterates, with the depth bounded by a setting the README exposes as AA_MAX_ITERATIONS, defaulting to 3 in the one-off example. Third, evaluation happens through what the README calls mentor agents or humans in the loop, configured via apprentice configure model against a Mentor Model Provider. Fourth, the completed run is written to a local run folder and an Experience Compilation path, which apprentice ecosystem inspect and apprentice bundle check can read. That compilation is the unit of value. apprentice learn install takes an Experience Compilation path or an ecosystem id and installs it as Runtime Training, which a subsequent apprentice run is meant to use. The data flow is local-first: runs land on disk, compilations are exportable, and only then does the ecosystem layer matter. Contribution mode is a separate switch, set in apprentice settings, between Public Ecosystem and Private Internal Only. Nothing in the README describes how Runtime Training is injected into the agent prompt, which is the single most important implementation detail for judging whether the loop is real or decorative.
Install, keys and the first run
The install path is a single npx command, and the README also documents a global npm install. After that the binary is apprentice, with agent-apprenticeship kept as a long-form alias. Setup is interactive by default, or non-interactive with npx agent-apprenticeship init --defaults. Mentor keys go in ~/.agent-apprenticeship/.env.local as OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY or OPENROUTER_API_KEY, or as shell exports for the current session. apprentice doctor is the check command, and apprentice settings is where loop depth and contribution mode live. Agent selection is auto-detected from installed CLIs, with a Custom option that takes a command template: apprentice configure agent custom --command-template "my-agent run --workspace {workspace} --prompt-file {prompt_file}". That template is the escape hatch for any agent not on the supported list, and the two placeholders are the entire documented contract between the tool and the underlying agent. A first run is apprentice run "Create a short market map for AI procurement tools.", followed by apprentice watch <run_id>. The README states that on completion the tool prints the local run folder and the Experience Compilation path, which is the handoff point to apprentice ecosystem inspect.
Loop depth, mentor cost and the failure modes the README does not address
The clearest limitation is loop depth. AA_MAX_ITERATIONS=3 is the documented one-off example, and the README does not explain what happens at the ceiling: whether the run stops mid-task, returns a partial compilation, or fails outright. That matters because a run that terminates at the cap still produces an Experience Compilation, and a compilation built from an unfinished task is exactly the kind of artifact that pollutes a shared dataset. The second cost is mentor calls. Every iteration is evaluated by a Mentor Model Provider, so a three-iteration run against a hosted model is at minimum three additional API calls on top of the apprentice agent's own usage, and the README gives no batching, caching or budget control for that. The third issue is versioning. Runtime Training is installed by path or ecosystem id, with no documented version pin, so there is no stated way to reproduce a run against the exact training state that produced it. Finally, the seed dataset numbers (500+ seed tasks, 495 lessons, 1000+ traces, 505 compilations, 39k+ records) are self-reported in the README and hosted on Hugging Face; the repository material gives no evaluation of their quality, and none of those figures should be read as evidence that the loop improves agent output.
How this differs from LangSmith, Weights & Biases Weave and plain agent logs
The nearest comparison is trace tooling such as LangSmith or Weights & Biases Weave. Those collect runs, let you annotate them, and give you dashboards for evaluation. The direction of travel is inward: telemetry flows to a store, and a human reads it. Agent Apprenticeship points the other way. Its terminal artifact is an Experience Compilation that is meant to be installed back into the agent with apprentice learn install and consumed by the next run. That is a different bet: the trace is not an observation, it is an input. The trade-off is that the observation tools have mature query, comparison and regression-testing surfaces, while Agent Apprenticeship's ecosystem surface is four commands (search, inspect, pull, export) and a contribution switch between Public Ecosystem and Private Internal Only. If your goal is to understand why a run failed, a trace dashboard is the better tool. If your goal is to feed a successful run back into the next one without hand-editing a prompt file, this is the narrower thing that does that.
Maintenance surface, licence and what the repository layout implies
The public repository layout is bin/, src/, schemas/, examples/ and selected_ale_tasks_demo/. The schemas directory is the part worth checking before adoption, because the Experience Compilation format is the interface you will be locked into once you have a directory of them; the README does not document schema versioning or a migration path. The selected_ale_tasks_demo directory holds what the README calls mirrored transfer tasks, which suggests the project tests whether experience from one workflow family transfers to a related one, but no results are given. The licence is MIT, which permits commercial use and redistribution with the copyright notice retained; it also means there is no warranty and no support obligation, and this is not legal advice. Upgrade cost is a real consideration: the project is at v0.2.0, released 2026-07-03, with the last push three days later, so pre-1.0 churn in the compilation schema or the settings keys is plausible, and any compilations you export today may need re-export after a breaking change. The npm package and the Hugging Face dataset are versioned separately, which adds a second thing to track.
Who should run this now, and the one check to do before contributing
The fit is a small team or individual already paying for a local coding agent and a model API key, working on repeatable task families where a prior run's approach is plausibly reusable. The misfit is anyone who needs a stable API contract, anyone running untrusted third-party code through an agent inside a pipeline, and anyone who expects the seed dataset to substitute for their own evaluation. Before switching contribution mode away from Private Internal Only, inspect one compilation end to end. Run apprentice run with AA_MAX_ITERATIONS=3, then apprentice ecosystem inspect and apprentice bundle check on the output, and read the schema in schemas/ against what was actually written. If the compilation contains the task, the iterations, the mentor judgements and enough context to re-run the task, the loop is doing what it claims. If it contains only a summary, then apprentice learn install is installing a description rather than experience, and the ecosystem layer is not worth the contribution.
Editorial conclusion
Adopt Agent Apprenticeship if you already run a local coding agent such as Codex, Cursor or Claude Code and want each run to leave a structured artifact you can reinstall with apprentice learn install rather than a chat log you will never reopen. Do not adopt it if you need a stable, versioned API for production pipelines or if you cannot accept that the loop depth is capped by AA_MAX_ITERATIONS and that the seed dataset's quality claims are not reproducible from the README alone. Verify first: run apprentice doctor after setting a key in ~/.agent-apprenticeship/.env.local, run one task with AA_MAX_ITERATIONS=3, then read the generated Experience Compilation before you let any run contribute to the Public Ecosystem mode.
Community notes