---
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`. Every
  instance is one of the per-status subclasses — `PendingHookEvent`,
  `ResolvedHookEvent`, or `CancelledHookEvent` — so match on the subclass
  instead of checking `hook.status`.
* `RunBlocked`: Emitted when the run is blocked on deferred hooks.
* `Retry`: Discards everything since the most recent `StreamStart`: the
  in-progress assistant message and any tool results for it. The
  library does not emit this yet; it is for custom loops that retry a model
  call after it already produced events. Such loops should call
  `ToolRunner.discard_all()` to cancel tools scheduled for the discarded
  response.

Agent event union:

* `AgentEvent`: everything an agent run can yield: `Event` plus
  `ToolCallResult`, `HookEvent`, `PartialToolCallResult`, `RunBlocked`,
  and `Retry`.
  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`. Hook events all share
  `kind: "hook"`; validating against `HookEvent` dispatches to the
  per-status subclass from `hook.status`.

## drop\_discarded

A tool scheduled for a response that later gets retried can still produce
output after the `Retry`, for example when the tool runs in a separate durable
step. `drop_discarded` wraps an event stream and drops that leftover output.

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

It drops a `ToolCallResult`, `PartialToolCallResult`, or `HookEvent` whose
tool call belonged to a discarded response. If the retried response reuses a
tool call id, output for that id is kept again.

`Agent.run`, `MessageHydrator`, `RunStateTracker`, `MessageAggregator`, and
the AI SDK UI adapter already filter this way, so only custom consumers of raw
event streams need it.

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