Self-improving agents

AgentRun can turn repeated work into reusable notes, skills, and validated workflow drafts. New runs use what the agent has already learned instead of rediscovering the same steps.

Enable learning

Set learning: true on an agentic definition, or enable Learning when editing the agent in the console. Learning is opt-in and is saved on the agent's revision. The server's --learning off switch overrides it.

Start with a task the agent will repeat: summarizing similar reports, extracting records from the same source, or following a recurring research process. Give the agent useful instructions and a working model/tool setup first.

What happens between runs

Stage	What AgentRun does
Start	Pin the agent's accepted learning at the time the run begins.
Execute	Give the harness the relevant notes, skills, and available learned workflows.
Reflect	After the task, propose information or procedures worth reusing.
Check	Validate proposals, check for secrets and invalid structure, and grade whether they are useful.
Save	Commit accepted changes; hold sensitive proposals for the owner's review.
Reuse	Give accepted learning to later runs of this agent.

A resumed run or follow-up keeps its original learning snapshot. Another run finishing does not change the instructions underneath work already in progress.

What the agent can retain

• Notes capture preferences, corrections, project facts, and references.
• Skills describe a reusable procedure in a SKILL.md file.
• Workflow drafts capture repeatable steps in the workflow format. Structural validation does not execute the draft; test it on representative inputs before relying on its results.

Reusing a workflow still processes the new input. It does not return a cached answer from the earlier task. Learning stays with the agent that learned it; unrelated agents do not automatically share it.

The exact proposal checks, workflow validation, and harness delivery are described in the current learning specification.

Inspect and control the changes

The console shows what a run was given, what it proposed, and what was accepted or rejected. Use the learning history to trace a change back to its run.

API read	What it returns
GET /v2/agents/{id}/learning	Accepted learning, recent changes, and available impact measurements.
GET /v2/agents/{id}/learning/notes	A paginated list of learning items.
GET /v2/agents/{id}/learning/log	The learning change history.
GET /v2/runs/{id}/learning	What this run received, proposed, and learned.
GET /v2/runs/{id}/learning/diff	The proposed or merged changes for this run.

Current source supports editing, retiring, and restoring learning items. Edits require an ETag precondition to avoid overwriting another change. Approving a pending item or restoring a retired one requires the owner's signed-in console session; an API token cannot approve its own learning. See Learning controls.

Measure improvement over repeated work

Compare similar inputs across several runs. Look at task quality, duration, model usage, and the cost of learning itself. A shorter run is useful only if it still produces the right result.

The current learning API separates task cost from reflection/grading cost. Its impact comparison is available only after both the earlier and learned cohorts have at least two runs. Savings are workload-dependent; a single successful run does not establish them.

Continue with Durability and compute.