# 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](/docs/learning-reference).

## 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](/docs/server-reference#what-a-person-sees-and-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](/docs/durability-and-compute).