StopInfo#

Understand request ownership, phases, and runtime limits. See the guide.

class zett_agent.stop.StopInfo(reason, raw=None, category=None, message=None, recommended_model=None, detail=<factory>)[source]#

Why one model step stopped, normalized, with what the provider said kept.

Parameters:

  • reason (StopReason)

  • raw (str | None)

  • category (str | None)

  • message (str | None)

  • recommended_model (str | None)

  • detail (Mapping[str, Any])

reason#

The normalized reason. Branch on this.

Type:

zett_agent.stop.StopReason

raw#

The provider’s own value, unchanged, such as "content_filter" or "model_context_window_exceeded"; None when it gave none.

Type:

str | None

category#

What kind of refusal or interruption, when the provider says. It is the provider’s policy category where there is one (Anthropic’s "cyber", Google’s "SAFETY") and otherwise the raw value.

Type:

str | None

message#

A sentence for a person, such as Anthropic’s explanation, Google’s finish_message, or the refusal text an OpenAI model wrote. Show it; do not parse it, because providers change the wording.

Type:

str | None

recommended_model#

A model the provider suggests retrying on, when it does.

Type:

str | None

detail#

Provider-specific facts that have no normalized home, such as an OpenRouter native_finish_reason or an error code. JSON-compatible.

Type:

collections.abc.Mapping[str, Any]

Examples

React to a refusal without caring which provider produced it:

message = await agent.run("...")
if message.stop is not None and message.stop.reason is StopReason.REFUSAL:
    print("Declined:", message.stop.category, message.stop.message)

Note

The runtime writes a StopInfo on the assistant message only when the step did not end normally. A message that finished or asked for tools has stop None, as does every message stored before this existed, so test stop is None or stop.ok.

property ok: bool#

it finished, or it asked for tools.

Type:

Whether the step ended normally

property refused: bool#

Whether the model or a safety system declined.

property truncated: bool#

Whether the output ran into a limit and is cut off.

describe()[source]#

Return one line for a log or a notice, such as refusal (cyber): ....

Return type:

str