DEV Community

Cover image for PydanticAI là gì? Hướng dẫn về khung tác tử Python an toàn kiểu dữ liệu
Sebastian Petrus
Sebastian Petrus

Posted on • Originally published at apidog.com

PydanticAI là gì? Hướng dẫn về khung tác tử Python an toàn kiểu dữ liệu

Nếu bạn từng đưa một tính năng LLM lên production rồi nhận JSON sai schema, PydanticAI là framework đáng xem xét. Đây là framework tác tử Python từ nhóm phát triển Pydantic, tập trung vào đầu ra được xác thực và an toàn kiểu dữ liệu. Bài viết này hướng dẫn cách dùng PydanticAI trong thực tế: định nghĩa output schema, đăng ký tool, inject dependency, kiểm thử API phụ trợ và so sánh nhanh với các framework như LangGraph.

Dùng thử Apidog ngay hôm nay

PydanticAI là gì

PydanticAI là framework tác tử mã nguồn mở, không phụ thuộc nhà cung cấp dành cho Python. Nó được duy trì bởi cùng nhóm phát triển Pydantic Validation và Pydantic Logfire, nên kế thừa cách tiếp cận quen thuộc: định nghĩa schema rõ ràng, xác thực dữ liệu và giảm lỗi runtime.

Pydantic AI

Thay vì tự parse chuỗi trả về từ LLM, bạn mô tả:

  • Tác tử cần làm gì.
  • Tác tử có thể gọi những tool nào.
  • Đầu ra cuối cùng phải có cấu trúc ra sao.

PydanticAI sẽ gọi model, xác thực output bằng Pydantic model của bạn và thử lại khi model trả về dữ liệu không hợp lệ.

Dự án đã đạt bản phát hành v2.0.0 ổn định vào ngày 23 tháng 6 năm 2026, sau nhiều bản beta. V2 hướng tới thiết kế ưu tiên “harness”, trong đó tool, hook, instruction và model settings có thể được đóng gói thành các đơn vị tái sử dụng.

Cài đặt:

pip install pydantic-ai
Enter fullscreen mode Exit fullscreen mode

Hoặc dùng uv:

uv add pydantic-ai
Enter fullscreen mode Exit fullscreen mode

Vì sao an toàn kiểu dữ liệu quan trọng với tác tử LLM

LLM không xác định tuyệt đối. Cùng một prompt có thể trả về nhiều biến thể khác nhau. Điều này vẫn chấp nhận được với chatbot, nhưng dễ gây lỗi khi output được đưa vào:

  • Ghi cơ sở dữ liệu.
  • Gọi API.
  • Tính hóa đơn.
  • Tạo ticket.
  • Điều phối workflow.

Ví dụ lỗi phổ biến:

{
  "category": "billing",
  "priority": "high"
}
Enter fullscreen mode Exit fullscreen mode

Trong khi code downstream lại kỳ vọng:

{
  "category": "billing",
  "priority": 3,
  "summary": "Payment failed three times"
}
Enter fullscreen mode Exit fullscreen mode

Nếu bạn tự parse JSON, bạn thường phải viết thêm:

  • Regex cleanup.
  • Try/catch lặp lại.
  • Fallback parser.
  • Logic kiểm tra field thiếu.
  • Retry prompt thủ công.

PydanticAI đưa hợp đồng dữ liệu vào framework. Bạn định nghĩa schema bằng Pydantic, sau đó nhận về object đã được xác thực thay vì chuỗi “hy vọng đúng”.

Các khái niệm cốt lõi trong PydanticAI

1. Tạo Agent

Agent là điểm vào chính. Bạn khai báo model, instruction và các kiểu dữ liệu liên quan.

from pydantic_ai import Agent

agent = Agent(
    'anthropic:claude-sonnet-4-6',
    instructions='Be concise, reply with one sentence.',
)

result = agent.run_sync('Where does "hello world" come from?')
print(result.output)
Enter fullscreen mode Exit fullscreen mode

Chuỗi model như 'anthropic:claude-sonnet-4-6' hoặc 'openai:gpt-4o' giúp bạn đổi provider bằng một thay đổi nhỏ trong cấu hình.

2. Định nghĩa đầu ra có kiểu dữ liệu

Với output có cấu trúc, hãy truyền Pydantic model vào output_type.

from pydantic import BaseModel
from pydantic_ai import Agent

class SupportTicket(BaseModel):
    category: str
    priority: int
    summary: str

agent = Agent(
    'openai:gpt-4o',
    output_type=SupportTicket,
)

result = agent.run_sync('My payment failed three times today.')

ticket = result.output
print(ticket.category)
print(ticket.priority)
print(ticket.summary)
Enter fullscreen mode Exit fullscreen mode

Lúc này result.output là một object SupportTicket, không phải chuỗi JSON thô.

Nếu model trả về sai kiểu, ví dụ priority là "high" thay vì int, quá trình xác thực sẽ thất bại và PydanticAI có thể yêu cầu model thử lại.

3. Đăng ký tool cho Agent

Tool cho phép tác tử gọi logic bên ngoài, ví dụ truy vấn database, gọi REST API hoặc tính toán.

Bạn đăng ký tool bằng @agent.tool.

from pydantic_ai import Agent, RunContext

agent = Agent('openai:gpt-4o', deps_type=str)

@agent.tool
async def get_user_balance(ctx: RunContext[str], account_id: str) -> float:
    """Return the current balance for an account."""
    return await lookup_balance(ctx.deps, account_id)
Enter fullscreen mode Exit fullscreen mode

PydanticAI đọc type hint và docstring để tạo schema cho tool. Khi LLM gọi tool, đối số được xác thực trước khi hàm thực sự chạy.

Điều này giúp tránh các lỗi như:

account_id = None
Enter fullscreen mode Exit fullscreen mode

Hoặc:

account_id = {"id": "abc"}
Enter fullscreen mode Exit fullscreen mode

Trong khi tool kỳ vọng account_id: str.

4. Inject dependency

Tác tử production thường cần dependency như:

  • Database client.
  • HTTP client.
  • User context.
  • API key.
  • Repository/service object.

PydanticAI xử lý bằng deps_type và RunContext.

Ví dụ:

from dataclasses import dataclass
from pydantic_ai import Agent, RunContext

@dataclass
class AppDeps:
    api_base_url: str
    auth_token: str

agent = Agent(
    'openai:gpt-4o',
    deps_type=AppDeps,
)

@agent.tool
async def get_order_status(ctx: RunContext[AppDeps], order_id: str) -> str:
    """Return the status of an order."""
    return await fetch_order_status(
        base_url=ctx.deps.api_base_url,
        token=ctx.deps.auth_token,
        order_id=order_id,
    )

deps = AppDeps(
    api_base_url='https://api.example.com',
    auth_token='test-token',
)

result = await agent.run('Check order A123', deps=deps)
print(result.output)
Enter fullscreen mode Exit fullscreen mode

Cách này giúp code dễ test hơn vì bạn có thể thay dependency thật bằng fake object hoặc mock server.

5. Streaming và provider độc lập

PydanticAI hỗ trợ nhiều provider như OpenAI, Anthropic, Gemini, DeepSeek, Grok, Cohere, Mistral, Perplexity, Azure AI Foundry, Amazon Bedrock và các mô hình tự lưu trữ.

Việc đổi model thường chỉ là đổi chuỗi model:

agent = Agent('openai:gpt-4o')
Enter fullscreen mode Exit fullscreen mode

Sang:

agent = Agent('anthropic:claude-sonnet-4-6')
Enter fullscreen mode Exit fullscreen mode

Framework cũng hỗ trợ streaming output có cấu trúc với xác thực khi dữ liệu đến. Nếu bạn cần hiển thị kết quả từng phần trong UI nhưng vẫn muốn giữ schema rõ ràng, đây là điểm đáng chú ý.

Ngoài ra, vì nhóm Pydantic cũng xây dựng Pydantic Logfire, khả năng quan sát như trace, debug và theo dõi chi phí theo từng lần chạy được tích hợp trong hệ sinh thái.

So sánh PydanticAI với các framework tác tử Python khác

Không có framework “tốt nhất” cho mọi trường hợp. Khác biệt chính nằm ở mục tiêu thiết kế.

Framework Điểm mạnh cốt lõi Phù hợp khi bạn muốn
PydanticAI Output và đối số tool được xác thực, an toàn kiểu dữ liệu Độ tin cậy production và luồng dữ liệu có schema rõ ràng
LangGraph Đồ thị trạng thái và luồng điều khiển rõ ràng Workflow dài hạn, phân nhánh, nhiều bước
Google ADK Điều phối đa tác tử trong hệ sinh thái Google Tích hợp sâu Gemini và Vertex AI
OpenAI Agents SDK Tích hợp chặt với OpenAI và hỗ trợ chuyển giao Stack ưu tiên OpenAI và thiết lập nhanh

PydanticAI nổi bật ở lớp xác thực. Nếu tác tử của bạn trả dữ liệu cho hệ thống khác, việc đảm bảo output khớp với Pydantic model sẽ loại bỏ nhiều lỗi runtime.

LangGraph phù hợp hơn nếu bạn cần kiểm soát trạng thái phức tạp, nhánh điều kiện và workflow nhiều bước. OpenAI Agents SDK là lựa chọn tự nhiên nếu bạn đã dùng OpenAI làm trung tâm và cần các tính năng như chuyển giao tác tử hoặc hỗ trợ máy chủ MCP.

Bạn cũng có thể kết hợp chúng: dùng framework điều phối lớn hơn cho workflow, và dùng PydanticAI làm lớp tạo output có kiểu dữ liệu.

Khi nào nên dùng PydanticAI

Hãy chọn PydanticAI khi:

  • Output của tác tử được đưa vào code, không chỉ hiển thị trong chat.
  • Bạn cần schema output chính xác.
  • Bạn muốn IDE và type checker hiểu luồng dữ liệu.
  • Codebase đã dùng Pydantic hoặc FastAPI.
  • Bạn muốn đổi provider LLM mà không viết lại toàn bộ tác tử.
  • Bạn cần quan sát, trace và debug agent run.

Không nên chọn PydanticAI làm công cụ chính nếu ưu tiên lớn nhất của bạn là điều phối workflow dạng đồ thị phức tạp với nhiều nhánh trạng thái. Khi đó, framework kiểu state machine hoặc graph framework có thể phù hợp hơn.

Kiểm thử và giả lập API mà tác tử phụ thuộc vào

Một tác tử PydanticAI chỉ đáng tin cậy bằng các API mà nó gọi. Ngoài LLM provider, nhiều tác tử còn gọi:

  • REST API nội bộ.
  • API thanh toán.
  • API CRM.
  • Tool endpoint.
  • Dịch vụ bên thứ ba.

PydanticAI xác thực output của model, nhưng nó không thể đảm bảo API upstream mà tool của bạn gọi luôn trả về đúng schema.

Apidog API testing

Đây là nơi Apidog hữu ích. Apidog không thay thế PydanticAI và không điều phối tác tử. Nó là nền tảng để kiểm thử, giả lập và xác minh các API mà tác tử giao tiếp.

Giả lập LLM hoặc tool endpoint

Trong quá trình phát triển, bạn có thể trỏ tool tới một API giả lập để trả về response xác định.

Ví dụ tool gọi một endpoint giả lập:

import httpx
from pydantic_ai import Agent, RunContext

agent = Agent('openai:gpt-4o', deps_type=str)

@agent.tool
async def get_customer_profile(ctx: RunContext[str], customer_id: str) -> dict:
    """Return customer profile by customer ID."""
    async with httpx.AsyncClient() as client:
        response = await client.get(
            f'{ctx.deps}/customers/{customer_id}'
        )
        response.raise_for_status()
        return response.json()
Enter fullscreen mode Exit fullscreen mode

Khi chạy local, ctx.deps có thể là mock server URL từ Apidog. Khi lên staging hoặc production, bạn đổi sang API thật.

Lợi ích:

  • Không tốn token cho mỗi lần chạy thử.
  • Không bị rate limit provider.
  • Response ổn định để debug logic agent.
  • Dễ tái hiện lỗi.

Xác nhận schema response trước khi nối vào tool

Trước khi một REST endpoint được gọi trong @agent.tool, hãy dùng API assertions để kiểm tra:

  • HTTP status.
  • Field bắt buộc.
  • Kiểu dữ liệu.
  • Cấu trúc nested object.
  • Error response.

Ví dụ nếu tool kỳ vọng:

class CustomerProfile(BaseModel):
    id: str
    email: str
    plan: str
Enter fullscreen mode Exit fullscreen mode

Thì API upstream cũng nên được kiểm thử để đảm bảo luôn trả về:

{
  "id": "cus_123",
  "email": "user@example.com",
  "plan": "pro"
}
Enter fullscreen mode Exit fullscreen mode

Phát hiện lỗi schema ở lớp API sẽ dễ hơn nhiều so với phát hiện sâu trong một lần chạy agent.

Quản lý môi trường chạy

Bạn có thể tách môi trường trong Apidog cho:

  • Local.
  • Test.
  • CI.
  • Staging.
  • Production.

Mỗi môi trường có thể dùng base URL, token và config khác nhau. Điều này giúp agent test chạy đúng endpoint mà không cần sửa code liên tục.

Kiểm thử trực tiếp endpoint LLM

Nếu bạn gọi provider qua HTTP, bạn có thể kiểm thử API ChatGPT bằng Apidog để xác minh:

  • Header xác thực.
  • Request body.
  • Streaming.
  • Tool calling.
  • Error format.

Sau đó mới đưa endpoint vào agent để giảm rủi ro debug nhiều lớp cùng lúc.

Nếu muốn bắt đầu nhanh, hãy tải xuống Apidog và giả lập một endpoint tool đơn giản trước.

Câu hỏi thường gặp

PydanticAI có miễn phí và mã nguồn mở không?

Có. PydanticAI là mã nguồn mở và có thể cài từ PyPI:

pip install pydantic-ai
Enter fullscreen mode Exit fullscreen mode

Hoặc:

uv add pydantic-ai
Enter fullscreen mode Exit fullscreen mode

Bạn vẫn cần trả phí cho provider LLM mà bạn sử dụng. Để giảm chi phí trong giai đoạn phát triển, bạn có thể giả lập API response thay vì gọi model thật trong mọi lần test.

PydanticAI hỗ trợ những model nào?

PydanticAI độc lập với nhà cung cấp. Tài liệu liệt kê các provider như OpenAI, Anthropic, Gemini, DeepSeek, Grok, Cohere, Mistral, Perplexity, Azure AI Foundry, Amazon Bedrock và các mô hình tự lưu trữ.

Bạn chọn model bằng chuỗi truyền vào Agent:

agent = Agent('openai:gpt-4o')
Enter fullscreen mode Exit fullscreen mode

Hoặc:

agent = Agent('anthropic:claude-sonnet-4-6')
Enter fullscreen mode Exit fullscreen mode

PydanticAI khác gì LangChain hoặc LangGraph?

PydanticAI tập trung vào an toàn kiểu dữ liệu: output có cấu trúc được xác thực và đối số tool được kiểm tra bằng schema Pydantic.

LangGraph tập trung vào state graph, workflow nhiều bước và phân nhánh rõ ràng.

Nếu bạn cần output đáng tin cậy cho hệ thống downstream, PydanticAI là lựa chọn tốt. Nếu bạn cần điều phối state machine phức tạp, graph framework sẽ có nhiều quyền kiểm soát hơn.

Tôi có cần biết Pydantic trước không?

Không bắt buộc, nhưng sẽ hữu ích. Kiến thức cơ bản khá đơn giản: bạn định nghĩa schema bằng class kế thừa BaseModel.

from pydantic import BaseModel

class InvoiceSummary(BaseModel):
    invoice_id: str
    total: float
    currency: str
Enter fullscreen mode Exit fullscreen mode

Nếu bạn đã dùng FastAPI hoặc từng làm kiểm thử API bằng Python, mô hình tư duy này sẽ quen thuộc.

Kết luận

PydanticAI giải quyết một vấn đề rất thực tế khi xây dựng tác tử LLM: đảm bảo output và tool call khớp với kiểu dữ liệu bạn đã khai báo. Điều này giúp giảm lỗi production, giảm code parse thủ công và làm cho luồng dữ liệu dễ kiểm thử hơn.

Hãy dùng PydanticAI khi độ tin cậy, schema rõ ràng và type safety quan trọng hơn việc điều phối graph phức tạp.

Dù chọn framework nào, các API bên dưới tác tử vẫn cần được kiểm thử. Hãy giả lập endpoint LLM và tool, xác nhận response schema, quản lý môi trường và kiểm tra các API phụ trợ trong Apidog trước khi đưa agent vào production.

Top comments (0)