Pydantic AI + Ertas

使用 Pydantic AI 建構正式上線等級代理——這是 Pydantic 團隊推出的型別安全 Python 代理框架，透過 OpenAI 相容端點對微調本地模型提供一級支援。

Overview

Pydantic AI 是出自 Pydantic 與 Logfire 團隊的代理框架——這個驗證函式庫已成為 Python 在執行期資料完整性上的事實標準，幾乎被所有現代 Python 網頁框架使用。Pydantic AI 將相同的型別安全嚴謹性延伸到 LLM 代理：每個工具、每個輸入、每個輸出都是型別化的 Pydantic 模型，於執行期驗證，並提供 Python 開發者已仰賴的完整 Pydantic 錯誤回報與 IDE 自動完成。框架於 2026 年 4 月發布 v1 版本，並迅速成為相對於 LangGraph 的崛起替代品——適合那些優先考量型別安全與開發者人體工學、而非基於圖的編排功能的團隊。2026 年 5 月初的 v1.90.x 與 v1.93.x 點版發布，在 `Agent` 上加入了明確的 `tool_choice` 設定、專屬的 `OutputToolCallEvent` 與 `OutputToolResultEvent` 串流事件以提供細粒度的可觀測性，以及 OpenAI Conversations API 狀態支援——這些改進讓正式上線使用更可控制、更可觀測。

框架的設計直接借鑒自 FastAPI：相依性以型別提示宣告、工具是以 `@agent.tool` 裝飾的函式、驗證自動進行。和透過提示工程及事後解析來處理結構化輸出的舊代理框架不同，Pydantic AI 使用底層模型原生的 function-calling 能力，並將驗證失敗以可捕捉、可重試的 Python 例外形式呈現。這帶來顯著更可靠的代理——當出問題時，你會獲得清楚的堆疊追蹤，而不是一個會幻覺欄位並在下游悄悄失敗的模型。

Pydantic AI 與模型無關。框架透過其 provider 抽象支援 OpenAI、Anthropic、Google 與任何 OpenAI 相容端點，這使其自然契合透過 Ollama、vLLM 或 LM Studio 提供服務的自託管本地模型。Pydantic AI 的型別安全與微調本地模型的組合特別具吸引力：框架在邊界強制 schema 合規、微調模型以訓練格式產生高品質輸出，兩者一起提供既可靠又經濟的代理。

How Ertas Integrates

Ertas 訓練的模型透過 Pydantic AI 的 OpenAI provider（設定指向本地端點）與其協同運作。在 Ertas Studio 微調模型並匯出為 GGUF 後，你透過 Ollama、vLLM 或 Ertas Cloud 提供服務，再將 Pydantic AI 的 `OpenAIModel` provider 指向該端點。你程式碼庫中的每個代理——無論它進行單次 LLM 呼叫或協調複雜的多步驟工作流程——都使用你的 Ertas 訓練模型作為底層引擎。

這個整合特別強大，是因為 Pydantic AI 處理結構化輸出的方式。框架的 `result_type` 參數接受任何 Pydantic 模型，代理會將 LLM 的輸出依該 schema 進行驗證，若輸出不符合，則拋出 `ValidationError`。對微調模型而言——Ertas Studio 的訓練流程可包含 schema 合規範例——這變成一個自我增強的迴圈：模型產生符合 schema 的輸出、Pydantic AI 驗證它們、任何失敗（在微調後變得罕見）都以可捕捉的例外呈現，你可以重試或記錄。

對於透過 Ertas Deployment CLI 的行動部署，Pydantic AI 的輕量級執行期是強力契合。框架在 LLM 呼叫本身之上幾乎沒有額外開銷——這在透過 llama.cpp 在裝置端執行代理迴圈時尤為重要。在主機應用程式端的型別安全（無論主機是 Python 後端或呼叫本地推論伺服器的行動 app）使契約明確，並縮小了錯誤通常隱身的整合面。

Getting Started

1
在 Ertas Studio 微調你的領域模型
在包含你的 Pydantic AI 代理將使用的結構化輸出與工具呼叫資料上訓練。Studio 的 JSONL 格式直接對應到 Pydantic AI 的 `messages` 與 `result_type` 模式。
2
部署到 OpenAI 相容端點
匯出為 GGUF 並透過 Ollama、vLLM 或 Ertas Cloud 提供服務。Pydantic AI 的 OpenAI provider 連線到任何暴露標準 chat-completion API 的端點。
3
安裝 Pydantic AI 並設定模型 provider
安裝 pydantic-ai。建立一個 `OpenAIModel`（或 `OpenAIProvider`）實例，指向你的 Ertas 推論端點並使用你的模型名稱。
4
定義型別化工具與結果 schema
將工具宣告為帶型別提示的修飾 Python 函式。將結果 schema 定義為 Pydantic 模型。Pydantic AI 自動處理驗證、schema 失敗時重試，以及清楚的錯誤回報。
5
執行代理並處理驗證
以你的輸入呼叫 `agent.run()` 或 `agent.run_sync()`。Pydantic AI 回傳一個型別化的結果。捕捉 `ValidationError` 以實作結構化重試邏輯，或仰賴框架內建的重試行為。

python

from pydantic import BaseModel
from pydantic_ai import Agent
from pydantic_ai.models.openai import OpenAIModel

# Point Pydantic AI at your Ertas-trained model served via Ollama
model = OpenAIModel(
    "ertas-support-agent-7b",
    base_url="http://localhost:11434/v1",
    api_key="not-needed",
)

class TicketTriage(BaseModel):
    category: str
    priority: int  # 1-5
    suggested_team: str
    requires_human: bool

agent = Agent(
    model,
    result_type=TicketTriage,
    system_prompt="You triage customer-support tickets for a SaaS product.",
)

@agent.tool
async def lookup_customer(ctx, customer_id: str) -> dict:
    """Fetch customer record from the CRM."""
    return await crm.get_customer(customer_id)

# The agent returns a validated TicketTriage object — or raises ValidationError
result = agent.run_sync(
    "Customer 12345 says the dashboard hasn't loaded for 30 minutes."
)
print(result.data.priority, result.data.suggested_team)

在 Pydantic AI 中建構由 Ertas 訓練模型支援的型別安全工單分流代理。代理的輸出會自動依 Pydantic schema 進行驗證。