Skip to main content

Observe

Every step of self-improvement starts by reading what an agent did. A long investigation can run for 15 turns and 1,500 messages, more than fits in any model's context window. So Autoheal builds a trace of each run. With a trace, a person or an agent can find the part of the run that matters and read only that.

Every agent gets a trace. There's nothing to turn on.

What a trace holds​

A trace adds three things to the messages Autoheal already saves for each run. Nothing is copied.

PartWhat it isWhen it's ready
TotalsPer turn: model calls, tokens (with the cache split), cost, tool calls, tool errors, human decisions and denialsThe moment the turn finishes
ChaptersPer turn: a one-sentence headline, and up to seven chapters with a goal and a few highlights eachSeconds to a minute after the turn finishes
ReadingThe outline, a range of messages, or the calls to a toolWhenever the run is read
Turn 11 of a run: totals over the whole turn, two chapters each covering a range of messages, and highlights citing message idsTurn 11 of a run: totals over the whole turn, two chapters each covering a range of messages, and highlights citing message ids

Totals​

Totals are counted by code from the saved messages, in the same step that marks the turn finished. They're exact, and they're there even when nothing else is. Turn 11 of an incident run might read:

JSON
{"model_calls": 61, "tool_calls": 140, "tool_errors": 3,
"human_inputs": 1, "denials": 0, "cost_usd": 7.55}

human_inputs counts approvals, denials and answers a person gave to a paused tool call. A subagent keeps its own totals, because it can keep running after its parent's turn ends. The cost of a whole run is the run's turns plus every subagent's turns.

If a model has no price in Autoheal's price list, the cost reads "cost unknown", not $0.

Chapters​

Chapters are an index, written by a small model after the turn ends. They exist so a reader can find the 30 messages that matter without reading 1,500. The same turn 11:

JSON
{"turn_headline": "Found deploy v4.31 at 09:57 and rolled it back after approval.",
"chapters": [
{"messages": "m319-m346",
"goal": "Find out whether the payment errors started with deploy v4.31.",
"highlights": [
{"text": "Error rate went from 0.2% to 6% 40 seconds after v4.31 went out.",
"ids": ["m325.1", "ev-r12"]},
{"text": "The same log query ran twice with the same arguments.",
"ids": ["m329.1", "m331.1"]}]}]}

Every highlight cites message ids. Code checks that each cited id exists in the turn before the chapters are saved. A chapter says why the agent did something only when the agent said so itself: in its to-do list, its reply, or its thinking.

note

A model wrote the chapters, so they can be wrong. Treat them as a map, and check claims against the messages they cite.

Message ids​

Every message and part of a run has a stable id. m325 is the 325th message of the session. m325.1 is its second part, for example a tool call. A subagent's messages carry its label: s1/m12 is message 12 of the run's first subagent, numbered in the order the subagents started. Saved messages never change, so an id always points at the same thing. Eval verdicts, memories and generated skills all cite these ids, so you can open the exact evidence behind them.

Reading a run​

A run is read from the top down, so a reader opens only what matters: the run's outline, then the calls to a tool, then the messages around the ones that matter. Each read is one of three tools, and each answers plain fields, the same ones the run page draws its cards from.

  • The outline lists the run's steps in the order they ran, one entry per attempt: each one's kind, the tool it calls or the model it used, how it ended, how many turns finished, its input and its output or error, and the run_id of the run that attempt opened. It names the run, its agent and how it ended so far, and why when the run failed. Pass an entry's run_id to read that attempt in full: a tool step's input and its output or error; a model step's instructions and its finished turns. A step that was retried lists its newest five attempts, and the oldest one shown says how many came before and their run ids. Each turn has its messages, how it ended, the tools it called, how many failed, its cost and the turn's summary, then what it was asked, its answer (or its error, if it failed), its chapters and its subagents' turns. A run of one step that ran once shows it in full straight away.

    For example, a run of the checkout-triage agent whose triage step failed once lists triage twice, as attempt 1 and attempt 2, each with its own run_id. Reading attempt 1's run_id shows the turns of that attempt only, and the calls and messages read with the same id come from that attempt too.

    JSON
    {"turn": 11, "messages": "m291-m413", "status": "completed", "cost_usd": 7.55,
    "tools": [{"name": "query_logs", "count": 61}, {"name": "rollback_deploy", "count": 1}],
    "failed_calls": 3,
    "summary": "Found deploy v4.31 at 09:57 and rolled it back after approval.",
    "input": "Roll it back if you're sure.",
    "output": "Rolled payments back from v4.31 to v4.30. Errors are back to 0.2%.",
    "chapters": [{"messages": "m319-m346",
    "goal": "Find out whether the payment errors started with deploy v4.31.",
    "highlights": [{"text": "Error rate went from 0.2% to 6% 40 seconds after v4.31 went out",
    "ids": ["m325.1", "ev-r12"]}]}],
    "subagents": [{"turn": 1, "messages": "s1/m1-m40", "status": "completed",
    "summary": "Confirmed error rates returned to 0.2%."}]}

    The outline also lists the model steps' names, which a range of messages takes as its step. To read each model step's calls or messages in turn, a workflow passes each attempt's run_id from the outline's steps. A model step read in full lists the artifacts it saved, each at the version it last wrote.

  • The calls to a tool take a model step's run_id from the outline, or the run's own id when it has one model step. They list each call with its whole arguments, the person's decision if it needed one, its result's status, the start of its result, and the part that holds all of it. For example, a rollback a person approved:

    JSON
    {"id": "m371.1", "turn": 11, "tool": "rollback_deploy",
    "arguments": "{\"service\": \"payments\", \"to_version\": \"v4.30\"}", "decision": "approved",
    "status": "success", "result": "Rolled back payments from v4.31 to v4.30.", "result_id": "m372.0"}
  • A range of messages reads what a turn, a chapter or a call points to, part by part, each saying what it is. It takes a model step's run_id from the outline, or the run's id with the step's name:

    JSON
    [{"id": "m371.0", "kind": "text", "text": "Rolling back to v4.30."},
    {"id": "m371.1", "kind": "tool-call", "tool": "rollback_deploy",
    "text": "{\"service\": \"payments\", \"to_version\": \"v4.30\"}"},
    {"id": "m372.0", "kind": "tool-return", "tool": "rollback_deploy", "call": "m371.1", "status": "success",
    "decision": "approved", "decided_at": "2026-10-09T09:20:00Z", "text": "Rolled back payments from v4.31 to v4.30."}]

A run's subagents are part of the run. Their turns, calls and messages carry their label, s1, s2 and so on.

What a read can and can't do​

A run's messages and tool results can carry prompt injection, so the reads are fixed. Each read:

  • covers one run, up to its last finished turn; messages and tool calls cover one model step of an agent that has several;
  • only reads: api-server checks the run's tenant and project on every call, and agents-py checks every session it reads, subagents included;
  • runs a query Autoheal wrote, with the read's values passed in. No model writes SQL;
  • comes whole, except a range of messages, which answers at most 20,000 characters and names the next read when there's more (next), and the outline, which leaves out what doesn't fit in 50,000 characters and names it in left_out: an attempt's input or output, or each turn's input, output and chapters. A run with very many steps still lists every one of them, so its outline can be longer.

A run can only be read by an agent in the same tenant and project.

Agents that read runs​

Self-improvement will read runs through agents written in agent.yaml, so you can read and change them like any other agent. Each reads the outline, then the chapters and messages it needs, and cites the message ids its answer rests on. For example, asked "Did the agent get the person's agreement before every restart?", an agent answers "no for turn 7 (m73, m164.1), yes for turn 11 (m73, m372.1, m373.0)".

They will be used by:

  • judge rubrics, so that a run longer than a context window can still be scored;
  • Learn, to score the memories a run used and propose new ones.

Reading runs from your own agents​

Three tools let an agent you write in agent.yaml read a past run in its own project: read_agent_run for the outline, read_agent_tool_calls for the calls to a tool, and read_agent_messages for a range of messages. They're read tools, so an agent whose system_tools filter is left out or keeps reads gets them. To remove them, add name not in [...] to the filter. An agent with no filter writes only that:

YAML
system_tools: name not in ["read_agent_run", "read_agent_messages", "read_agent_tool_calls"]

An agent with a filter joins it with &&, like (operation_type == "read" || name == "create_artifact") && name not in [...], so it keeps the write tools it had.

Each tool takes the run's id, so an agent can keep any of them. The same limits apply as above. For example, give an agent a run's id, or a chat follow-up's, and ask how that run ended.

Limits​

  • Older runs have no trace. Turns that finished before traces launched have no totals or chapters. A turn whose chapter writer failed has totals but no chapters.
  • Multi-step agents are read one step at a time. Each LLM step of a multi-step agent runs in its own session, and a trace covers one session.
  • Provider-run tools aren't counted. Tools the model provider runs on its side, like a built-in web search, don't appear in the list of calls or the totals.
  • Evaluate: rubrics that score what the trace shows
  • Learn: memories and skills generated from a run
  • Capabilities: which agents can read traces
  • Heal: opens traces to diagnose why scores dropped