Pydantic AI: Hướng dẫn Production (Vượt qua Hello World)

Pydantic AI: Hướng dẫn Production (Vượt qua Hello World)

Đầu ra thô từ LLM thường làm hỏng ứng dụng. Bạn yêu cầu JSON, nó trả về markdown. Bạn yêu cầu một số từ 1 đến 10, nó trả về "Chắc chắn rồi! Đây là một con số: bảy." Nếu bạn đã xây dựng bất kỳ thứ gì thực tế với API LLM, bạn hẳn đã viết mã phân tích cú pháp phòng thủ khiến bạn phải nghi ngờ cả lựa chọn nghề nghiệp của mình. Pydantic AI khắc phục điều này; đây là framework agent an toàn về kiểu dữ liệu được xây dựng bởi cùng đội ngũ đứng sau Pydantic và FastAPI. Hãy coi nó như "FastAPI dành cho AI agent": bạn định nghĩa những gì bạn muốn bằng cách sử dụng gợi ý kiểu (type hints) của Python, và framework sẽ xử lý việc xác thực, thử lại và gọi công cụ.

Hướng dẫn Pydantic AI này dành cho các nhà phát triển đã thực hiện cuộc gọi LLM đầu tiên và muốn tìm hiểu các mẫu thiết kế cho production: đầu ra có cấu trúc không bị lỗi, tiêm phụ thuộc để tạo các agent có thể kiểm thử được, và các công cụ thực tế vượt xa khỏi các API thời tiết đơn giản. Đến cuối bài, bạn sẽ có các agent hoạt động với công cụ, DI, streaming và kiểm thử.

Tổng quan về Pydantic AI

Các tính năng nổi bật là đầu ra có cấu trúc (được xác thực bằng mô hình Pydantic), tiêm phụ thuộc (giống như Depends của FastAPI) và TestModel (LLM giả lập để kiểm thử mà không cần gọi API). Nếu bạn đang đến từ LangChain và tự hỏi "có thứ gì sạch sẽ hơn không?", thì đây rất có thể là câu trả lời.

Cài đặt và Agent đầu tiên

# Install with OpenAI support (swap openai for anthropic, google, etc.)
pip install "pydantic-ai[openai]"

# Set your API key
export OPENAI_API_KEY="sk-..."

Agent đầu tiên của bạn chỉ trong 5 dòng:

from pydantic_ai import Agent

agent = Agent("openai:gpt-4o", system_prompt="You are a helpful assistant.")

result = agent.run_sync("What's the capital of France?")
print(result.output)  # "Paris"

Chỉ vậy thôi. Agent bao bọc mô hình, run_sync gửi prompt và trả về kết quả. result.output ở đây là một chuỗi thuần túy, nhưng điều đó sắp thay đổi.

Đầu ra có cấu trúc, Lý do Pydantic AI tồn tại

Đây là tính năng cốt lõi. Thay vì nhận lại một chuỗi từ LLM và hy vọng nó là JSON hợp lệ, bạn định nghĩa một mô hình Pydantic và agent sẽ trả về một đối tượng Python đã được xác thực.

Trước: Đầu ra LLM thô

# The old way -- hope for the best
from openai import OpenAI

client = OpenAI()
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Review the movie Inception. Return JSON with title, rating (1-10), summary."}]
)
# response.choices[0].message.content is a string
# Maybe it's JSON. Maybe it has markdown code fences. Maybe rating is "eight".
# You're on your own.

Sau: Có cấu trúc với Pydantic AI

from pydantic import BaseModel
from pydantic_ai import Agent

class MovieReview(BaseModel):
    title: str
    rating: int  # Guaranteed to be an int, not "eight"
    summary: str
    recommended: bool

agent = Agent("openai:gpt-4o", result_type=MovieReview)

result = agent.run_sync("Review the movie Inception")
review = result.output  # This is a MovieReview instance, not a string

print(f"{review.title}: {review.rating}/10")
print(f"Recommended: {review.recommended}")
print(review.summary)

Sự khác biệt là một trời một vực. result.output là một đối tượng MovieReview thực sự. Nếu LLM trả về rating: "eight" thay vì rating: 8, cơ chế xác thực của Pydantic sẽ bắt lỗi này. Để xem sâu hơn về cách hoạt động này trên các nhà cung cấp khác nhau, hãy xem hướng dẫn của chúng tôi về đầu ra có cấu trúc trên các nhà cung cấp LLM.

Chuyện gì xảy ra khi xác thực thất bại

Đây là phần mà không hướng dẫn nào khác chỉ ra: chuyện gì xảy ra khi LLM mắc lỗi?

from pydantic import BaseModel, Field
from pydantic_ai import Agent

class StrictReview(BaseModel):
    title: str
    rating: int = Field(ge=1, le=10)  # Must be 1-10
    pros: list[str] = Field(min_length=2)  # At least 2 pros

agent = Agent("openai:gpt-4o", result_type=StrictReview)

# If the LLM returns rating=15 or only 1 pro:
# 1. Pydantic validation fails
# 2. The error message is sent BACK to the LLM
# 3. The LLM tries again with the corrected output
# 4. This repeats up to the retry limit
result = agent.run_sync("Review the movie Inception")

Vòng lặp thử-lại-với-phản-hồi này là tính năng đột phá của Pydantic AI. LLM học từ chính các lỗi xác thực của nó. Bạn không cần viết logic thử lại, framework sẽ xử lý nó.

Nhận định: Đầu ra có cấu trúc là lý do tốt nhất duy nhất để sử dụng Pydantic AI thay vì gọi API thô. Nếu bạn đang tự tay phân tích cú pháp JSON từ LLM, hãy dừng lại.

Công cụ và Gọi hàm

Công cụ cho phép agent của bạn gọi các hàm Python để lấy dữ liệu thực tế. Thay vì LLM bịa đặt sự kiện, nó có thể truy vấn cơ sở dữ liệu của bạn, tìm kiếm tài liệu hoặc gọi API.

Đăng ký một Công cụ

from pydantic_ai import Agent

agent = Agent("openai:gpt-4o")

@agent.tool
async def search_docs(query: str) -> str:
    """Search the documentation for relevant articles."""
    # Your actual search logic here
    results = await doc_search_engine.search(query, limit=5)
    return "\n".join(r.title + ": " + r.snippet for r in results)

Decorator @agent.tool đăng ký hàm. Pydantic AI đọc các gợi ý kiểu và docstring của hàm để báo cho LLM biết công cụ làm gì, nhận những đối số nào và trả về cái gì. Không cần viết schema thủ công, các gợi ý kiểu của bạn CHÍNH LÀ schema. Để biết thêm thông tin về cách gọi hàm LLM hoạt động bên dưới hậu trường, chúng tôi có một hướng dẫn riêng.

RunContext: Truyền dữ liệu vào Công cụ

Đây là điểm Pydantic AI khác biệt so với các framework khác. RunContext cho phép bạn truyền dữ liệu thời gian chạy (kết nối cơ sở dữ liệu, thông tin người dùng, client API) vào các công cụ của mình mà không cần trạng thái toàn cục.

from dataclasses import dataclass
from pydantic_ai import Agent, RunContext

@dataclass
class SupportDeps:
    customer_id: str
    db_connection: DatabaseConnection

agent = Agent("openai:gpt-4o", deps_type=SupportDeps)

@agent.tool
async def get_order_history(ctx: RunContext[SupportDeps], limit: int = 5) -> str:
    """Fetch recent orders for the current customer."""
    orders = await ctx.deps.db_connection.query(
        "SELECT * FROM orders WHERE customer_id = $1 ORDER BY date DESC LIMIT $2",
        ctx.deps.customer_id, limit
    )
    return format_orders(orders)

ctx.deps cung cấp cho công cụ quyền truy cập vào bất cứ thứ gì bạn đã truyền tại thời gian chạy. Công cụ không nhập một kết nối cơ sở dữ liệu toàn cục, nó nhận một kết nối. Đây là tiêm phụ thuộc, và đó là điều làm cho các agent của bạn có thể kiểm thử được.

Ví dụ về Công cụ thực tế

@agent.tool
async def run_sql_query(ctx: RunContext[SupportDeps], sql: str) -> str:
    """Run a read-only SQL query against the analytics database.
    Only SELECT queries are allowed."""
    if not sql.strip().upper().startswith("SELECT"):
        return "Error: only SELECT queries are allowed"
    results = await ctx.deps.db_connection.fetch(sql)
    return json.dumps(results, default=str)

Nhận định: Gọi công cụ trong Pydantic AI sạch sẽ hơn bất kỳ framework nào khác nhờ vào việc các gợi ý kiểu đảm nhận phần việc nặng nhọc. Bạn viết các hàm Python bình thường với chú thích kiểu. Framework sẽ lo phần còn lại.

Tiêm phụ thuộc, Tính năng mà LangGraph mong ước có

Nếu bạn đã sử dụng Depends của FastAPI, bạn đã hiểu hệ thống DI của Pydantic AI. Nếu chưa, đây là phiên bản ngắn gọn: thay vì agent của bạn tự đi lấy những gì nó cần (kết nối cơ sở dữ liệu toàn cục, client API, cấu hình), bạn trao cho nó mọi thứ tại thời gian chạy.

Định nghĩa Phụ thuộc

from dataclasses import dataclass
from pydantic_ai import Agent

@dataclass
class AppDeps:
    db: AsyncDatabasePool
    search_client: SearchAPIClient
    current_user: User

agent = Agent(
    "openai:gpt-4o",
    deps_type=AppDeps,
    system_prompt="You are a customer support agent."
)

Sử dụng Phụ thuộc trong Công cụ

@agent.tool
async def lookup_account(ctx: RunContext[AppDeps]) -> str:
    """Look up the current user's account details."""
    account = await ctx.deps.db.fetchrow(
        "SELECT * FROM accounts WHERE user_id = $1",
        ctx.deps.current_user.id
    )
    return json.dumps(account, default=str)

# Run with real dependencies
result = await agent.run(
    "What's my account status?",
    deps=AppDeps(db=real_db, search_client=real_search, current_user=user)
)

Tại sao DI làm cho Agent của bạn có thể kiểm thử

Đây mới là lợi ích thực sự. Trong LangChain, bạn phải truyền ngữ cảnh qua các kwargs của chain hoặc closures, không có mẫu chuẩn nào cả. Trong Pydantic AI, việc thay thế các phụ thuộc thực bằng các đối tượng giả lập cho kiểm thử là cực kỳ đơn giản:

# In your test file
from pydantic_ai import Agent
from your_app import agent, AppDeps

async def test_account_lookup():
    mock_deps = AppDeps(
        db=MockDatabase({"user_123": {"status": "active", "plan": "pro"}}),
        search_client=MockSearch(),
        current_user=User(id="user_123")
    )
    result = await agent.run("What's my account status?", deps=mock_deps)
    assert "active" in result.output
    assert "pro" in result.output

Không cần monkey-patching. Không cần mock các import toàn cục. Bạn chỉ cần truyền các deps khác đi.

Nhận định: Tiêm phụ thuộc là lý do tại sao các nhà phát triển Python giàu kinh nghiệm ưa chuộng Pydantic AI. Đó là ảnh hưởng từ FastAPI thể hiện rõ.

Các nhà cung cấp Mô hình, OpenAI, Anthropic, Gemini, Ollama

Pydantic AI không phụ thuộc vào mô hình. Việc chuyển đổi nhà cung cấp chỉ là thay đổi một dòng:

# OpenAI
agent = Agent("openai:gpt-4o")

# Anthropic
agent = Agent("anthropic:claude-sonnet-4-20250514")

# Google Gemini
agent = Agent("google-gla:gemini-2.0-flash")

# Local Ollama
agent = Agent("ollama:llama3.1")

Mọi thứ khác, công cụ, đầu ra có cấu trúc, DI, đều giữ nguyên. Logic nghiệp vụ của bạn không thay đổi khi bạn chuyển đổi mô hình.

Nhận định: Thiết kế không phụ thuộc mô hình nghĩa là bạn không bao giờ bị khóa chặt vào một nhà cung cấp. Bắt đầu với OpenAI để thuận tiện, đánh giá hiệu năng với Anthropic và sử dụng Ollama cho phát triển cục bộ.

Phản hồi Streaming

Đối với giao diện chat và ứng dụng thời gian thực, streaming là yếu tố thiết yếu. Pydantic AI hỗ trợ tính năng này trong khi vẫn duy trì tính an toàn về kiểu dữ liệu:

from pydantic_ai import Agent
from pydantic import BaseModel

class AnalysisResult(BaseModel):
    summary: str
    sentiment: str
    confidence: float

agent = Agent("openai:gpt-4o", result_type=AnalysisResult)

async def stream_analysis(text: str):
    async with agent.run_stream(f"Analyze this text: {text}") as stream:
        async for partial in stream.stream_structured():
            # partial is a partially-validated AnalysisResult
            print(f"Streaming: {partial}")

        # Final result is fully validated
        result = await stream.get_output()
        print(f"Final: {result.summary} ({result.confidence:.0%} confident)")

Tính năng này hoạt động tuyệt vời với StreamingResponse của FastAPI, cùng một hệ sinh thái, cùng các mẫu thiết kế. Tài liệu về agent Pydantic AI bao gồm các tùy chọn streaming nâng cao bao gồm streaming chỉ văn bản với stream_text().

Pydantic AI so với LangGraph so với OpenAI Agents SDK

Bạn đang ở đây, nên có lẽ bạn đang hỏi: "tôi nên dùng Pydantic AI hay LangGraph?" Câu trả lời trung thực: chúng giải quyết các vấn đề khác nhau và bạn có thể sử dụng cả hai.

Bảng so sánh tính năng

Khi nào nên sử dụng cái nào

Chọn Pydantic AI khi bạn muốn mã agent sạch sẽ và an toàn về kiểu. Nó lý tưởng cho các tác vụ đơn agent với công cụ (bot hỗ trợ khách hàng, trích xuất dữ liệu, agent rà soát mã) và các tình huống mà khả năng kiểm thử là quan trọng. Nếu nhóm của bạn đã sử dụng FastAPI và Pydantic, đường cong học tập gần như bằng phẳng.

Chọn LangGraph khi bạn cần các luồng công việc đa bước phức tạp với phân nhánh có điều kiện, phê duyệt có con người tham gia và quản lý trạng thái tinh vi. LangGraph xuất sắc trong việc điều phối nhiều bước, không phải chất lượng của từng agent riêng lẻ. Để đi sâu, hãy xem so sánh đầy đủ LangGraph vs CrewAI vs OpenAI Agents SDK của chúng tôi.

Chọn OpenAI Agents SDK khi bạn 100% sử dụng OpenAI, muốn thiết lập đơn giản nhất có thể và không cần hỗ trợ đa nhà cung cấp hoặc DI.

Mẫu kết hợp

Đây là những gì các đội ngũ giàu kinh nghiệm thực sự làm: sử dụng Pydantic AI cho các agent riêng lẻ (mã sạch, có thể kiểm thử, đầu ra có kiểu) và LangGraph cho việc điều phối giữa các agent (định tuyến, máy trạng thái, logic có điều kiện). Chúng không cạnh tranh, mà là các lớp bổ sung cho nhau.

# Pydantic AI agent -- clean, testable, type-safe
support_agent = Agent("openai:gpt-4o", result_type=SupportResponse, deps_type=SupportDeps)

# LangGraph graph -- orchestrates when to call which agent
graph = StateGraph(SupportState)
graph.add_node("classify", classify_intent)
graph.add_node("support", lambda state: support_agent.run_sync(state["query"]))
graph.add_node("escalate", escalate_to_human)

Nhận định: Chọn Pydantic AI cho mã agent sạch, có thể kiểm thử. Chọn LangGraph cho các luồng công việc đa bước phức tạp. Chúng không loại trừ lẫn nhau.

Kiểm thử Agent của bạn với TestModel

Đây là phần phân biệt một hướng dẫn cho người mới bắt đầu với một hướng dẫn cho production. Mọi codebase thực tế đều cần kiểm thử, và việc kiểm thử agent notoriously khó khăn, các cuộc gọi LLM chậm, đắt đỏ và không xác định. Pydantic AI cung cấp một giải pháp: TestModel.

from pydantic_ai import Agent
from pydantic_ai.models.test import TestModel
from pydantic import BaseModel

class SupportResponse(BaseModel):
    answer: str
    confidence: float
    escalate: bool

agent = Agent("openai:gpt-4o", result_type=SupportResponse)

# In tests: swap the real model for TestModel
def test_support_agent():
    with agent.override(model=TestModel()):
        result = agent.run_sync("I need help with billing")
        # TestModel returns valid structured data matching your result_type
        assert isinstance(result.output, SupportResponse)
        assert isinstance(result.output.confidence, float)
        assert isinstance(result.output.escalate, bool)

TestModel tạo ra dữ liệu hợp lệ khớp với result_type của bạn mà không thực hiện bất kỳ cuộc gọi API nào. Chi phí bằng không, xác định, nhanh chóng. Tài liệu kiểm thử Pydantic AI bao gồm các mẫu nâng cao như FunctionModel cho các phản hồi tùy chỉnh và capture_run_messages để kiểm tra các cuộc gọi công cụ.

Kiểm thử Công cụ và DI cùng lúc

def test_order_lookup_tool():
    # Mock dependencies
    mock_deps = SupportDeps(
        customer_id="test-123",
        db_connection=MockDB(orders=[{"id": "ord-1", "status": "shipped"}])
    )

    with agent.override(model=TestModel()):
        result = agent.run_sync(
            "Where is my order?",
            deps=mock_deps
        )
        assert isinstance(result.output, SupportResponse)

Không có cuộc gọi API. Không có kiểm thử flaky. Không tốn kém. Chạy cái này trong CI/CD cùng với phần còn lại của bộ kiểm thử của bạn.

Đây là khoảng trống nội dung số 1 trên toàn bộ SERP. Không có hướng dẫn Pydantic AI nào khác đề cập đến kiểm thử. Nếu bạn đang xây dựng agent cho production, đây là những gì bạn cần.

Khả năng quan sát, Tích hợp Logfire trong 5 phút

Các agent production cần khả năng quan sát AI. Bạn muốn thấy mọi cuộc gọi LLM, lệnh gọi công cụ, độ trễ, số lượng token và chi phí. Pydantic AI tích hợp native với Logfire, nền tảng khả năng quan sát của đội ngũ Pydantic (xây dựng trên OpenTelemetry).

import logfire
from pydantic_ai import Agent

logfire.configure()  # Uses LOGFIRE_TOKEN env var
logfire.instrument_pydantic_ai()

agent = Agent("openai:gpt-4o", result_type=MovieReview)
# Every run is now traced automatically
result = agent.run_sync("Review Inception")

Ba dòng lệnh. Bạn nhận được các dấu vết đầy đủ hiển thị: prompt đã gửi, phản hồi mô hình, các cuộc gọi công cụ (nếu có), xác thực thành công/thất bại, thử lại, độ trễ và chi phí ước tính. Nếu Logfire không phù hợp với bạn, Langfuse là một lựa chọn mã nguồn mở vững chắc với hỗ trợ kỹ thuật ngữ cảnh để theo dõi cách các prompt của bạn tiến hóa.

FAQ

Pydantic AI là gì và nó khác LangChain như thế nào?

Pydantic AI là một framework agent an toàn về kiểu dữ liệu nơi các gợi ý kiểu Python dẫn dắt việc xác thực, schema công cụ và tiêm phụ thuộc. LangChain là một framework lớn hơn tập trung vào việc chaining các cuộc gọi LLM lại với nhau. Điểm khác biệt chính: Pydantic AI xác thực đầu ra ở cấp độ framework và cung cấp tiêm phụ thuộc tích hợp sẵn cho khả năng kiểm thử, LangChain mặc định không làm neither.

Làm thế nào để xây dựng một AI agent an toàn về kiểu dữ liệu với Pydantic AI?

Định nghĩa một BaseModel Pydantic cho đầu ra của bạn, truyền nó dưới dạng result_type cho Agent, và gọi run_sync() hoặc run(). Agent trả về một instance đã được xác thực của mô hình của bạn, không phải một chuỗi thô. Xem phần Đầu ra có cấu trúc để biết các ví dụ đầy đủ.

Tôi nên dùng Pydantic AI hay LangGraph cho các agent production?

Sử dụng Pydantic AI cho các agent riêng lẻ nơi tính an toàn kiểu, khả năng kiểm thử và mã sạch là quan trọng. Sử dụng LangGraph để điều phối các luồng công việc đa bước phức tạp với định tuyến có điều kiện. Nhiều đội ngũ sử dụng cả hai, với các agent Pydantic AI nằm bên trong lớp điều phối LangGraph.

Pydantic AI xử lý gọi công cụ và tiêm phụ thuộc như thế nào?

Trang trí một hàm với @agent.tool và Pydantic AI đọc các gợi ý kiểu của nó để tạo schema công cụ. Đối với DI, đặt deps_type trên Agent và chấp nhận RunContext[YourDeps] trong các công cụ. Các phụ thuộc thời gian chạy (kết nối DB, client API) chảy qua mà không cần trạng thái toàn cục.

Làm thế nào để thêm streaming vào một agent Pydantic AI?

Sử dụng agent.run_stream() thay vì agent.run(). Nó trả về một async context manager yield các kết quả từng phần qua stream_structured() hoặc stream_text(). Kết quả cuối cùng vẫn được xác thực đầy đủ dựa trên result_type của bạn.

Pydantic AI đã sẵn sàng cho production vào năm 2026 chưa?

Có. Phiên bản 1.0 đã phát hành vào tháng 9 năm 2025 với cam kết ổn định API. Nó được hậu thuẫn bởi đội ngũ Pydantic (thư viện Python được tải xuống nhiều nhất cho xác thực dữ liệu) và hiện đang ở v1.74.0 với các bản cập nhật thường xuyên.

Tôi có thể sử dụng Pydantic AI với Ollama và các mô hình cục bộ không?

Có. Sử dụng Agent("ollama:llama3.1") và đảm bảo Ollama đang chạy cục bộ. Cài đặt extra provider ollama: pip install "pydantic-ai[ollama]". Đầu ra có cấu trúc và công cụ hoạt động giống hệt như với các nhà cung cấp đám mây.

Làm thế nào để kiểm thử các agent Pydantic AI?

Sử dụng TestModel, một mô hình giả lập tạo ra dữ liệu có cấu trúc hợp lệ khớp với result_type của bạn mà không cần gọi API. Bao bọc kiểm thử của bạn trong agent.override(model=TestModel()) và chạy các assertion trên đầu ra. Xem phần Kiểm thử để biết các ví dụ pytest đầy đủ.

Pydantic AI có hoạt động với FastAPI không?

Hoàn hảo. Chúng chia sẻ cùng triết lý tiêm phụ thuộc và được xây dựng bởi cùng một đội ngũ. Bạn có thể sử dụng các agent Pydantic AI bên trong các endpoint FastAPI, chia sẻ các kiểu phụ thuộc giữa chúng và stream các phản hồi agent qua StreamingResponse.

Sự khác biệt giữa Pydantic AI và OpenAI Agents SDK là gì?

Pydantic AI không phụ thuộc vào mô hình (hoạt động với OpenAI, Anthropic, Gemini, Ollama, v.v.), có tiêm phụ thuộc, TestModel để kiểm thử và xác thực Pydantic. OpenAI Agents SDK đơn giản hơn nhưng bị khóa vào các mô hình OpenAI và thiếu DI cũng như kiểm thử tích hợp. Chọn Pydantic AI cho sự linh hoạt; chọn OpenAI Agents SDK cho thiết lập chỉ dùng OpenAI đơn giản nhất có thể.

Những điểm chính và Bước tiếp theo

Bắt đầu với một agent nhỏ có đầu ra có cấu trúc. Thêm một công cụ. Thêm phụ thuộc. Viết một kiểm thử với TestModel. Đó là con đường dẫn đến production, và bây giờ bạn đã có mọi thứ cần thiết để đi trên con đường đó.

Tài liệu chính thức của Pydantic AI và kho lưu trữ GitHub rất tuyệt vời để đi sâu hơn. Framework phát triển nhanh, vì vậy hãy đánh dấu trang changelog.

Nguồn

• Pydantic AI, Tài liệu chính thức
• Tài liệu Phụ thuộc Pydantic AI
• Tài liệu Kiểm thử Pydantic AI
• Thông báo phát hành Pydantic AI v1
• Khả năng quan sát AI Logfire
• pydantic/pydantic-ai, Kho lưu trữ GitHub