pydantic_ai.ui.vercel_ai
Vercel AI protocol adapter for Pydantic AI agents.
This module provides classes for integrating Pydantic AI agents with the Vercel AI protocol, enabling streaming event-based communication for interactive AI applications.
Converted to Python from: https://github.com/vercel/ai/blob/ai%405.0.34/packages/ai/src/ui/ui-messages.ts
Bases: UIEventStream[RequestData, BaseChunk, AgentDepsT, OutputDataT]
UI event stream transformer for the Vercel AI protocol.
Vercel AI SDK version to target. Setting to 6 enables tool approval streaming.
Type: Literal[5, 6] Default: 5
Optional server-generated message ID to include in the StartChunk.
Type: str | None Default: None
Bases: UIAdapter[RequestData, UIMessage, BaseChunk, AgentDepsT, OutputDataT]
UI adapter for the Vercel AI protocol.
Vercel AI SDK version to target. Default is 5 for backwards compatibility.
Setting sdk_version=6 enables tool approval streaming for human-in-the-loop workflows.
Type: Literal[5, 6] Default: 5
Optional server-generated message ID to include in the StartChunk.
Type: str | None Default: None
Extract deferred tool results from Vercel AI messages with approval responses.
Type: DeferredToolResults | None
Pydantic AI messages from the Vercel AI run input.
Type: list[ModelMessage]
@classmethod
def build_run_input(cls, body: bytes) -> RequestData
Build a Vercel AI run input object from the request body.
RequestData
@async
@classmethod
def from_request(
cls,
request: Request,
agent: AbstractAgent[AgentDepsT, OutputDataT],
sdk_version: Literal[5, 6] = 5,
server_message_id: str | None = None,
kwargs: Any = {},
) -> VercelAIAdapter[AgentDepsT, OutputDataT]
Extends from_request with the sdk_version and server_message_id parameters.
VercelAIAdapter[AgentDepsT, OutputDataT]
@async
@classmethod
def dispatch_request(
cls,
request: Request,
agent: AbstractAgent[DispatchDepsT, DispatchOutputDataT],
sdk_version: Literal[5, 6] = 5,
server_message_id: str | None = None,
message_history: Sequence[ModelMessage] | None = None,
deferred_tool_results: DeferredToolResults | None = None,
model: Model | KnownModelName | str | None = None,
instructions: _instructions.AgentInstructions[DispatchDepsT] = None,
deps: DispatchDepsT = None,
output_type: OutputSpec[Any] | None = None,
model_settings: ModelSettings | None = None,
usage_limits: UsageLimits | None = None,
usage: RunUsage | None = None,
metadata: AgentMetadata[DispatchDepsT] | None = None,
infer_name: bool = True,
toolsets: Sequence[AbstractToolset[DispatchDepsT]] | None = None,
builtin_tools: Sequence[AbstractBuiltinTool] | None = None,
on_complete: OnCompleteFunc[BaseChunk] | None = None,
kwargs: Any = {},
) -> Response
Extends dispatch_request with the sdk_version and server_message_id parameters.
Response
def build_event_stream(
) -> UIEventStream[RequestData, BaseChunk, AgentDepsT, OutputDataT]
Build a Vercel AI event stream transformer.
UIEventStream[RequestData, BaseChunk, AgentDepsT, OutputDataT]
@classmethod
def load_messages(cls, messages: Sequence[UIMessage]) -> list[ModelMessage]
Transform Vercel AI messages into Pydantic AI messages.
@classmethod
def dump_messages(
cls,
messages: Sequence[ModelMessage],
generate_message_id: Callable[[ModelRequest | ModelResponse, Literal['system', 'user', 'assistant'], int], str] | None = None,
) -> list[UIMessage]
Transform Pydantic AI messages into Vercel AI messages.
list[UIMessage] — A list of UIMessage objects in Vercel AI format
messages : Sequence[ModelMessage]
A sequence of ModelMessage objects to convert
generate_message_id : Callable[[ModelRequest | ModelResponse, Literal[‘system’, ‘user’, ‘assistant’], int], str] | None Default: None
Optional custom function to generate message IDs. If provided,
it receives the message, the role (‘system’, ‘user’, or ‘assistant’), and the
message index (incremented per UIMessage appended), and should return a unique
string ID. If not provided, uses provider_response_id for responses,
run_id-based IDs for messages with run_id, or a deterministic UUID5 fallback.
Vercel AI request types (UI messages).
Converted to Python from: https://github.com/vercel/ai/blob/ai%406.0.57/packages/ai/src/ui/ui-messages.ts
Tool approval types (ToolApprovalRequested, ToolApprovalResponded) require AI SDK v6 or later.
Bases: CamelBaseModel, ABC
Abstract base class for all UI parts.
Bases: BaseUIPart
A text part of a message.
The text content.
Type: str
The state of the text part.
Type: Literal[‘streaming’, ‘done’] | None Default: None
The provider metadata.
Type: ProviderMetadata | None Default: None
Bases: BaseUIPart
A reasoning part of a message.
The reasoning text.
Type: str
The state of the reasoning part.
Type: Literal[‘streaming’, ‘done’] | None Default: None
The provider metadata.
Type: ProviderMetadata | None Default: None
Bases: BaseUIPart
A source part of a message.
Bases: BaseUIPart
A document source part of a message.
Bases: BaseUIPart
A file part of a message.
IANA media type of the file. @see https://www.iana.org/assignments/media-types/media-types.xhtml
Type: str
Optional filename of the file.
Type: str | None Default: None
The URL of the file. It can either be a URL to a hosted file or a Data URL.
Type: str
The provider metadata.
Type: ProviderMetadata | None Default: None
Bases: BaseUIPart
A step boundary part of a message.
Bases: BaseUIPart
Data part with dynamic type based on data name.
Bases: CamelBaseModel
Tool approval in requested state (awaiting user response).
The approval request ID.
Type: str
Bases: CamelBaseModel
Tool approval in responded state (user has approved or denied).
The approval request ID.
Type: str
Whether the user approved the tool call.
Type: bool
Optional reason for the approval or denial.
Type: str | None Default: None
Bases: BaseUIPart
Tool part in input-streaming state.
Bases: BaseUIPart
Tool part in input-available state.
Bases: BaseUIPart
Tool part in output-available state.
Bases: BaseUIPart
Tool part in output-error state.
Bases: BaseUIPart
Tool part in approval-requested state (awaiting user decision).
Bases: BaseUIPart
Tool part in approval-responded state (user approved/denied, execution pending).
Bases: BaseUIPart
Tool part in output-denied state (tool was denied, terminal state).
Bases: BaseUIPart
Dynamic tool part in input-streaming state.
Bases: BaseUIPart
Dynamic tool part in input-available state.
Bases: BaseUIPart
Dynamic tool part in output-available state.
Bases: BaseUIPart
Dynamic tool part in output-error state.
Bases: BaseUIPart
Dynamic tool part in approval-requested state (awaiting user decision).
Bases: BaseUIPart
Dynamic tool part in approval-responded state (user approved/denied, execution pending).
Bases: BaseUIPart
Dynamic tool part in output-denied state (tool was denied, terminal state).
Bases: CamelBaseModel
A message as displayed in the UI by Vercel AI Elements.
A unique identifier for the message.
Type: str
The role of the message.
Type: Literal[‘system’, ‘user’, ‘assistant’]
The metadata of the message.
Type: Any | None Default: None
The parts of the message. Use this for rendering the message in the UI. System messages should be avoided (set the system prompt on the server instead). They can have text parts. User messages can have text parts and file parts. Assistant messages can have text, reasoning, tool invocation, and file parts.
Type: list[UIMessagePart]
Bases: CamelBaseModel
Submit message request.
Bases: CamelBaseModel
Ask the agent to regenerate a message.
Provider metadata.
Default: dict[str, dict[str, JSONValue]]
Union of tool approval states.
Default: ToolApprovalRequested | ToolApprovalResponded
Union of all tool part types.
Default: ToolInputStreamingPart | ToolInputAvailablePart | ToolOutputAvailablePart | ToolOutputErrorPart | ToolApprovalRequestedPart | ToolApprovalRespondedPart | ToolOutputDeniedPart
Union of all dynamic tool part types.
Default: DynamicToolInputStreamingPart | DynamicToolInputAvailablePart | DynamicToolOutputAvailablePart | DynamicToolOutputErrorPart | DynamicToolApprovalRequestedPart | DynamicToolApprovalRespondedPart | DynamicToolOutputDeniedPart
Union of all message part types.
Default: TextUIPart | ReasoningUIPart | ToolUIPart | DynamicToolUIPart | SourceUrlUIPart | SourceDocumentUIPart | FileUIPart | DataUIPart | StepStartUIPart
Union of all request data types.
Default: Annotated[SubmitMessage | RegenerateMessage, Discriminator('trigger')]
Vercel AI response types (SSE chunks).
Converted to Python from: https://github.com/vercel/ai/blob/ai%406.0.57/packages/ai/src/ui-message-stream/ui-message-chunks.ts
Tool approval types (ToolApprovalRequestChunk, ToolOutputDeniedChunk) require AI SDK UI v6 or later.
Bases: CamelBaseModel, ABC
Abstract base class for response SSE events.
Bases: BaseChunk
Text start chunk.
Bases: BaseChunk
Text delta chunk.
Bases: BaseChunk
Text end chunk.
Bases: BaseChunk
Reasoning start chunk.
Bases: BaseChunk
Reasoning delta chunk.
Bases: BaseChunk
Reasoning end chunk.
Bases: BaseChunk
Error chunk.
Bases: BaseChunk
Tool input start chunk.
Bases: BaseChunk
Tool input delta chunk.
Bases: BaseChunk
Tool output available chunk.
Bases: BaseChunk
Tool input available chunk.
Bases: BaseChunk
Tool input error chunk.
Bases: BaseChunk
Tool output error chunk.
Bases: BaseChunk
Tool approval request chunk for human-in-the-loop approval.
Requires AI SDK UI v6 or later.
Bases: BaseChunk
Tool output denied chunk when user denies tool execution.
Requires AI SDK UI v6 or later.
Bases: BaseChunk
Source URL chunk.
Bases: BaseChunk
Source document chunk.
Bases: BaseChunk
File chunk.
Bases: BaseChunk
Data chunk with dynamic type.
Bases: BaseChunk
Start step chunk.
Bases: BaseChunk
Finish step chunk.
Bases: BaseChunk
Start chunk.
Bases: BaseChunk
Finish chunk.
Bases: BaseChunk
Abort chunk.
Bases: BaseChunk
Message metadata chunk.
Bases: BaseChunk
Done chunk.
Provider metadata.
Default: dict[str, dict[str, JSONValue]]
Reason why the model finished generating.
Default: Literal['stop', 'length', 'content-filter', 'tool-calls', 'error', 'other'] | None