Skip to content
agent.run()

Self-improving layer

Turn repeated work into reusable skills and workflows. AgentRun learns from completed runs, checks what it saves, and brings that learning into the next task.

Learning reference
01 / LEARN

Make useful work reusable.

A run can leave more than an answer. AgentRun turns useful lessons into context, methods, and steps the same agent can use again.

  • Keep what is usefulNotes preserve context. Skills capture a method. Workflows make a sequence callable.
  • Check before savingProposals are validated and graded. Risky changes wait for your approval.
  • Opt in per agentChoose which agents learn. Each keeps its own learning across supported harnesses.
How self-improvement works
From completed work to reusable learning
THIS RUNComplete the task
  1. 01ReflectPropose a lesson
  2. 02ValidateCheck the change
  3. 03GradeJudge its value
NotesKeep contextSkillsKeep the methodWorkflowsReuse the steps
NEXT RUNStart with what worked

Learning stays with the agent that produced it.

Enable learning and understand the checksConfiguration, artifact types, and how proposals are accepted.

On a server with a model configured, create an agent with learning: true. This request body selects Pi and sets a $2 model-spend budget per run.

POST /v2/agents · request body
{
  "definition": {
    "id": "invoice-reviewer",
    "name": "Invoice reviewer",
    "instructions": "Extract invoice fields and report inconsistencies.",
    "harness": "pi",
    "tools": ["read"],
    "learning": true,
    "max_cost_usd": 2
  }
}
Agent definitions and learning configurationjson
ArtifactHow later runs use it
NotesActive context and lessons enter the agent’s instructions.
SkillsReusable instructions join the skills available through the harness.
WorkflowsValidated sequences become callable through learned_workflow.

Code validates formats, secrets, limits, and tool permissions; a model grades proposals against the agent’s instructions and existing learning. Learned workflows cannot contain executable code or shell nodes. Validation does not run a task-specific test suite.

Learning changes agent artifacts, not model weights. It applies to agentic definitions; the server’s --learning off switch overrides individual settings. Check GET /v2/capabilities for features.learning.

Read the learning lifecycle
02 / REUSE

Spend tokens on the new problem.

Later runs can reuse a known method instead of rediscovering tools and planning the same steps. New inputs still get their own execution and checks.

  • Skip repeated discoveryAn accepted skill gives the agent a method to start from.
  • Call a learned workflowRun a validated sequence as a tool, with new inputs each time.
  • Measure the whole resultCompare task quality, tokens, time, and the cost of learning itself.
Explore learned workflows
LEARNING BETWEEN RUNSLearn the steps. Reuse the workflow.
The first run finds, plans, fetches, and checks a result. AgentRun checks and saves a reusable workflow. A later run skips repeated exploration. Its orange route and four stations then become a descending line labeled relative cost per run. This illustrates less repeated work, not measured cost savings. FIRST RUN Task FindAPI Readdocs Planrequest Fetch Check Result LATER RUN REUSABLE WORKFLOWFetch → Check Task Fetch Check Result A first route finds and plans the steps. A checked workflow is saved for a later run. Its orange route and four stations move into a relative-cost chart showing less repeated work. The chart is illustrative, not a measured benchmark. FIRST RUN Task Find Plan Fetch Check Result LATER RUN REUSABLE WORKFLOWFetch → Check Task Fetch Check Result
Relative cost per run As learned steps are reused MoreLessEarly runsLater runs
First runReusable workflow
Illustrative · costs vary by run
See a learned skill and measure its impactAn example artifact, the cost metrics, and what to include in a comparison.

This illustrative invoice skill keeps a checking method for future invoices. It does not reuse one invoice’s answer.

Illustrative artifact · skills/review-invoices/SKILL.md
---
name: review-invoices
description: Use when extracting and checking invoice fields.
---
1. Read the invoice and identify its currency and date format.
2. Extract line items, subtotal, tax, and total.
3. Check the arithmetic; report differences without changing the source.
4. Mark missing or ambiguous values for review. Do not invent them.
Skill and workflow formatsmarkdown

The learning endpoint’s impact comparison appears after both cohorts have at least two completed runs: runs before the first note, and runs starting with active notes.

MetricWhat it includes
median_cost_usdThe job’s cost, excluding reflection.
median_duration_sTime to the job’s answer, before reflection.
median_learning_usdReflection plus proposal grading.

Reflection counts toward the run’s budget. Grading is recorded separately under the learning meter in GET /v2/usage. Include both and compare answer quality on comparable tasks; the built-in comparison is observational.

Learning impact and cost accounting
03 / CONTROL

See what changed. Keep control.

Learning has a history you can inspect. Each run keeps its starting snapshot, while newly accepted learning becomes available to later runs.

  • Trace the lessonInspect the proposal, its verdict, and the run it came from.
  • Keep active work stableNew learning leaves the snapshot of an in-progress run unchanged.
  • Change what gets reusedReview pending changes, edit notes, and retire or restore learning.
Review your agent’s learning
New learning, without changing a run in flight
Snapshot A
Run in progressSnapshot A stays pinned
Changes checked & accepted
Snapshot B
Next runStarts with the new learning
YOUR CONTROLS
ReviewRetireRestore

Each run retains the learning snapshot it started with.

Inspect and manage learning through the APISource runs, diffs, snapshots, and edit protections.
InspectAPI route
Current learning and change historyGET /v2/agents/{agent_id}/learning
A run’s seed, proposals, and verdictGET /v2/runs/{run_id}/learning
Proposed or accepted file changesGET /v2/runs/{run_id}/learning/diff

The learning folder has Git history and source-run attribution. Resumes and follow-ups retain the run’s original snapshot. Edit notes, retire an item to stop serving it, or restore retired learning.

Writes use ETags to detect concurrent edits. Approval and restore require the owner’s password session.

Inspect, edit, retire, and restore learning
Set up AgentRunRead the documentation