Runs, agents, and invocations
Understand what a trace represents and how to interpret its timing and outcome.
A run groups the model requests made by one workflow. You create one with
startRun; the returned LedgeTraceHandle controls its lifecycle. The console
displays the run as a trace.
An invocation represents one actual model request. The console also calls an invocation a span. An invocation captures its agent definition, native input/output, timing, model metadata, status, and error.
An agent definition is a stable name and positive implementation version.
For example, summarizer version 1 identifies the instructions, prompt
construction, tools, and response schema used for that model request.
Where recording happens
The Foundation Models adapter records immediately around respond. One request
creates one invocation, including failed and cancelled requests. Parsing a
response, updating UI, fetching a page, or computing an embedding does not create
an invocation. Application processing cannot replace the captured model outcome.
If the model succeeds but your application rejects its result, the model invocation remains successful. Your caller-owned run can still fail because the workflow failed.
Versions
Keep an agent's name stable. Increase its version when the implementation changes in a way you want to distinguish, including its instructions, templates, tools, or output schema. A run's definition version describes the enclosing workflow and is independent of each agent's version.
The SDK records these values; it does not register agents or manage prompt versions for you. Templates remain in your application code.
Timing
A run starts at its first model invocation and ends at its latest observed invocation completion. Preparation and post-processing are excluded. Gaps between calls remain on the timeline, and parallel calls can overlap.
An unfinished invocation has an unknown end time and duration. Recovery marks it interrupted without inventing a completion timestamp. A run with no model calls is not persisted or uploaded.
Inputs and results
| Field | Meaning |
|---|---|
inputData | Application arguments before rendering the prompt. Also available on a run. |
promptTemplate | Caller-supplied unrendered instructions or messages. |
input | Native model history through the current request. |
output | Native entries generated by that request, including tool activity. |
capture | Provider transcript snapshot and boundary metadata. |
outputReferences | Text or JSON that explains identifiers in the response. |
Missing input/output means the provider capture could not be split with enough certainty. The native capture can still be present. Missing, JSON null, and an empty value have different meanings.
Continue with caller-owned runs and input capture.