Fleet docs v0.2.0-rc.448

Runs

A run is one turn of one agent: everything the agent's process wrote while it ran that turn. Its id is the agent id, a dot and the turn number, for example 6f1c2e0a-5d7b-4c1e-9a43-2b8f0e6d1a77.3. GET /v1/agents/{id}/turns/{n} names it in run.

The server stores each line of a run as it comes in (#591). You can attach to a run by its id at any time: while it runs, after it ended, and after the server restarted. You get the run from its first line, or from an offset, and then each new line until the run is over.

  • Page. /run?id=<run id> shows the run, one row per line, and follows it while it runs. Add &from=<offset> to start later. The row number is the line's offset.
  • CLI. fleet attach <run id> [--from N] prints each line as JSON on stdout and returns when the run is over. If the stream drops (a server restart), it opens it again from the next offset, so no line prints twice.
  • API. GET /v1/runs/{id} gives the run's state (running or done) and next, the offset after its last stored line. GET /v1/runs/{id}/events?from=N is the stream as Server-Sent Events: a line event per line (the event id is its offset), a gap event for offsets the server never had, and an end event when the run is over.

An offset is the line's index in the turn's output as the node counts it. Offsets can skip a number (fleet's own control answers are not stored); a skip is not a gap. A gap is rare: the server stores each batch of lines before it acknowledges it to the node, so a restart loses nothing, but a failed disk write does.

Runs from before #591 have no stored lines: the page and fleet attach show an empty run. Their conversation is still in the transcript.