Skip to content

Stop reasons

A run never throws because a model call failed or a tool broke. It ends with a result whose stop reason says why. You need this to know which reasons your code must handle.

  • done: the model answered without calling a tool, or an output tool accepted its answer.
  • max_steps: the run made its step limit of model calls, 20 by default, and the model still wanted to go on.
  • error: a model call failed. The result’s error says what kind of failure it was.
  • aborted: you aborted the run.
  • stopped: a shouldStop hook ended the run, or beforeModelCall returned { stop } before a call. In the second case the call the hook stopped never ran, so a run stopped at its first call has steps of 0. stoppedBy is the reason the hook gave, as in the first.
  • no_progress: the progress policy found the model repeating a failing call.
  • budget: the next call could have taken the run past its dollar budget, so the run ended without making it.
  • awaiting_approval: a gate asked a person to approve a tool call, and the call waits.
  • clarification_requested: a tool asked the user a question.

Check the reason before you read the output

Section titled “Check the reason before you read the output”

Only a done result carries output. TypeScript rejects result.output until you have checked that the stop reason is done, so an unfinished run cannot pass for a finished one.

A text answer cut off at the output limit also ends done. Check whether the last message’s stop reason is length before you show the answer as complete.

Every result also carries usage, cost and steps, summed over the run’s model calls. The result’s messages holds the messages this run added, and its context holds the whole conversation, ready to continue.

Next, see how tools work.

These docs are licensedCC BY 4.0. Thelicence text is in the repository.