Using and training adapters

An adapter is a directory of files that an agent loads when it works on a task. Those files can contain instructions, skills, tools, and role definitions. Training produces new versions of that directory from task feedback. The agent’s model weights are unchanged.

There are two workflows: using an existing adapter and training an adapter. You can use an adapter without running the training system. For commands to try first, follow Quick Start.

See the two workflows

Switch views below. In the training view, select a component or use Next to follow one iteration. The arrows show handoffs; the detail below the diagram explains what is passed and who owns the operation.

USE TIME · THE ADAPTER IS AN INPUT

Portable files Adapter directory adapter.yaml
ADAPTER.md
skills/ · tools · roles* *As declared by the template.

→

Host connector / your pipeline Deployment Context → instructions
Tools → callable tools
Skills / roles → host files

→

Your acting pipeline Acting agent Receives a task
Uses the adapter's exports
Produces an answer

OfficeQA: the agent reads ADAPTER.md as context and adds it to the system prompt, as the skill, on each run. A host connector instead prepares workspace files before the agent starts.

The Trainer and Evolver are not needed to use an existing adapter. Runtime dependencies still apply.

TRAIN TIME · FOLLOW ONE ITERATION

Task owner supplies data, pipeline, judge, task-infoTemplate supplies starting files, exports, editable paths, checks

TrainerOrchestrates every handoff below · tracks budget and progress

1 · Task codePipeline / acting agentrun(task, adapter)Current adapter + task 2 · Task codeJudgescore(task, output)Scores the output 3 · Trainer writesLearning materiallearning_material/step_N/Saved for each step 4 · Learning methodEvolver / learnerstep(ctx)Reads the learning material 5 · Template rulesCheck and repaircheck_spec(adapter, root)Check files; restore violations 6 · Trainer writesGit + run recordscommit · state · steps.jsonlCommits the version; saves state and records

↻ The next batch starts at 1 with the accepted adapter. A failed Evolver step retains the previous version.

1. Run the current adapter

The Trainer exports the current Git version and gives its path and one task to your pipeline. The acting agent consumes the exports. The pipeline returns RunOutput: an answer plus any logs and usage it records.

task + adapter path → RunOutput

A passing check means the adapter conforms to its template. Performance is measured by the pipeline and judge; candidate validation belongs to the Evolver.

At use time: what does an adapter look like?

The simplest adapter uses the built-in prompt-only@1.0 template:

adapter/
  adapter.yaml    declares the exports and which files may change
  ADAPTER.md      instructions given to the acting agent
  EVOLVER.md      explains the editable structure to the learner
  README.md      instructions for people
  CARD.md        provenance and evaluation results, added at the end of training

ADAPTER.md is every adapter’s context for the acting agent (a fixed, required file). EVOLVER.md guides the learner; CARD.md records where the adapter came from. Neither is automatically included in the acting agent’s prompt.

For example, ADAPTER.md might say “check the unit and scale of each source figure before calculating.” This affects behavior when the pipeline makes the text available to the agent. The file has no effect just by existing on disk.

How does it reach the agent?

Export	Codex deployment	Claude Code deployment	Custom pipeline
Context	A block in AGENTS.md	A block in CLAUDE.md	Read the context and include it in model messages.
Tools, when declared	MCP server configuration	MCP server configuration	Integrate the declared tools through a supported calling mechanism.
Roles and skills, when declared	Host files generated by the connector	Host files generated by the connector	Provide support for the exports the chosen adapter needs.

hermit deploy prepares a workspace; it does not launch the acting agent. Context and skills are copied or rendered at deployment, so redeploy after changing them. Generated tool-server configuration can reference the original adapter directory, which must remain available.

For the exact source-to-host paths, managed instruction blocks, and the learner’s editable working copy, see the Adapter file interface.

In OfficeQA, examples/officeqa/utils/agent/agent.py loads the adapter’s context for each execution and passes it to SkillOpt’s rollout as the skill in the system prompt. The file tools, model choice, and tool-calling loop remain defined in that agent. This particular integration consumes context only.

The Lean collaboration template has more exports: instructions, skills, and tools for sharing proof work. Its tools also need Lean/Mathlib and per-run shared state. Packaging files as an adapter does not install these dependencies or make every host support them automatically.

At training time: who supplies what?

The framework trains through interfaces you provide. The task owner supplies the dataset and code that runs and scores the agent. A template defines what is editable. An Evolver implements a learning method. The Trainer coordinates their execution.

Component	Supplied by	Responsibility
Task data and description	Task owner	Problems, train/validation/test splits, and a description of the objective.
Pipeline	Task owner	Run the acting agent on a task with an adapter; return the answer and available logs and usage.
Judge	Task owner	Score the answer and produce feedback.
Template	Template author	Supply starting files, declare exports and editable paths, and define validity checks.
Evolver	Learning-method author	Use the evidence to edit or select an adapter.
Trainer	Framework	Run batches, prepare evidence, invoke the Evolver, check edits, track budgets, and save versions and state.

One person can supply several parts. They are separate so a new task can reuse a learning method, or several methods can be compared on the same task and editable files.

The pipeline runs the acting agent

run(task, adapter) -> RunOutput
score(task, output) -> JudgeResult

The Trainer passes a task dictionary and an adapter path to run. The pipeline deploys the adapter as needed and runs the acting agent. Its result includes an output for the judge, plus optional logs, messages, and usage. The Trainer then calls score with that result.

The pipeline owns the host, model, number of acting agents, tools, and execution loop. The Trainer does not rewrite this code. Training and evaluation call the same pipeline and judge. adapter=None runs without a harness adapter and provides a baseline.

The template defines the scope of learning

For prompt-only@1.0, the relevant manifest declarations are:

exports:
  context: ADAPTER.md
structure:
  learnable:
    - path: ADAPTER.md
      format: {text: true, max_bytes: 40000}
  fixed:
    - EVOLVER.md
    - README.md

The Evolver can rewrite the instruction file. It cannot change the export declaration, edit fixed files, or add files outside the learnable paths. The template remains the reference for checking later versions.

The template contains the starting instructions and their rules. An evolved adapter contains later instructions plus the same fixed files. Training can start from the template or a previous adapter.

In lean-collab@1.0, instructions and skills are learnable while collaboration code stays fixed. A different template could allow code edits and provide corresponding checks. “Training the harness” has a specific scope for each template.

The Evolver is the learner

The Evolver receives a working copy of the adapter, task information, results, adapter history, and its own persistent state. It may rewrite instructions, run candidate experiments, keep a candidate pool, or return the current adapter unchanged.

The built-in gepa and skillopt methods ask a model to rewrite Markdown using scored examples and test a rewrite before keeping it. The codex and claude methods launch a learner agent to inspect material and edit files. The learner improves what future task executions will consume; the acting agent solves those tasks. The two roles can use different models.

Template and Evolver are separate, but still need compatible capabilities. A method that only rewrites Markdown will not automatically learn executable tools just because a template permits code changes.

One iteration, with the actual handoffs

OfficeQA’s smoke configuration runs four training questions in two batches. For the first batch:

1. Trainer → pipeline. Export the current adapter from Git and call run(task, adapter) for each question. The pipeline loads its instructions, calls the acting model, and returns answers and logs.

2. Trainer → judge. Call score(task, output). Scores and feedback describe the adapter that ran this batch.

3. Trainer → learning material. Write inputs, outputs, judge results, and available trajectories under learning_material/step_0001/. Point learning_material/current at that directory.

4. Trainer → Evolver. Call step(ctx). The learner reads the material and edits ctx.workspace.adapter. It returns a StepResult describing status and usage. The adapter itself is the directory left on disk.

5. Trainer → specification check. Run check_spec. For a specification violation, restore affected files from the template or previous adapter and check again. Repair can fall back to the previous version. An Evolver result marked failed or out of budget keeps the previous adapter.

6. Trainer → Git and run records. Commit changes and save the learner’s state, report, usage, and check results. The accepted adapter is used for the next batch.

The Trainer calls setup before the first step and finalize at the end. The Evolver hands back one adapter per step even if it compares many candidates internally. The Trainer handles common experiment machinery; the Evolver decides how to update and select candidates.

Suppose an answer used figures in incompatible units. The learner could add a unit-checking instruction, and the next batch would run with it. This is an illustrative update, not a measured OfficeQA result.

Acceptance is different from improvement

check_spec checks fixed files, allowed paths, formats, export loading, and template-specific requirements. It does not measure task performance. A valid edit can lower the score; the Trainer does not reject it for that reason. The Evolver may validate candidates itself. The prompt-only method (a Codex session per step) does not test its rewrite before returning it.

Step 1 and step 2 use different task batches. A higher score on step 2 alone does not show improvement: the questions also changed. Run separate evaluations on the same held-out test split to compare final, the adapter the run started from (root, or the start_from adapter when the config sets one, such as OfficeQA’s ../utils/seed_adapter), and none; see OfficeQA evaluation.

final means the adapter selected by finalize, which defaults to the current adapter. It does not mean “the highest-scoring checkpoint.” The framework does not automatically evaluate the final adapter or run baselines.

What survives training, and what gets deployed?

Item	Location	Used for
Adapter files	Git versions and the run’s checkout/	Deployment or the starting point of a new run.
Learner state	workspace/state/, with per-step snapshots	Continuing the learning method, such as its search history or candidate pool.
Results and logs	learning_material/ and run records	Learning, inspection, and experiment accounting.
Acting runtime state	Location chosen by the pipeline or adapter runtime	One execution’s working data, such as a shared lemma library.

A final adapter includes CARD.md with provenance and recorded evaluation results. Deployment needs the adapter and the environment its exports depend on; it does not need the Evolver or its state. Starting a new training run from that adapter starts fresh learner state. Resuming an unfinished run restores its saved state and progress.

A template may allow learned memories or examples inside the adapter. They then travel as adapter content. Recording a trajectory during training alone does not make it part of the deployed package.

Available in this version

Version 0.1.0 includes the prompt-only, lean-collab, mwm, harness2-codex and continual-harness templates and the codex, claude, gepa, skillopt, mwm, harness2_upstream and continual_harness Evolvers. OfficeQA and CL-Bench (database, poker) provide end-to-end task integrations; the Lean template can be deployed, but its complete training pipeline has not been migrated.

For detailed contracts, continue to Adapter, Evolver, Trainer, or Task integration. To implement a method, see Custom Evolver integration.