Skip to main content

​
Overview

Agent turns a question into a multi-step research loop: it plans its own searches, follows up on what it finds, and keeps going until it has enough to answer, rather than the single grounding search Answer makes. Because that loop can take a while, a run is asynchronous rather than a single request/response. This topic explains the terminology used in Agent and how the feature works.

​
The run lifecycle

A run moves through a small, closed state machine:
create returns at once with the run in pending state. There is no notification when it finishes. Poll get by id, or let the SDKs’ wait / create_and_wait (createAndWait) do the polling for you. Runs typically finish in under a minute for a simple question, but a harder one can take several minutes and up to around an hour. status is the coarse outcome; stop_reason is the fine-grained one, and it appears only once a run reaches a terminal state: budget_reached and timeout are cut-offs, not verdicts on their own: a budget-capped run with schema-valid partial output is completed + budget_reached; one with nothing usable is failed + budget_reached. See Reference for the full table.

​
Output: text or structured

By default, output.text is a cited Markdown report: inline [n] markers point at entries in output.sources, the list of pages the run consulted. Pass output_schema (the same OpenAI-style response_format object answer and chat completions accept) to also get output.structured, a JSON result shaped by your schema. Requesting structured output does not replace the text report; both are present on a completed run. See Structured output.

​
Sources, grounding, and citations

Three related lists carry attribution, at two different levels of the output:
  • output.sources: every page the run consulted, in retrieval order. Each entry has a stable id (starting at 1) and a url. This is the list output.text’s inline [n] markers point into.
  • output.grounding: present only alongside output.structured. One entry per field of the structured result the run could ground, keyed by a dot-notation field path (e.g. "acquisitions.0.acquirer").
  • Each grounding entry’s citations point back into output.sources by source_id, so a field can cite more than one source.
A field the run could not ground is null in output.structured; the model does not invent a value, and the field has no corresponding output.grounding entry.

​
Cancellation is best-effort

cancel requests that a run stop; it is not a guarantee. It cancels a pending run at once, but a running one stops at its next step. If the run is close enough to finishing, it can complete before the cancellation takes effect, so cancel returns whatever the run’s status actually is at that moment rather than forcing it to cancelled. This makes cancel safe to call speculatively: it never errors on a run that already ended, so you can retry it and race it against completion.

​
Next steps

To learn more about Seltz Agent, check out the following topics: