Nếu bạn từng triển khai một tính năng LLM và thấy nó trả về JSON bị lỗi trong môi trường sản xuất, thì PydanticAI được tạo ra dành cho bạn. Đây là framework tác tử Python từ nhóm phát triển Pydantic, và nó đặt đầu ra được xác thực, an toàn về kiểu dữ liệu làm trọng tâm của việc phát triển tác tử. Hướng dẫn này giải thích PydanticAI là gì, tại sao an toàn kiểu dữ liệu quan trọng đối với các tác tử, các khái niệm cốt lõi bạn sẽ thực sự sử dụng và cách nó so sánh với các framework Python khác như LangGraph.
PydanticAI là gì
PydanticAI là một 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 một nhóm phát triển Pydantic Validation và Pydantic Logfire, vì vậy nó thừa hưởng một nền tảng xác thực mạnh mẽ và một mục tiêu thiết kế rõ ràng: mang lại “cảm giác như FastAPI” cho việc xây dựng tác tử.
Nói một cách đơn giản, bạn mô tả tác tử của mình nên làm gì, những công cụ nào nó có thể gọi và hình dạng đầu ra của nó phải như thế nào. PydanticAI xử lý các cuộc gọi mô hình, xác thực mọi thứ dựa trên các mô hình Pydantic của bạn và thử lại khi mô hình trả về thứ gì đó không phù hợp.
Dự án đã đạt được bản phát hành v2.0.0 ổn định vào ngày 23 tháng 6 năm 2026, sau một loạt các phiên bản beta. V2 hướng tới thiết kế ưu tiên "harness" nơi các công cụ, hook, hướng dẫn và cài đặt mô hình của một tác tử được kết hợp thành các đơn vị có thể tái sử dụng. Bạn có thể cài đặt nó bằng pip install pydantic-ai hoặc uv add pydantic-ai.
Tại sao an toàn kiểu dữ liệu quan trọng đối với các tác tử
Các LLM là phi xác định. Hỏi cùng một câu hỏi hai lần và bạn có thể nhận được hai dạng câu trả lời khác nhau. Điều đó không sao đối với một hộp trò chuyện, nhưng nó sẽ gây lỗi ngay khi bạn kết nối đầu ra của mô hình vào mã thực tế: một thao tác ghi vào cơ sở dữ liệu, một cuộc gọi API, một phép tính hóa đơn.
Hầu hết các lỗi của tác tử đều xuất phát từ khoảng trống này. Mô hình “hầu hết” trả về JSON hợp lệ, trình phân tích cú pháp của bạn hoạt động trong quá trình kiểm thử, sau đó một phản hồi trong môi trường sản xuất làm mất một trường hoặc gói câu trả lời bằng văn xuôi và pipeline của bạn bị lỗi. Cuối cùng, bạn phải tự viết mã phân tích cú pháp phòng vệ, dọn dẹp regex và các vòng lặp thử lại.
PydanticAI khắc phục khoảng trống này bằng cách biến hợp đồng đầu ra thành một phần của framework. Bạn định nghĩa một mô hình Pydantic, truyền nó làm kiểu đầu ra và framework đảm bảo giá trị bạn nhận được phù hợp với mô hình đó. Nếu mô hình trả về thứ gì đó không hợp lệ, PydanticAI sẽ gửi lỗi xác thực trở lại LLM và yêu cầu nó thử lại. Mã downstream của bạn nhận được các đối tượng đã được định kiểu, chứ không phải các chuỗi 'hy vọng' (chưa được xác thực).
Ý tưởng tương tự này cũng mở rộng đến các đối số công cụ. Khi mô hình gọi một trong các công cụ của bạn, PydanticAI sẽ xác thực các đối số dựa trên các gợi ý kiểu của hàm của bạn trước khi hàm chạy. Các đối số không hợp lệ sẽ không bao giờ chạm tới logic nghiệp vụ của bạn.
Các khái niệm cốt lõi
PydanticAI giữ diện tích bề mặt của nó nhỏ gọn. Năm ý tưởng bao gồm hầu hết những gì bạn sẽ xây dựng.
Tác tử (Agents)
Lớp Agent là điểm vào chính. Bạn tạo một tác tử với một định danh mô hình và các hướng dẫn tùy chọn. Lớp này là generic trên hai tham số kiểu: kiểu phụ thuộc (dependencies type) và kiểu đầu ra (output type), đây là điều mang lại cho trình soạn thảo và công cụ kiểm tra kiểu của bạn khả năng hiển thị thực sự vào tác tử của bạn.
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)
Chuỗi mô hình đó là tất cả những gì bạn thay đổi để chuyển đổi nhà cung cấp, điều này giúp mã của bạn có tính di động cao.
Đầu ra có kiểu dữ liệu (Typed outputs)
Truyền một mô hình Pydantic làm `output_type` và kết quả của tác tử sẽ được xác thực dựa trên nó. Bạn nhận được một đối tượng có kiểu dữ liệu, và IDE của bạn biết mọi trường. Dưới đây là một ví dụ về đầu ra có cấu trúc:
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.')
print(result.output.priority) # an int, validated, not a guess
Nếu mô hình trả về mức độ ưu tiên dưới dạng văn bản hoặc bỏ qua tóm tắt, quá trình xác thực sẽ thất bại và framework sẽ nhắc lại. Bạn không bao giờ tự phân tích phản hồi thô.
Công cụ (Tools)
Các công cụ cho phép mô hình tương tác bên ngoài bản thân nó: truy vấn cơ sở dữ liệu, gọi một API REST, thực hiện một phép tính. Bạn đăng ký một công cụ bằng decorator `@agent.tool`. PydanticAI đọc các gợi ý kiểu và docstring của hàm để xây dựng schema mà mô hình nhìn thấy, sau đó xác thực mọi cuộc gọi dựa trên schema đó.
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."""
# ctx.deps holds your injected dependency
return await lookup_balance(ctx.deps, account_id)
Mô hình quyết định khi nào gọi công cụ. Hàm của bạn chỉ chạy với các đối số đã vượt qua quá trình xác thực.
Phụ thuộc (Dependencies)
Các tác tử thực tế cần ngữ cảnh: kết nối cơ sở dữ liệu, máy khách HTTP, người dùng hiện tại, khóa API. PydanticAI xử lý điều này bằng cách tiêm phụ thuộc. Bạn khai báo `deps_type` trên tác tử, sau đó đọc nó thông qua `RunContext` bên trong các công cụ và hướng dẫn động. Toàn bộ chuỗi vẫn an toàn kiểu dữ liệu, và việc kiểm thử trở nên dễ dàng hơn vì bạn có thể thay thế các phụ thuộc thực bằng các đối tượng giả.
Nhà cung cấp độc lập với mô hình và truyền dữ liệu (Streaming)
PydanticAI hỗ trợ một danh sách dài các nhà cung cấp: OpenAI, Anthropic, Gemini, DeepSeek, Grok, Cohere, Mistral, Perplexity, cùng với các tùy chọn đám mây như Azure AI Foundry và Amazon Bedrock cũng như các mô hình tự lưu trữ. Việc chuyển đổi thường chỉ là một thay đổi một dòng trong chuỗi mô hình.
Nó cũng truyền trực tuyến đầu ra có cấu trúc với xác thực được áp dụng khi dữ liệu đến, vì vậy bạn có thể hiển thị kết quả một phần mà không từ bỏ các đảm bảo kiểu. Và vì nhóm cũng xây dựng Pydantic Logfire, khả năng quan sát được tích hợp sẵn: theo dõi, gỡ lỗi và theo dõi chi phí cho mỗi lần chạy.
PydanticAI so sánh như thế nào với các framework tác tử Python khác
Không có framework nào là “tốt nhất” tuyệt đối. Chúng được tối ưu hóa cho những mục đích khác nhau. Dưới đây là đánh giá trung thực về vị trí của PydanticAI.
| Framework | Điểm mạnh cốt lõi | Tốt nhất khi bạn muốn |
|---|---|---|
| PydanticAI | Đầu ra và đối số công cụ được xác thực, an toàn kiểu dữ liệu | Độ tin cậy trong sản xuất và luồng dữ liệu có kiểu rõ ràng |
| LangGraph | Đồ thị trạng thái và luồng điều khiển rõ ràng | Quy trình làm việc dài hạn, phân nhánh, đa bước |
| Google ADK | Điều phối đa tác tử trong hệ sinh thái của Google | Tích hợp sâu Gemini và Vertex AI |
| OpenAI Agents SDK | Tích hợp chặt chẽ với OpenAI với khả năng chuyển giao | Ngăn xếp ưu tiên OpenAI và thiết lập nhanh chóng |
Điểm nổi bật của PydanticAI là lớp xác thực. Nếu tác tử của bạn cung cấp dữ liệu có kiểu cho các hệ thống khác, đảm bảo rằng đầu ra khớp với mô hình Pydantic sẽ loại bỏ toàn bộ các lỗi thời gian chạy. LangGraph mang lại cho bạn khả năng kiểm soát tốt hơn đối với các máy trạng thái và luồng phức tạp. OpenAI Agents SDK là lựa chọn tự nhiên nếu bạn đã cam kết sử dụng OpenAI và muốn các tính năng như chuyển giao tác tử và hỗ trợ máy chủ MCP.
Bạn cũng có thể kết hợp chúng. PydanticAI hoạt động tốt như lớp đầu ra có kiểu bên trong một hệ thống điều phối lớn hơn.
Khi nào nên sử dụng PydanticAI
Hãy chọn PydanticAI khi:
- Đầu ra của tác tử của bạn đi vào mã, không chỉ là một cửa sổ trò chuyện, và hình dạng phải chính xác.
- Bạn muốn trình kiểm tra kiểu và IDE của mình hiểu tác tử của bạn từ đầu đến cuối.
- Bạn đã sử dụng Pydantic trong codebase của mình, vì vậy các định nghĩa mô hình có cảm giác quen thuộc.
- Bạn cần sự linh hoạt của nhà cung cấp và không muốn viết lại tác tử của mình để chuyển đổi mô hình.
- Khả năng quan sát là quan trọng và tính năng theo dõi tích hợp của Logfire hấp dẫn.
Hãy tìm kiếm các giải pháp khác khi bạn cần điều phối dựa trên đồ thị phức tạp với phân nhánh phức tạp, nơi một framework máy trạng thái mang lại cho bạn quyền kiểm soát trực tiếp hơn.
Kiểm thử và giả lập các API hỗ trợ tác tử của bạn
Một tác tử PydanticAI chỉ đáng tin cậy như các API mà nó phụ thuộc vào. Mỗi lần chạy đều gọi một nhà cung cấp LLM, và hầu hết các tác tử hữu ích cũng gọi các điểm cuối REST của riêng bạn hoặc các công cụ của bên thứ ba. Những cuộc gọi đó là nơi phát sinh hành vi không ổn định, chi phí bất ngờ và sự không khớp về hình dạng. PydanticAI xác thực đầu ra của mô hình, nhưng nó không thể xác thực rằng API công cụ upstream mà bạn đang gọi trả về những gì bạn mong đợi.
Đây là nơi Apidog phát huy tác dụng, và nó là một công việc khác với framework. Apidog là một nền tảng API nơi bạn kiểm thử và giả lập các API cơ bản mà tác tử của bạn giao tiếp.
Một vài trường hợp sử dụng cụ thể:
- Giả lập LLM hoặc một điểm cuối công cụ. Trong quá trình phát triển, hãy hướng một công cụ đến một API giả lập trả về các phản hồi xác định. Bạn sẽ ngừng đốt token trong mỗi lần chạy thử và bạn tránh được giới hạn tốc độ của nhà cung cấp trong khi lặp lại.
- Xác nhận hình dạng phản hồi. Trước khi bạn kết nối một điểm cuối REST vào một hàm
@agent.tool, hãy sử dụng các xác nhận API để xác nhận rằng phản hồi thực tế khớp với cấu trúc mà công cụ của bạn mong đợi. Phát hiện một trường bị thiếu ở lớp API, chứ không phải sâu bên trong quá trình chạy tác tử. - Quản lý khóa theo môi trường. Giữ các khóa nhà cung cấp và URL cơ sở trong các môi trường Apidog riêng biệt để các lần chạy cục bộ, thử nghiệm và CI nhắm đúng mục tiêu mà không cần thay đổi mã.
- Xác minh trực tiếp điểm cuối LLM. Nếu bạn gọi một nhà cung cấp qua HTTP, bạn có thể kiểm thử API ChatGPT bằng Apidog để xác nhận định dạng xác thực, truyền trực tuyến và gọi công cụ trước khi tác tử của bạn phụ thuộc vào chúng.
Apidog không xây dựng hoặc điều phối tác tử, và nó không phải là một giải pháp thay thế cho PydanticAI. Nó là nơi bạn kiểm thử và giả lập bề mặt API mà tác tử của bạn chạy trên đó. Nếu bạn muốn dùng thử, hãy tải xuống Apidog và giả lập một trong các điểm cuối công cụ của bạn trước tiên.
Cá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à bạn cài đặt nó từ PyPI bằng pip install pydantic-ai hoặc uv add pydantic-ai. Bạn vẫn sẽ phải trả phí cho bất kỳ nhà cung cấp LLM nào bạn sử dụng, vì framework gọi các API đó thay mặt bạn. Để giữ chi phí nhà cung cấp thấp trong khi bạn xây dựng, bạn có thể giả lập các phản hồi API trong quá trình kiểm thử thay vì gọi mô hình trực tiếp trong mỗi lần chạy.
PydanticAI hoạt động với những mô hình nào?
Nó độc lập với nhà cung cấp. Tài liệu liệt kê OpenAI, Anthropic, Gemini, DeepSeek, Grok, Cohere, Mistral và Perplexity, cùng với các tùy chọn đám mây như Azure AI Foundry và Amazon Bedrock và các mô hình tự lưu trữ. Bạn chọn một mô hình bằng cách truyền một chuỗi như 'anthropic:claude-sonnet-4-6' hoặc 'openai:gpt-4o' vào hàm tạo Agent, và việc chuyển đổi thường chỉ là một thay đổi một dòng.
PydanticAI khác với LangChain hay LangGraph như thế nào?
PydanticAI tập trung vào an toàn kiểu dữ liệu: đầu ra có cấu trúc được xác thực và đối số công cụ được xác thực được hỗ trợ bởi các mô hình Pydantic. LangGraph tập trung vào các đồ thị trạng thái rõ ràng cho các quy trình làm việc đa bước, phân nhánh. Nếu ưu tiên của bạn là đảm bảo hình dạng đầu ra và luồng dữ liệu có kiểu rõ ràng, PydanticAI rất phù hợp. Nếu bạn cần kiểm soát chi tiết một máy trạng thái phức tạp, một framework đồ thị sẽ cung cấp cho bạn nhiều đòn bẩy trực tiếp hơn.
Tôi có cần biết Pydantic để sử dụng nó không?
Điều đó hữu ích, nhưng những kiến thức cơ bản rất nhanh để nắm bắt. Bạn định nghĩa hình dạng dữ liệu dưới dạng các lớp kế thừa từ BaseModel, và PydanticAI sử dụng chúng cho đầu ra và schema công cụ. Nếu bạn đã sử dụng Python để kiểm thử API hoặc làm việc với FastAPI, mô hình tư duy sẽ cảm thấy quen thuộc.
Kết luận
PydanticAI mang lại một điều thiết thực cho việc phát triển tác tử: đảm bảo rằng đầu ra của mô hình và các cuộc gọi công cụ của bạn khớp với các kiểu bạn đã khai báo. Điều đó loại bỏ một nguồn lỗi sản xuất thực sự và giữ cho luồng dữ liệu của bạn sạch sẽ. Hãy chọn nó khi độ tin cậy và đầu ra có kiểu dữ liệu quan trọng hơn việc điều phối đồ thị phức tạp.
Bất kể bạn chọn framework nào, các API bên dưới tác tử của bạn vẫn cần được kiểm thử. Giả lập các điểm cuối LLM và công cụ của bạn, xác nhận hình dạng phản hồi của chúng và quản lý khóa theo môi trường trong Apidog để tác tử của bạn chạy trên một nền tảng mà bạn đã thực sự xác minh.