ray-r-ren/agent-apprenticeship

What it is

Agent Apprenticeship is an open‑source toolkit that lets you run AI‑agents (e.g., OpenAI Codex, Claude Code, Anthropic, Gemini, etc.) in a repeatable “work loop”. An agent performs a real‑world task, a mentor model (or a human) evaluates the result, and the whole execution trace is saved as an experience compilation. Those compilations become training signals that can be re‑used to improve future runs.

Core ideas

Idea	What it means
Iterative workflow loops	An agent can be run for several iterations (controlled by AA_MAX_ITERATIONS) until a satisfactory outcome is reached.
Mentor‑in‑the‑loop	A second model (or a human) reviews the agent’s output and provides feedback that is stored with the trace.
Experience compilation	All files produced during a run – prompts, outputs, mentor feedback, economic‑value estimate – are bundled together and can be exported, searched, or installed as “runtime training”.
Seed dataset	A Hugging‑Face dataset containing 500+ curated tasks, ~1 000 execution traces and ~39 k structured records that serve as a starter ecosystem.
Public vs private ecosystem	Users can contribute their compilations to a shared public pool or keep them private for internal use.

How you use it

1. Install – either with npx agent-apprenticeship init (one‑off) or npm i -g agent-apprenticeship (global). The CLI command is apprentice.
2. Configure – tell the tool which apprentice agent you want (apprentice configure agent …) and which mentor model provider supplies the API keys (~/.agent‑apprenticeship/.env.local).
3. Run a task – apprentice run "<natural‑language task>". The tool launches the chosen agent, collects its output, sends it to the mentor model for evaluation, and repeats up to the configured loop depth.
4. Watch & inspect – apprentice watch <run_id> streams progress; after completion you can explore the generated experience compilation with apprentice ecosystem inspect … or bundle check ….
5. Reuse the knowledge – apprentice learn install <compilation> registers the trace as runtime training, which the next run can draw on to improve its prompts or decisions.
6. Share – optionally push the compilation to the public ecosystem (apprentice ecosystem export …) or keep it private.

Who it’s for

• Developers who want to experiment with autonomous agents on concrete tasks without building the loop infrastructure from scratch.
• Researchers interested in collecting large‑scale agent execution data for fine‑tuning or reinforcement learning.
• Teams that want a reproducible way to capture “agent work experience” and reuse it across projects.

What you get out of the box

• A CLI that orchestrates agent‑mentor loops.
• Auto‑detection of several popular code‑generation agents (Codex, Claude Code, Cursor, etc.) and a custom‑command hook.
• Pre‑populated seed dataset on Hugging Face with hundreds of task‑trace bundles.
• Commands to search, inspect, export, and install experience compilations.

Limitations (as per README)

• The system relies on external model APIs; you must provide your own keys.
• “Runtime training” is a plug‑in concept – the README does not detail how the installed compilation actually influences later runs beyond being available for inspection.
• Economic‑value estimation is mentioned but not described in detail.

Quick start checklist

# 1. Install / initialise
npx agent-apprenticeship init

# 2. Configure model keys
export OPENAI_API_KEY="…"
apprentice configure model

# 3. Choose an apprentice agent (e.g., Codex)
apprentice configure agent codex

# 4. Run a task
apprentice run "Create a short market map for AI procurement tools."

# 5. Watch progress
apprentice watch <run_id>

# 6. Re‑use the result
apprentice learn install <experience_compilation_path>

---

All information above is taken directly from the repository’s README; no external assumptions have been added.