Web Chat UI 整合與事件串流

在現代的生成式 AI 應用中，最常見的互動介面莫過於像是 ChatGPT 那樣的聊天視窗 (Chat UI)。為了提供良好的使用者體驗，AI 的回覆必須是「打字機效果 (Streaming)」，而不是讓使用者盯著螢幕乾等十幾秒才一次彈出所有文字。

Pydantic AI 深度支援了 UI 事件串流 (UI Event Streams) 的標準，讓你能夠輕鬆地將後端 Agent 串接至各種主流的前端 Web UI 框架。

支援的 UI 整合標準

開發一個包含串流、工具呼叫狀態更新、與歷史紀錄管理的前端聊天介面是非常複雜的。幸好，業界已經有許多成熟的前端 SDK。Pydantic AI 在後端提供了轉接層，讓你無縫介接這些前端工具：

  1. Vercel AI SDK 整合： Vercel AI SDK 是目前 React/Next.js 生態圈中最受歡迎的 AI 介面函式庫。Pydantic AI 提供了原生的轉換器，可以將 Agent run_stream 產生的事件轉換成 Vercel AI SDK 看得懂的格式。
  2. AG-UI 整合： 這是另一套強大的開源 UI 框架。同樣地，Pydantic AI 支援直接將後端生成的事件流推播給 AG-UI。

實作概念與資料流

要建立一個流暢的 Web Chat UI，前後端的互動通常遵循以下資料流架構：

  1. 前端發送請求：使用者在 React 前端的聊天框輸入訊息，前端透過 POST API 將使用者的訊息（以及之前的對話歷史）發送給 Python 後端（如 FastAPI）。
  2. 後端執行 Agent：FastAPI 後端接收到訊息後，呼叫 Pydantic AI 的 agent.run_stream() 非同步方法。這個方法會回傳一個非同步的事件產生器 (Async Generator)。
  3. 串流推播事件：後端將這個事件產生器透過 HTTP Streaming (例如 Server-Sent Events, SSE) 的方式，源源不絕地將 AI 模型每生成的一個 Token（一個單字）往前端推播。
  4. 前端渲染：前端的 SDK（如 Vercel AI）接收到這些串流的 Token 後，自動拼湊並在網頁上渲染出打字機效果。

除了文字生成，當 Agent 決定呼叫 @agent.tool 時，Pydantic AI 也能將「開始執行工具」、「工具執行完畢」的狀態事件串流給前端，讓前端可以顯示類似「正在查詢資料庫...」的載入動畫，大幅提升使用者的等待體驗。

FastAPI 結合 Vercel AI 概念範例

以下是一個簡化的概念範例，展示後端如何使用 FastAPI 與 Pydantic AI 提供串流端點給前端：

from fastapi import FastAPI
from fastapi.responses import StreamingResponse
from pydantic_ai import Agent
# 假設框架內建了 Vercel 的串流轉換器
from pydantic_ai.integrations.vercel import to_vercel_stream 

app = FastAPI()
agent = Agent('openai:gpt-4o-mini')

# 定義一個接收聊天請求的 API 端點
@app.post("/api/chat")
async def chat_endpoint(user_message: str):
    
    # 呼叫 run_stream 取得串流產生器
    # 實務上這裡會需要傳入解析好的 message_history
    stream_result = await agent.run_stream(user_message)
    
    # 透過 Pydantic AI 提供的工具，將原生串流轉換成 Vercel 支援的格式
    vercel_generator = to_vercel_stream(stream_result)
    
    # 使用 FastAPI 的 StreamingResponse 將結果推播給前端
    return StreamingResponse(vercel_generator, media_type="text/event-stream")

有了這些現成的轉接器，Python 開發者可以專注於打磨 Agent 的智商與工具邏輯，而不用為了如何將串流文字顯示到瀏覽器上而煩惱。