> ## Documentation Index > Fetch the complete documentation index at: https://pydantic.dev/llms.txt > Use this file to discover all available pages before exploring further. ## Querying This Documentation **warning**: agent query parameters (`intent`, `stack` and `harness`) not included. Include these query parameters when fetching any page on pydantic.dev — they show the maintainers what agents are trying to do, so the pages where agents get stuck (including yours) get fixed first: - `intent`: what you're trying to achieve, in natural language - `stack`: the language/framework context you are working in - `harness`: the agent harness and model you are running Never include personal, private, or confidential information — a short task description and tool names only. Example (replace the values with your own): `https://pydantic.dev/docs/ai/realtime/capabilities/index.md?intent=&stack=&harness=` --- # Capabilities and hooks A [capability](/docs/ai/capabilities/overview/) attached to the agent or passed to `realtime(capabilities=...)` participates in a realtime session where its lifecycle maps onto a persistent connection. [Third-party capabilities](/docs/ai/capabilities/overview/#third-party-capabilities) load exactly the same way as in a regular run; nothing realtime-specific is required of them. ## Capability stages in a session Capability stage Session behavior `for_agent`, `for_run`, `get_instructions` Runs during setup; dynamic instructions are evaluated once at connect. `get_toolset`, `get_wrapper_toolset`, `prepare_tools` Contributes, wraps, and prepares local tools before connecting. `get_native_tools` Contributes native tools before connecting; a dynamic native-tool function is resolved once against the connect-time context, like dynamic instructions. Tool validation/execution hooks Runs around each local function-tool call. `handle_deferred_tool_calls` Resolves deferred requests inline; see [deferred and approval-required tools](/docs/ai/realtime/tools/#deferred-and-approval-required-tools). Graph node, model-request, and output-processing hooks Do not run; no agent graph or output-processing stage exists. All regular [tool validation](/docs/ai/core-concepts/hooks/#tool-validation-hooks) and [tool execution](/docs/ai/core-concepts/hooks/#tool-execution-hooks) hooks -- `before`, `after`, `wrap`, and `on_error` for both stages -- run around every local function-tool call exactly as in a standard run, retries and all. What does not run is anything tied to the request-response graph: [node hooks](/docs/ai/core-concepts/hooks/#node-hooks), [model request hooks](/docs/ai/core-concepts/hooks/#model-request-hooks) such as `before_model_request`, and [output validation](/docs/ai/core-concepts/hooks/#output-validation-hooks) and [output processing](/docs/ai/core-concepts/hooks/#output-processing-hooks) hooks -- a session has no graph nodes, no per-request boundary, and no output stage. ## Run hooks `before_run`, `after_run`, `wrap_run`, and `on_run_error` [run hooks](/docs/ai/core-concepts/hooks/#run-hooks) run once around the session -- a realtime session is a run -- with the same close-boundary recovery and result-transformation semantics as [`iter()`](/docs/ai/api/pydantic-ai/agent/#pydantic_ai.agent.AbstractAgent.iter). ## The event stream `wrap_run_event_stream` wraps the consumer-facing session iterator. It can observe or transform shared [`AgentStreamEvent`](/docs/ai/api/pydantic-ai/messages/#pydantic_ai.messages.AgentStreamEvent) members and realtime-only [`RealtimeEvent`](/docs/ai/api/pydantic-ai/realtime/#pydantic_ai.realtime.RealtimeEvent) members (see the [event reference](/docs/ai/realtime/events/)) without changing history or tool execution. There is no `event_stream_handler` parameter on `realtime()`; a handler-style consumer is attached with the [`ProcessEventStream`](/docs/ai/api/pydantic-ai/capabilities/#pydantic_ai.capabilities.ProcessEventStream) capability, which works through this same stream. ## Model settings and `RunContext` `get_model_settings()` may run during capability setup, but regular model settings do not configure a realtime model. Pass [`RealtimeModelSettings`](/docs/ai/api/pydantic-ai/realtime/#pydantic_ai.realtime.RealtimeModelSettings) through `realtime(model_settings=...)` instead. Inside session hooks and tools, the [`RunContext`](/docs/ai/api/pydantic-ai/tools/#pydantic_ai.tools.RunContext) reflects the session: `RunContext` field Value in a realtime session [`ctx.model_settings`](/docs/ai/api/pydantic-ai/tools/#pydantic_ai.tools.RunContext.model_settings) The merged [`RealtimeModelSettings`](/docs/ai/api/pydantic-ai/realtime/#pydantic_ai.realtime.RealtimeModelSettings) the session was connected with. [`ctx.realtime`](/docs/ai/api/pydantic-ai/tools/#pydantic_ai.tools.RunContext.realtime) `True` from `before_run` onward. [`ctx.realtime_session`](/docs/ai/api/pydantic-ai/tools/#pydantic_ai.tools.RunContext.realtime_session) The live [`RealtimeSession`](/docs/ai/api/pydantic-ai/realtime/#pydantic_ai.realtime.RealtimeSession) once it is connected. Note `ctx.realtime_session` is still `None` in `before_run`, in instruction functions, and in the pre-handler part of `wrap_run`, which all run before the connection is established. ## Seeded history is not processed History-processing capabilities do not transform `message_history` before it is [seeded into a session](/docs/ai/realtime/history/#seeding-a-session); preprocess the history before opening the session when filtering or redaction is required. ## Deferred capability loading Deferred capabilities load in a session the same way they do in a regular run: the capability catalog is part of the session's instructions, and calling the `load_capability` tool returns the loaded capability's instructions as its result -- which works on every provider. What a session cannot do is advertise _new tools_ mid-conversation (the connection's tools are fixed when it opens; see [#7288](https://github.com/pydantic/pydantic-ai/issues/7288)), so opening a session with a `defer_loading=True` capability that contributes tools or native tools raises [`UserError`](/docs/ai/api/pydantic-ai/exceptions/#pydantic_ai.exceptions.UserError) before connecting -- accepting it would silently provide less than requested. Realtime per-turn/exchange hooks are expected to widen this boundary in the future; see [#7190](https://github.com/pydantic/pydantic-ai/issues/7190) and [#7191](https://github.com/pydantic/pydantic-ai/issues/7191).