---
title: ai.events
description: Reference for event classes and event helpers.
type: reference
summary: Reference for ai.events.
---

# ai.events



Streams and agents yield event objects from `ai.events`. This is the public
event-model namespace, and events are Pydantic models.

## Stream Events

Model stream events inherit from `ModelEvent`.

```python
event.message
event.usage
event.provider_metadata
```

Text events:

* `StreamStart`
* `TextStart`
* `TextDelta`
* `TextEnd`
* `StreamEnd`

`StreamEnd` carries the final response metadata. New in 0.4.0:

* `finish_reason`: Why the model stopped: `stop`, `length`, `content_filter`,
  `tool_call`, `error`, or `other`. Raw provider value is kept in `provider_metadata`.
* `response_id`: The provider's id for the response.
* `response_model`: The model that produced the response. It can differ from
  the requested model under gateway routing or fallbacks.

Reasoning events:

* `ReasoningStart`
* `ReasoningDelta`
* `ReasoningEnd`

Tool events:

* `ToolStart`
* `ToolDelta`
* `ToolEnd`
* `BuiltinToolStart`
* `BuiltinToolDelta`
* `BuiltinToolEnd`
* `BuiltinToolResult`

File events:

* `FileEvent`

Stream event union:

* `Event`: union of all model stream events above.

## Agent Events

Agents can emit event values that are not raw provider stream events.

* `ToolCallResult`: Carries the tool result message and result parts.
* `PartialToolCallResult`: Carries values yielded by streaming tools and
  `yield_from`.
* `HookEvent`: Carries an internal hook message and `HookPart`.
* `RunBlocked`: Emitted when the run is blocked on deferred hooks.

Agent event union:

* `AgentEvent`: everything an agent run can yield: `Event` plus
  `ToolCallResult`, `HookEvent`, `PartialToolCallResult`, and `RunBlocked`.
  The union is annotated with a Pydantic discriminator on the `kind` field,
  so use it as a field or `TypeAdapter` type when deserializing events and
  Pydantic picks the right event class from `kind`.

## Aggregator

`Aggregator[Item, Result, ModelInput]` is the interface used by streaming tools
and `yield_from`.

```python
class MyAggregator(ai.events.Aggregator[Item, Result, ModelInput]):
    def feed(self, item: Item) -> None: ...
    def snapshot(self) -> Result: ...

    @classmethod
    def to_model_input(cls, snapshot: Result) -> ModelInput: ...
```

`snapshot()` is the rich value stored in tool results. `get_model_input()` is
the value sent back to the model.


---

For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md)

For an index of all available documentation, see [/llms.txt](/llms.txt)

For agent-facing discovery, including API and MCP surfaces, see [/agents.md](/agents.md)