Result Types

API reference for generation, streaming, step, and turn result objects

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)

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

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

text · str

Accumulated generated text.

steps · list[StepResult]

Step history for the model/tool loop.

finish_reason · str | None

Finish reason for the final provider response.

usage · Usage | None

Total usage across all steps.

response · dict[str, Any]

Raw response metadata from the provider implementation.

provider_metadata · dict[str, Any]

Additional provider metadata.

tool_calls · list[ToolCall]

Flattened tool calls from all steps.

tool_results · 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 steps(self) -> list[StepResult]: ...

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

event_stream · AsyncIterator[TextStreamEvent]

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

text_stream · AsyncIterator[str]

Replayable text-only projection of event_stream.

text · Awaitable[str]

Complete accumulated text after stream consumption.

usage · Awaitable[Usage | None]

Usage after stream completion.

finish_reason · Awaitable[str | None]

Finish reason after stream completion.

steps · 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

turn_id · str

ID of the turn.

agent_id · str

ID of the agent that ran the turn.

text · str

Final accumulated assistant text.

finish_reason · str | None

Final stream finish reason.

usage · Usage | None

Usage after turn completion.

steps · list[StepResult]

Step history for this turn.

started_at · float

Unix timestamp when the turn started.

ended_at · float

Unix timestamp when the turn ended.

output_message · Message

Final assistant message appended to agent history.

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

text · str

Text produced in the step.

tool_calls · list[ToolCall]

Tool calls requested by the model in the step.

tool_results · list[ToolResult]

Results from executing tool calls in the step.

finish_reason · str | None

Provider finish reason for this step.

usage · 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

inject_messages · list[Message]

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

stop · bool

If true, stops at the step boundary.

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

See Also

• generate_text
• stream_text
• AgentTurn
• Usage