Pydantic AI: agent Python có kiểu dữ liệu, phê duyệt công cụ và chạy bền vững
Đăng ngày 12/10/2026
Mục lục bài nghiên cứu
Tóm lược: Pydantic AI hợp với ai, và khi nào nên chọn thứ khác
Pydantic AI tự định vị là Python AI SDK: một vòng lặp agent có kiểu dữ liệu, mở rộng được, trong đó đổi mô hình chỉ cần đổi một chuỗi. Cùng một agent, tức chương trình để mô hình ngôn ngữ gọi công cụ và trả kết quả, có thể chạy sau giao diện web, trong terminal, trên cuộc gọi thoại, trên hàng đợi nền bền vững, trong GitHub Actions hoặc như một đối tượng Python gọi run(). [1]
Đây là thư viện để lập trình viên nhúng vào ứng dụng, không phải nền tảng có sẵn giao diện quản trị. Điểm nhấn là tính có kiểu từ đầu đến cuối: đầu ra có cấu trúc, phụ thuộc được tiêm có kiểu và công cụ có kiểu, để IDE, bộ kiểm tra kiểu và mô hình cùng hiểu một hợp đồng dữ liệu. [1]
Nên chọn khi đội ngũ viết Python, khi agent phải trả dữ liệu đúng lược đồ để ghi vào hệ thống nghiệp vụ, khi hành động nhạy cảm cần người phê duyệt, hoặc khi run phải sống qua sự cố. Nên chọn thứ khác nếu tổ chức muốn một sản phẩm dùng ngay không cần lập trình, hay chưa có thói quen kiểm thử phần mềm.
Vấn đề gốc: mô hình trả văn bản, hệ thống nghiệp vụ cần dữ liệu có kiểu
Điểm gãy hay gặp khi đưa mô hình ngôn ngữ vào phần mềm doanh nghiệp nằm ở ranh giới dữ liệu: mô hình sinh văn bản tự do, còn cơ sở dữ liệu cần trường có kiểu và ràng buộc. Pydantic AI xử lý ngay trong định nghĩa agent: tham số công cụ được kiểm tra trước khi hàm chạy, và run được bảo đảm trả về đúng output_type đã khai báo. [1]
Vấn đề thứ hai là sự lặp lại: công cụ, chỉ dẫn, hook vòng đời và thiết lập mô hình thường giống nhau giữa nhiều agent. Thư viện gom chúng vào một khái niệm duy nhất là capability để đóng gói và tái sử dụng. [1][3]
Vấn đề thứ ba là độ tin cậy khi chạy lâu: lỗi API, máy chủ khởi động lại, hay phải chờ con người duyệt nhiều giờ. Thư viện tách hai cơ chế cho hai nhu cầu: deferred tools để tạm dừng chờ phê duyệt hoặc kết quả bên ngoài, và durable execution để giữ một run sống qua sự cố. [7][9]
Kiến trúc: đồ thị bốn nút, kiểu tổng quát và capability làm điểm mở rộng
Theo tài liệu kiến trúc đi kèm gói, Agent.run() đi qua UserPromptNode, ModelRequestNode, CallToolsNode rồi lặp lại hoặc kết thúc. Kiểu tổng quát Agent[AgentDepsT, OutputDataT] khóa kiểu phụ thuộc và kiểu đầu ra; RunContext[AgentDepsT] có mặt trong công cụ và system prompt; AbstractCapability là lớp gốc của các gói hành vi tái sử dụng. [3]
Agent dựng được bằng mã Python hoặc khai báo YAML, JSON qua Agent.from_file() và Agent.from_spec(). Capability gom công cụ, hook vòng đời, chỉ dẫn và thiết lập mô hình; bản có sẵn gồm Thinking, Hooks, WebSearch, WebFetch, ImageGeneration, MCP, LocalWorkspace, PrepareTools và một số loại khác. Hook bao mỗi giai đoạn theo mẫu wrap_X, bên trong là before_X, thao tác lõi hoặc on_X_error, rồi after_X. [3]
Mô hình được chỉ định bằng chuỗi nhà_cung_cấp:tên_mô_hình; bảng tiền tố gồm OpenAI, Anthropic, Google, Bedrock, Azure, Groq, Mistral, DeepSeek, OpenRouter, Ollama, vLLM và nhiều bên khác, còn endpoint tương thích OpenAI bất kỳ được nối qua OpenAIProvider với base_url. [3]
Hệ sinh thái tách gói rõ ràng: Pydantic Graph (luồng điều khiển đồ thị có kiểu) và Pydantic Evals (kiểm thử hành vi) là gói riêng; Pydantic AI Harness, cài qua pydantic-ai-harness, cung cấp bộ nhớ, guardrail, sub-agent, lập kế hoạch, quản lý ngữ cảnh, lưu trạng thái và agent lập trình Coder. [1] Mã harness nằm cùng kho, trong thư mục src/pydantic_ai_harness. [5]
Luồng dữ liệu của một run: phụ thuộc đi vào, đầu ra có kiểu đi ra
Đầu vào gồm prompt, lịch sử tin nhắn và đối tượng deps do ứng dụng tạo, như kết nối cơ sở dữ liệu và mã khách hàng trong ví dụ trợ lý ngân hàng của README. Mô hình nhận chỉ dẫn và lược đồ công cụ sinh từ chữ ký hàm, docstring; khi mô hình gọi công cụ, tham số được kiểm tra trước, hàm chạy với RunContext mang deps, và kết quả quay về mô hình ở vòng sau. [1][3]
Đầu ra cuối đi qua một trong bốn chế độ: ToolOutput, mặc định cho mô hình Pydantic, dùng lời gọi công cụ, tương thích mọi nhà cung cấp và hỗ trợ stream; NativeOutput dùng chế độ ép lược đồ của nhà cung cấp, chỉ có ở OpenAI, Anthropic, Google; PromptedOutput dự phòng qua prompt; TextOutput dùng hàm phân tích tùy biến. [3]
Khi công cụ cần phê duyệt hoặc chạy bên ngoài, run kết thúc bằng DeferredToolRequests chứa tên công cụ, tham số đã kiểm tra và ID lời gọi; ứng dụng lưu hội thoại bằng ConversationTypeAdapter, thu phê duyệt rồi chạy tiếp với DeferredToolResults. Nếu bộ xử lý nằm cùng tiến trình, capability HandleDeferredToolCalls giải quyết ngay trong run. [7]
Ở luồng thoại, âm thanh và điều khiển có thể tách: với WebRTC kèm sideband trên OpenAI và Azure OpenAI, âm thanh đi thẳng giữa trình duyệt và nhà cung cấp, còn công cụ, lịch sử và khóa API ở máy chủ. [4] Dữ liệu quan sát đi qua OpenTelemetry tới Logfire hoặc backend OTel bất kỳ. [1]
Tính năng kiểm chứng được trong nguồn tại commit
Công cụ có ba cách đăng ký: @agent.tool khi cần RunContext, @agent.tool_plain cho hàm thuần, Tool(fn) cho công cụ định nghĩa ở module khác; FunctionToolset gom nhóm công cụ, ToolPrepareFunc tạo công cụ động. [3] Capability nạp theo nhu cầu bằng defer_loading=True, như capability tra cứu hoàn tiền trong ví dụ ngân hàng. [1][3]
Một định nghĩa agent chạy trên nhiều giao diện: CLI clai, web chat có sẵn, thoại thời gian thực trên OpenAI Realtime, Gemini Live, Azure, xAI Grok Voice, luồng sự kiện UI theo AG-UI và Vercel AI, ACP cho trình soạn thảo, và GitHub Agentic Workflows. Sinh ảnh và embeddings có trong cùng gói. [1]
Durable execution hỗ trợ tám engine: Temporal, DBOS, Prefect, Restate, AWS Lambda, năm engine được đồng duy trì với đội của nhà cung cấp, cùng Kitaru, Apache Airflow và Absurd; gắn engine thứ hai cho cùng một agent sẽ phát sinh UserError. [9] Với Temporal, mỗi lời gọi mô hình và công cụ trở thành một activity bền vững. [1]
Phê duyệt có người dùng requires_approval=True, ApprovalRequired khi điều kiện phụ thuộc tham số, và CallDeferred cho công cụ chạy ngoài; sự kiện DeferredToolRequestsEvent và DeferredToolResultsEvent báo cho giao diện khi cần người can thiệp. [7] Mô hình 'test' tích hợp sẵn nên có thể bắt đầu mà chưa cần khóa API. [1]
Ai hợp với Pydantic AI, lĩnh vực nào khai thác được
Đối tượng tự nhiên nhất là lập trình viên Python và nhóm backend đã quen Pydantic hoặc FastAPI; README nhắc Pydantic Validation chính là nền mà FastAPI được xây trên đó. [1] Chi phí học chủ yếu nằm ở khái niệm capability và cách tổ chức công cụ, không ở cú pháp mới.
Về lĩnh vực, thư viện hợp với trích xuất dữ liệu có cấu trúc từ hồ sơ, biểu mẫu; trợ lý chăm sóc khách hàng gắn cơ sở dữ liệu; quy trình nhiều ngày có bước phê duyệt; tổng đài thoại. Đây là phân loại theo năng lực, không phải danh sách tổ chức đang dùng. Một kho nghiên cứu cá nhân như phamvanthu.com, nếu muốn chuẩn hóa thẻ ghi chú với nguồn, ngày kiểm tra và mức tin cậy, có thể dùng output_type làm bộ lọc trước khi lưu; đây chỉ là gợi ý thiết kế.
Không hợp với nhóm không lập trình, hoặc tổ chức cần giao diện để người làm nghiệp vụ tự cấu hình agent: thư viện có YAML spec và web chat, nhưng không phải nền tảng quản trị nhiều người dùng.
Kiểm thử trước khi tin: TestModel, FunctionModel và bản ghi tương tác
Tài liệu kiến trúc đưa ra cây quyết định kiểm thử: cần nhanh và tất định thì dùng TestModel với agent.override(); cần điều khiển hành vi gọi công cụ thì dùng FunctionModel; kiểm thử tích hợp với API thật thì dùng cassette ghi sẵn. [3] Nhờ vậy logic công cụ và lược đồ đầu ra được kiểm thử trong CI mà không tốn token.
Ở tầng hành vi, Pydantic Evals là gói riêng để đánh giá agent theo cách pytest kiểm thử mã. [1] Với bài toán trích xuất, bộ đánh giá nên gồm hồ sơ mẫu có đáp án, đo đúng sai theo từng trường, và được chạy lại sau mỗi lần đổi mô hình hay prompt.
Chính sách phiên bản cho biết thuộc tính span OpenTelemetry có thể đổi trong bản minor, dù phiên bản instrumentation cấu hình được. [6] Dashboard và cảnh báo dựa vào tên thuộc tính vì thế cũng cần được kiểm thử lại sau mỗi lần nâng cấp.
Tình huống giả định: phòng đào tạo của một trường đại học tư thục
Giả định một trường đại học tư thục ở Hà Nội với khoảng 12.000 sinh viên. Đầu mỗi học kỳ, phòng đào tạo nhận hàng nghìn đơn xét công nhận tín chỉ của sinh viên chuyển trường, học văn bằng hai hay nộp chứng chỉ ngoại ngữ, kèm bảng điểm PDF; tổng đài tuyển sinh cùng lúc quá tải vì câu hỏi lặp lại. Đây là tình huống đề xuất, chưa triển khai.
Ứng dụng thứ nhất là trích xuất có kiểu: agent đọc bảng điểm, trả về mô hình Pydantic gồm mã học phần, tên, số tín chỉ, điểm và thang điểm, với ràng buộc như số tín chỉ là số nguyên dương; một công cụ tra đề cương nội bộ đề xuất học phần tương đương. [1][3] Công cụ ghi quyết định vào hệ thống quản lý đào tạo đặt requires_approval=True: run dừng, chuyên viên duyệt từng đề xuất, hội thoại được lưu để chạy tiếp khi có người duyệt. [7]
Ứng dụng thứ hai là tổng đài tuyển sinh bằng giọng nói qua relay WebSocket hoặc WebRTC kèm sideband, để khóa API và công cụ ở lại máy chủ của trường. [4] Không nạp lịch sử chứa dữ liệu cá nhân vào cuộc gọi WebRTC vì trình duyệt đọc được các lượt đó; thông tin mật phải nằm trong deps và logic công cụ. [4] Nguồn đã đọc không có dữ liệu về chất lượng nhận dạng tiếng Việt, nên phải thử riêng.
Dữ liệu sinh viên là dữ liệu cá nhân, vì vậy ưu tiên mô hình chạy trong hạ tầng của trường qua Ollama hoặc vLLM, hoặc nhà cung cấp có cam kết xử lý dữ liệu rõ ràng, và gửi trace OpenTelemetry về backend do trường quản lý. [1][3]
Đưa vào vận hành: gói cài đặt, engine bền vững, chính sách phiên bản
Pydantic AI không có máy chủ riêng; ứng dụng chủ, thường là một dịch vụ FastAPI, quyết định cách triển khai, mở rộng và xác thực. Gói chính cài bằng uv add pydantic-ai, các extras như temporal hay openai-realtime thêm khi cần, còn harness là gói riêng. [1]
Nếu cần chạy bền, nên chọn engine tổ chức đã vận hành như Temporal, DBOS hay Prefect. Tài liệu nhấn mạnh durability không phải lưu trữ: engine giữ một run sống qua sự cố, còn lưu hội thoại để quay lại sau là bài toán persistence với lời giải nhẹ hơn. [9]
Chính sách phiên bản: V1 ra tháng 9/2025, V2.0 ổn định ngày 23/6/2026; không cố ý phá tương thích trong bản minor; chức năng deprecated chỉ bị gỡ ở bản major kế tiếp, không sớm hơn ba tháng sau V2.0; V1 nhận bản vá bảo mật ít nhất sáu tháng sau khi V2 ổn định; tính năng trong module beta có thể đổi không tương thích. [6]
Instrumentation là OpenTelemetry thuần nên dùng được với mọi backend OTel; Logfire là lựa chọn của chính công ty phát triển. [1] Đề xuất vận hành: ghim phiên bản, chạy bộ kiểm thử TestModel trong CI cho mọi thay đổi, và cập nhật theo lịch.
Bảo mật: phê duyệt của con người không thay thế phân quyền
Tài liệu deferred tools cảnh báo: khi agent phục vụ qua UI adapter, quyết định phê duyệt do client gửi kèm yêu cầu và adapter không có bản ghi phía máy chủ về lời gọi nào do nó phát ra, nên client chạm được endpoint có thể tự phê duyệt lời gọi của chính nó. Phê duyệt chỉ ngăn mô hình hành động khi thiếu chữ ký con người, không thay thế xác thực endpoint và kiểm tra quyền trong hàm công cụ. [7]
Với thoại, khóa nhà cung cấp, công cụ và logic nghiệp vụ phải ở máy chủ; trình duyệt là một bên trong phiên và có thể gửi sự kiện điều khiển gốc, nên mọi công cụ phải phân quyền dựa trên deps đáng tin, không dựa trên chỉ dẫn của phiên. Đóng sideband chỉ tách máy chủ ra; cuộc gọi vẫn chạy và bị tính phí tới khi trình duyệt cúp máy, trừ khi máy chủ gọi hang_up(). [4]
LocalWorkspace chạy tiến trình con và thao tác tệp ngay trên máy chủ, không cô lập; tùy chọn read_only=True từ chối lệnh và thay đổi. [3] Monty, trình thông dịch Python sandbox cho mã do mô hình viết, thuộc một dự án riêng. [1]
Nội dung prompt, kết quả công cụ và trace đi tới nhà cung cấp mô hình và backend quan sát mà ứng dụng cấu hình; nếu dùng Pydantic AI Gateway, request đi qua hạ tầng của Pydantic theo vùng US hoặc EU. [8] Với dữ liệu sinh viên, cần quyết định bằng văn bản backend nào được nhận nội dung prompt và giữ trong bao lâu.
Giấy phép MIT, các gói con và lớp dịch vụ thương mại bao quanh
LICENSE gốc là MIT, bản quyền Pydantic Services Inc. từ năm 2024; gói harness trong src/pydantic_ai_harness có LICENSE MIT riêng, bản quyền Pydantic Services Inc. năm 2026. [2][5] Kho còn tệp LICENSE trong các gói con như pydantic_ai_slim, pydantic_graph, pydantic_evals, clai và examples; bài chỉ đọc hai tệp trên, nên trước khi phân phối lại cần kiểm tra từng gói.
Quanh phần mã mở là sản phẩm thương mại: Pydantic Logfire, nền tảng quan sát của cùng công ty, và Pydantic AI Gateway, dịch vụ một khóa cho nhiều nhà cung cấp, quản lý qua Logfire, có giới hạn chi tiêu, cho tự mang khóa hoặc trả phí suy luận qua nền tảng, kế thừa SSO và vai trò tùy chỉnh từ Logfire. [1][8] README nói Gateway tự host được, nhưng gateway.md tại commit chỉ mô tả luồng đăng ký dùng dịch vụ. [1][8]
MIT áp dụng cho mã ở commit này, không bao trùm Logfire, Gateway, mô hình được gọi, Monty, genai-prices hay phụ thuộc bên thứ ba. Commit thuộc dòng V2 với cam kết tương thích đã nêu ở phần vận hành. [6] Tên mô hình trong mã ví dụ của README chỉ mang tính minh họa, cần thay bằng mô hình tổ chức có quyền dùng.
Chi phí: thư viện miễn phí, chi phí nằm ở mô hình, engine và con người
Nguồn lực chính gồm kỹ sư Python viết lược đồ, công cụ và bài kiểm thử; chuyên viên phòng đào tạo gán nhãn dữ liệu đánh giá và duyệt đề xuất; hạ tầng ứng dụng sẵn có của trường; mô hình theo token hoặc GPU tự host; và engine durable nếu dùng, mỗi engine có chi phí vận hành riêng. Bài không nêu giá cụ thể.
Để theo dõi chi phí, README nhắc dự án genai-prices giữ dữ liệu giá mô hình và cho biết Logfire có gói miễn phí. [1] Gateway đặt được giới hạn chi tiêu theo dự án, người dùng và khóa API theo ngày, tuần, tháng, và mặc định từ chối request tới mô hình chưa có dữ liệu giá. [8]
Về thiết kế, tài liệu kiến trúc khuyến nghị cân nhắc trì hoãn mọi capability thay vì nhồi chỉ dẫn và lược đồ ít dùng vào prompt, giúp tiết kiệm ngữ cảnh mỗi lượt. [3] Với thoại, cuộc gọi không được cúp đúng cách vẫn bị tính phí, nên kịch bản kiểm thử phải có trường hợp người gọi bỏ ngang. [4]
Các hướng thay thế ở cấp độ cách tiếp cận
SDK agent của chính nhà cung cấp mô hình, như OpenAI Agents SDK, Claude Agent SDK hay Google ADK, gắn với hệ sinh thái của họ; Pydantic AI chọn đa nhà cung cấp với chuỗi tên mô hình hoán đổi được. [1][3] README dẫn tới trang so sánh với LangChain, Google ADK, Claude Agent SDK và bảy khung khác; bài không đọc các trang đó nên không thuật lại kết luận. [1]
Khung đồ thị như LangGraph, hay nền tảng ứng dụng tự host như DeerFlow và Dify, mạnh khi cần giao diện và quy trình dựng sẵn; Pydantic AI nhẹ hơn, sống trong codebase, và khi cần đồ thị có kiểu thì đã có Pydantic Graph. [1]
Tự viết bằng SDK HTTP của nhà cung cấp cộng Pydantic khả thi cho một tác vụ trích xuất đơn lẻ; khi xuất hiện nhiều công cụ, phê duyệt, chạy bền và nhiều giao diện, thư viện giảm phần mã lặp mà nhóm phải tự bảo trì.
Giới hạn và trường hợp không nên dùng
Là thư viện, Pydantic AI không kèm giao diện quản trị, hệ thống tài khoản hay kho hội thoại mặc định cho nhiều người dùng; ứng dụng chủ phải tự xây, kể cả phần lưu hội thoại vốn tách khỏi durable execution. [9]
Tốc độ thay đổi cao: tính năng beta có thể đổi không tương thích, thuộc tính span OpenTelemetry có thể đổi trong bản minor. [6] Các dịch vụ tiện lợi nhất xung quanh như Gateway và Logfire là sản phẩm thương mại vận hành ở vùng US và EU. [8]
NativeOutput chỉ có ở một số nhà cung cấp, và mô hình nhỏ chạy cục bộ có thể khó tuân thủ lược đồ phức tạp. [3] Không nên dùng khi không có lập trình viên, khi quyết định tự động trên dữ liệu nhạy cảm diễn ra mà không có người duyệt, hoặc khi nhu cầu chỉ là chatbot hỏi đáp mà sản phẩm có sẵn đã đáp ứng.
Thử nghiệm mười hai tuần với ngưỡng dừng rõ ràng
Tuần 1–3, dựng nền: viết lược đồ Pydantic cho bảng điểm và cho quyết định công nhận tín chỉ; lấy 300 hồ sơ đã xử lý của học kỳ trước, ẩn danh, làm tập đánh giá có đáp án; viết kiểm thử với TestModel và FunctionModel cho mọi công cụ. [3]
Tuần 4–8, chạy song song với quy trình hiện tại. Chỉ số đề xuất: độ chính xác theo trường, mục tiêu từ 98% với số tín chỉ và điểm; tỷ lệ đề xuất học phần tương đương được chuyên viên chấp nhận; thời gian xử lý mỗi hồ sơ; số run lỗi vì sai lược đồ; chi phí mô hình trên mỗi hồ sơ.
Tuần 9–12, bật công cụ ghi có requires_approval cho một khoa và đo tỷ lệ đề xuất bị từ chối. [7] Dừng nếu có bất kỳ lần ghi nào không qua phê duyệt, nếu độ chính xác vẫn dưới ngưỡng sau hai vòng chỉnh lược đồ và prompt, hoặc nếu chi phí trên hồ sơ vượt ngân sách. Tổng đài thoại để sang đợt sau. Mọi ngưỡng là đề xuất; bài không có số liệu thực nghiệm.
Kết luận: lợi thế nằm ở kỷ luật kiểu dữ liệu
Pydantic AI không cố làm một ứng dụng agent trọn gói. Thế mạnh của nó là biến ranh giới giữa mô hình và phần mềm thành hợp đồng có kiểu: tham số công cụ được kiểm tra, đầu ra được kiểm tra lược đồ, còn phê duyệt và chạy bền là những khối ghép được. [1][3]
Với một trường đại học hay bất kỳ tổ chức nào xử lý hồ sơ, đó là cách tiếp cận dễ kiểm toán: mỗi quyết định có dữ liệu nguồn, có người duyệt, có bài kiểm thử. Đổi lại, tổ chức cần kỹ sư và kỷ luật phiên bản.
Nên khởi đầu bằng một bài toán trích xuất nhỏ có đáp án đối chiếu, chạy song song với quy trình cũ, và chỉ mở rộng khi số liệu tự đo cho thấy lợi ích rõ ràng.
Về nguồn, commit và cách làm của bài
Pydantic AI vào nhóm AI agents và ứng dụng sau khi xuất hiện trong danh sách Python ngày 26/04/2026 của một kho lưu trữ độc lập các trang GitHub Trending; bảng tổng hợp ứng viên của loạt bài ghi nhận dự án tới ngày 01/10/2026. [10] Kho chỉ phủ bốn danh sách Python, Go, JavaScript, Swift và thiếu ngày 03/09, 12/10/2026; loạt bài là tuyển chọn biên tập, không phải Top 100 chính thức của GitHub.
Đối tượng nghiên cứu là commit 69ea1e57201ed59e7d30fbe4a7590d193acecce0 (10/10/2026), kiểm tra ngày 12/10/2026. Bài đã đọc README, LICENSE, ARCHITECTURE.md trong skill building-pydantic-ai-agents, docs/realtime/deployment.md, cùng năm tài liệu bổ sung tại cùng commit: LICENSE của gói harness, docs/version-policy.md, docs/deferred-tools.md, docs/gateway.md và docs/durable_execution/overview.md. [1][2][3][4][5][6][7][8][9]
Đây là nghiên cứu tài liệu có hỗ trợ AI: không cài đặt, không chạy mã, không đo hiệu năng, và không phải công bố khoa học đã qua phản biện. Mã ví dụ trong tài liệu được đọc như mô tả API, không phải bằng chứng đã chạy thử. Tình huống Việt Nam, chi phí, so sánh và kế hoạch thử nghiệm là phân tích, đề xuất của bài.
Xem mã nguồn Pydantic AI trên GitHub