> ## Documentation Index
> Fetch the complete documentation index at: https://thethirdpenco-feat-tool-lifecycle-events.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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()`.

```python theme={null}
@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]: ...
```

<ResponseField name="text" type="str">
  Accumulated generated text.
</ResponseField>

<ResponseField name="steps" type="list[StepResult]">
  Step history for the model/tool loop.
</ResponseField>

<ResponseField name="finish_reason" type="str | None">
  Finish reason for the final provider response.
</ResponseField>

<ResponseField name="usage" type="Usage | None">
  Total usage across all steps.
</ResponseField>

<ResponseField name="response" type="dict[str, Any]">
  Raw response metadata from the provider implementation.
</ResponseField>

<ResponseField name="provider_metadata" type="dict[str, Any]">
  Additional provider metadata.
</ResponseField>

<ResponseField name="tool_calls" type="list[ToolCall]">
  Flattened tool calls from all steps.
</ResponseField>

<ResponseField name="tool_results" type="list[ToolResult]">
  Flattened tool results from all steps.
</ResponseField>

## TextStreamResult

Returned by `stream_text()`.

```python theme={null}
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]: ...
```

<ResponseField name="event_stream" type="AsyncIterator[TextStreamEvent]">
  Replayable async iterator yielding typed text, reasoning, tool lifecycle, step lifecycle, and final events.
</ResponseField>

<ResponseField name="text_stream" type="AsyncIterator[str]">
  Replayable text-only projection of `event_stream`.
</ResponseField>

<ResponseField name="text" type="Awaitable[str]">
  Complete accumulated text after stream consumption.
</ResponseField>

<ResponseField name="usage" type="Awaitable[Usage | None]">
  Usage after stream completion.
</ResponseField>

<ResponseField name="finish_reason" type="Awaitable[str | None]">
  Finish reason after stream completion.
</ResponseField>

<ResponseField name="steps" type="Awaitable[list[StepResult]]">
  Step history after stream completion.
</ResponseField>

`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()`.

```python theme={null}
@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
```

<ResponseField name="turn_id" type="str">
  ID of the turn.
</ResponseField>

<ResponseField name="agent_id" type="str">
  ID of the agent that ran the turn.
</ResponseField>

<ResponseField name="text" type="str">
  Final accumulated assistant text.
</ResponseField>

<ResponseField name="finish_reason" type="str | None">
  Final stream finish reason.
</ResponseField>

<ResponseField name="usage" type="Usage | None">
  Usage after turn completion.
</ResponseField>

<ResponseField name="steps" type="list[StepResult]">
  Step history for this turn.
</ResponseField>

<ResponseField name="started_at" type="float">
  Unix timestamp when the turn started.
</ResponseField>

<ResponseField name="ended_at" type="float">
  Unix timestamp when the turn ended.
</ResponseField>

<ResponseField name="output_message" type="Message">
  Final assistant message appended to agent history.
</ResponseField>

## StepResult

One model/tool-loop step.

```python theme={null}
@dataclass
class StepResult:
    text: str
    tool_calls: list[ToolCall]
    tool_results: list[ToolResult]
    finish_reason: str | None = None
    usage: Usage | None = None
```

<ResponseField name="text" type="str">
  Text produced in the step.
</ResponseField>

<ResponseField name="tool_calls" type="list[ToolCall]">
  Tool calls requested by the model in the step.
</ResponseField>

<ResponseField name="tool_results" type="list[ToolResult]">
  Results from executing tool calls in the step.
</ResponseField>

<ResponseField name="finish_reason" type="str | None">
  Provider finish reason for this step.
</ResponseField>

<ResponseField name="usage" type="Usage | None">
  Token usage for this step only.
</ResponseField>

## StreamChunk

Provider stream chunk consumed by `stream_text()`.

```python theme={null}
@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.

```python theme={null}
@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.

```python theme={null}
@dataclass
class StepControl:
    inject_messages: list[Message] = field(default_factory=list)
    stop: bool = False
```

<ResponseField name="inject_messages" type="list[Message]">
  Messages appended to the current model context before the provider call.
</ResponseField>

<ResponseField name="stop" type="bool">
  If true, stops at the step boundary.
</ResponseField>

## 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.

```python theme={null}
@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.

```python theme={null}
@dataclass
class RetryEvent:
    step_number: int
    attempt: int
    max_attempts: int
    delay: float
    error: str
    exception: Exception
```

## StepStartEvent

Passed to `on_step_start`.

```python theme={null}
@dataclass
class StepStartEvent:
    step_number: int
    messages: list[Message]
    tools: ToolSet | None
```

## StepFinishEvent

Passed to `on_step_finish`.

```python theme={null}
@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

```python theme={null}
@dataclass
class ToolCall:
    id: str
    name: str
    arguments: dict[str, Any]
    metadata: dict[str, Any] = field(default_factory=dict)
```

## ToolResult

```python theme={null}
@dataclass
class ToolResult:
    tool_call_id: str
    tool_name: str
    result: Any
    is_error: bool = False
```

## See Also

* [generate\_text](/reference/generate-text)
* [stream\_text](/reference/stream-text)
* [AgentTurn](/reference/agent-turn)
* [Usage](/reference/types/usage)