Starstruk Logo MarkStarstruk

v2.40.0

pydantic/pydantic-aiv2.40.0Sep 5, 2026by DouweM

AI Summary

This release adds robust support for real-time interactions, including barge-in handling, asynchronous background price updates, and new event-driven capabilities. It also introduces several utility methods for managing sessions and models more effectively.

Key Highlights

  • Add `pydantic_ai.prices.update_in_background()` for async price management
  • Handle barge-in in sessions with `handle_barge_in` and audio interrupt mechanisms
  • Add `@agent.on_event` decorator for registering event listeners
  • Add `RealtimeSession.enqueue()` for out-of-band prompts
  • Add `provider_factory` to `infer_realtime_model`

New Features

  • Add `pydantic_ai.prices.update_in_background()`
  • Handle barge-in in the session
  • Add `provider_factory` to `infer_realtime_model`
  • Add `@agent.on_event` for registering event listeners
  • Add `respond=` to `RealtimeSession.send()`
  • Add `RealtimeSession.enqueue()` for out-of-band prompts

Full Release Notes

<!-- Release notes generated using configuration in .github/release.yml at main -->

## What's Changed
### 🚀 Features
* Add `pydantic_ai.prices.update_in_background()` by @adtyavrdhn in https://github.com/pydantic/pydantic-ai/pull/4841
* Handle barge-in in the session: `handle_barge_in=True`, `interrupt(played_bytes=...)`, and `played_audio_bytes` by @DouweM in https://github.com/pydantic/pydantic-ai/pull/7870
* Add `provider_factory` to `infer_realtime_model` by @DouweM in https://github.com/pydantic/pydantic-ai/pull/8106
* Add `@agent.on_event` for registering event listeners on an `Agent` by @DouweM in https://github.com/pydantic/pydantic-ai/pull/8101
* Add `respond=` to `RealtimeSession.send()` and document that a text turn solicits a reply by @DouweM in https://github.com/pydantic/pydantic-ai/pull/8110
* Add `RealtimeSession.enqueue()` for out-of-band prompts from code driving the session by @DouweM in https://github.com/pydantic/pydantic-ai/pull/8109
### 🐛 Bug Fixes
* Map `finish_reason` on OpenAI Responses stream terminal events by [@pydanty](https://github.com/apps/pydanty) in https://github.com/pydantic/pydantic-ai/pull/7916
* Fix `defer_loading` reveal synthesis splitting a parallel batch's `tool_result` from its `tool_use` by [@pydanty](https://github.com/apps/pydanty) in https://github.com/pydantic/pydantic-ai/pull/7879
* fix(realtime): roll back user-turn state when an audio chunk is not bytes-like by @simpleqt in https://github.com/pydantic/pydantic-ai/pull/7905
* Let a capability cache derived state again, and refuse a collection the merge cannot rebuild by @DouweM in https://github.com/pydantic/pydantic-ai/pull/8099
* Make a capability's auto-assigned registry key look like the run-local handle it is by @DouweM in https://github.com/pydantic/pydantic-ai/pull/8119
* Stop sending `reasoning` to the dated `gpt-realtime-2025-08-28` snapshot by @DouweM in https://github.com/pydantic/pydantic-ai/pull/8103
* Subscribe `stream_audio()` and `stream_transcripts()` views when they are called, not on first iteration by @DouweM in https://github.com/pydantic/pydantic-ai/pull/8107
* End the realtime audio and transcript views when a tool fails and nobody is iterating by @DouweM in https://github.com/pydantic/pydantic-ai/pull/8108
* Let a realtime tool hang up with `ctx.realtime_session.close()` instead of wedging itself by @DouweM in https://github.com/pydantic/pydantic-ai/pull/8105
* Fix the realtime "Speaking first" and relay examples, the `interrupt(played_ms=)` cancel race, and two provider tables by @DouweM in https://github.com/pydantic/pydantic-ai/pull/8132

## New Contributors
* @simpleqt made their first contribution in https://github.com/pydantic/pydantic-ai/pull/7905

**Full Changelog**: https://github.com/pydantic/pydantic-ai/compare/v2.39.0...v2.40.0