---
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 `BaseEvent`.

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

Text events:

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

Reasoning events:

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

Tool events:

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

File and hook events:

* `FileEvent`
* `HookSuspension`
* `HookResolution`

Stream event unions:

* `Event`
* `DiscriminatedEvent`

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

Agent event unions:

* `AgentMessageEvent`
* `AgentEvent`
* `TerminalEvent`

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

## replay\_message\_events

`replay_message_events` synthesizes stream events from a complete `Message`.

```python
async for event in ai.events.replay_message_events(message):
    ...
```

Use it when cached, durable, or test messages need to flow through code that
expects stream events.


---

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

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