Result Types

This page documents result types returned by core generation and agent turn APIs.

GenerateTextResult

Returned by generate_text().

@dataclass
class GenerateTextResult:
    text: str
    steps: list[StepResult] = field(default_factory=list)
    finish_reason: str | None = None
    usage: Usage | None = None
    response: dict[str, Any] = field(default_factory=dict)
    provider_metadata: dict[str, Any] = field(default_factory=dict)
    termination: TurnTermination | None = None

    @property
    def tool_calls(self) -> list[ToolCall]: ...

    @property
    def tool_results(self) -> list[ToolResult]: ...

str

Accumulated generated text.

list[StepResult]

Step history for the model/tool loop.

str | None

Finish reason for the final provider response.

Usage | None

Total usage across all steps.

dict[str, Any]

Raw response metadata from the provider implementation.

dict[str, Any]

Additional provider metadata.

TurnTermination | None

Framework-level reason the model/tool loop ended. This is distinct from the provider’s finish_reason.

list[ToolCall]

Flattened tool calls from all steps.

list[ToolResult]

Flattened tool results from all steps.

TextStreamResult

Returned by stream_text().

class TextStreamResult:
    @property
    def event_stream(self) -> AsyncIterator[TextStreamEvent]: ...

    @property
    def text_stream(self) -> AsyncIterator[str]: ...

    @property
    async def text(self) -> str: ...

    @property
    async def usage(self) -> Usage | None: ...

    @property
    async def finish_reason(self) -> str | None: ...

    @property
    async def termination(self) -> TurnTermination | None: ...

    @property
    async def steps(self) -> list[StepResult]: ...

    def __aiter__(self) -> AsyncIterator[str]: ...

AsyncIterator[TextStreamEvent]

Replayable async iterator yielding typed text, reasoning, tool lifecycle, step lifecycle, and final events.

AsyncIterator[str]

Replayable text-only projection of event_stream.

Awaitable[str]

Complete accumulated text after stream consumption.

Awaitable[Usage | None]

Usage after stream completion.

Awaitable[str | None]

Finish reason after stream completion.

Awaitable[TurnTermination | None]

Framework-level termination diagnostic after stream completion.

Awaitable[list[StepResult]]

Step history after stream completion.

event_stream and text_stream share one provider request. They can be consumed in either order or concurrently, and later consumers replay events already received.

TurnResult

Returned by Agent.run(), AgentTurn.result(), and AgentTurn.wait().

@dataclass
class TurnResult:
    turn_id: str
    agent_id: str
    text: str
    finish_reason: str | None
    usage: Usage | None
    steps: list[StepResult]
    started_at: float
    ended_at: float
    output_message: Message
    termination: TurnTermination | None = None

str

ID of the turn.

str

ID of the agent that ran the turn.

str

Final accumulated assistant text.

str | None

Final stream finish reason.

Usage | None

Usage after turn completion.

list[StepResult]

Step history for this turn.

float

Unix timestamp when the turn started.

float

Unix timestamp when the turn ended.

Message

Final assistant message appended to agent history.

TurnTermination | None

Structured terminal diagnostic for the turn.

TurnTermination

finish_reason belongs to the model provider. TurnTermination records why ai-query stopped the surrounding loop.

@dataclass(frozen=True)
class TurnTermination:
    kind: Literal[
        "completed",
        "stop_condition",
        "step_limit",
        "hook_stop",
        "tool_terminated",
        "aborted",
        "failed",
    ]
    provider_finish_reason: str | None = None
    reason: str | None = None
    stop_condition: str | None = None
    tool_name: str | None = None
    final_step_number: int = 0
    has_text: bool = False
    has_tool_calls: bool = False
    last_tool_error: str | None = None
    error_type: str | None = None
    message: str | None = None

Kind	Meaning
`completed`	The provider returned a step without tool calls.
`stop_condition`	A custom condition or `has_tool_call()` matched.
`step_limit`	`step_count_is()` matched, including the default one-step bound.
`hook_stop`	A before-step hook returned `StepControl(stop=True)`.
`tool_terminated`	An after-tool hook returned `AfterToolCallResult(terminate=True)`.
`aborted`	An abort signal stopped the operation.
`failed`	A provider, hook, tool-loop, or runtime exception escaped.

final_step_number is the last attempted model step. It is 0 when the operation stops before the first provider call. Successful operations expose this object on GenerateTextResult, StreamFinishedEvent, TextStreamResult.termination, and TurnResult. AbortError and ordinary exceptions expose a termination attribute when the runtime can attach one. TurnFailed.termination contains the same diagnostic for event consumers.

StepResult

One model/tool-loop step.

@dataclass
class StepResult:
    text: str
    tool_calls: list[ToolCall]
    tool_results: list[ToolResult]
    finish_reason: str | None = None
    usage: Usage | None = None

str

Text produced in the step.

list[ToolCall]

Tool calls requested by the model in the step.

list[ToolResult]

Results from executing tool calls in the step.

str | None

Provider finish reason for this step.

Usage | None

Token usage for this step only.

StreamChunk

Provider stream chunk consumed by stream_text().

@dataclass
class StreamChunk:
    text: str = ""
    is_final: bool = False
    usage: Usage | None = None
    finish_reason: str | None = None
    tool_calls: list[ToolCall] | None = None
    reasoning_events: list[ReasoningEvent] | None = None

ReasoningEvent

Provider reasoning/thinking event.

@dataclass
class ReasoningEvent:
    kind: Literal["summary", "delta", "signature", "state"]
    provider: str
    text: str | None = None
    data: dict[str, Any] = field(default_factory=dict)

StepControl

Returned from on_step_start to control the next step.

@dataclass
class StepControl:
    inject_messages: list[Message] = field(default_factory=list)
    stop: bool = False
    stop_reason: str | None = None

list[Message]

Messages appended to the current model context before the provider call.

bool

If true, stops at the step boundary.

str | None

Optional reason copied into the hook_stop termination diagnostic.

RetryPolicy

Configures provider-call retries for generate_text(), stream_text(), and agents. Default classification retries transient HTTP statuses (408, 409, 425, 429, 500, 502, 503, 504) and network/timeout failures. It does not retry clear client errors such as 400, 401, and 403. Set retry_on to override the classifier.

@dataclass
class RetryPolicy:
    max_attempts: int = 1
    initial_delay: float = 0.5
    max_delay: float = 8.0
    backoff: float = 2.0
    jitter: bool = True
    retry_on: Callable[[Exception], bool] | None = None

RetryEvent

Passed to on_retry before the runtime waits and starts another provider attempt.

@dataclass
class RetryEvent:
    step_number: int
    attempt: int
    max_attempts: int
    delay: float
    error: str
    exception: Exception

StepStartEvent

Passed to on_step_start.

@dataclass
class StepStartEvent:
    step_number: int
    messages: list[Message]
    tools: ToolSet | None

StepFinishEvent

Passed to on_step_finish.

@dataclass
class StepFinishEvent:
    step_number: int
    step: StepResult
    text: str
    usage: Usage | None
    steps: list[StepResult]

usage is the provider-reported usage for this step.

ToolCall

@dataclass
class ToolCall:
    id: str
    name: str
    arguments: dict[str, Any]
    metadata: dict[str, Any] = field(default_factory=dict)

ToolResult

@dataclass
class ToolResult:
    tool_call_id: str
    tool_name: str
    result: Any
    is_error: bool = False

result remains Any for backward compatibility. Tools returning rich text, image, or file content use ToolOutput; scalar and JSON-compatible results keep their existing behavior.

Core Functions

Agent Classes

Transport Layer

Providers

Types

GenerateTextResult

TextStreamResult

TurnResult

TurnTermination

StepResult

StreamChunk

ReasoningEvent

StepControl

RetryPolicy

RetryEvent

StepStartEvent

StepFinishEvent

ToolCall

ToolResult

See Also

​GenerateTextResult

​TextStreamResult

​TurnResult

​TurnTermination

​StepResult

​StreamChunk

​ReasoningEvent

​StepControl

​RetryPolicy

​RetryEvent

​StepStartEvent

​StepFinishEvent

​ToolCall

​ToolResult

​See Also

GenerateTextResult

TextStreamResult

TurnResult

TurnTermination

StepResult

StreamChunk

ReasoningEvent

StepControl

RetryPolicy

RetryEvent

StepStartEvent

StepFinishEvent

ToolCall

ToolResult

See Also