# Pydantic AI: tool có kiểu và eval giúp FDE đổi model mà không phải đánh cược

> Với Pydantic AI, đổi model chỉ cần sửa một chuỗi. Nhưng muốn chứng minh với khách rằng agent vẫn chạy đúng sau khi đổi, bạn cần thêm một bộ eval và một phiên bản thư viện được ghim cố định.

Bản gốc: https://fdetimes.net/vi/cong-cu/pydantic-ai-agent-co-kieu-dau-ra-co-schema/

Giả sử bạn đang ngồi ở văn phòng một công ty logistics. Agent đọc email khiếu nại chạy ổn suốt hai tuần demo, rồi một sáng nó gọi tool tra đơn hàng với mã đơn là cả một câu văn, và hệ thống phía sau trả lỗi 500. Pydantic AI được làm ra để chặn kiểu lỗi này từ sớm.

Pydantic AI tự giới thiệu là SDK Python cho AI, gồm một vòng lặp agent có kiểu dữ liệu, mở rộng được, và muốn đổi sang model khác thì chỉ cần đổi một chuỗi. Thư viện do chính đội làm Pydantic xây dựng, phát hành theo giấy phép MIT. Repo trên GitHub tóm lại bằng một ý: mọi model, mọi interface đều có kiểu từ đầu đến cuối.

Với FDE, giá trị nằm ở chữ "có kiểu". Ở site khách hàng, phần việc khó thường không phải viết prompt hay hơn mà là nối agent vào hệ thống thật của khách, và hệ thống đó không chấp nhận dữ liệu sai hình dạng.

## Kiểu dữ liệu chặn lỗi ở đâu?

Pydantic AI đưa kiểu dữ liệu vào ba chỗ: structured output, dependency injection có kiểu và tool có kiểu. Chi tiết đáng chú ý nhất nằm ở tool. Tham số mà model sinh ra được kiểm tra bằng schema trước khi code của bạn chạy.

Quay lại ví dụ logistics. Bạn khai báo tool `tra_don_hang` nhận một mã đơn theo định dạng cố định. Khi model đưa vào cả câu "đơn của tôi giao trễ", lớp kiểm tra bắt lỗi trước khi request chạm tới API của khách. Lỗi xảy ra trong agent, nơi bạn còn xử lý được, thay vì trong log của đội vận hành phía khách.

Output cũng vậy. Bạn có thể yêu cầu agent trả về một ticket với ba trường: loại sự cố, mã đơn, mức ưu tiên. Phía nhận là hệ thống ticketing của khách, và nó cần đúng ba trường đó chứ không cần một đoạn văn. Hợp đồng dữ liệu được viết bằng code Python, nên đồng nghiệp phía khách đọc là hiểu, không cần đoán từ prompt.

## Đổi model là đổi một chuỗi, kiểm lại cần thêm một bộ eval

Đổi model bằng một chuỗi rất tiện khi khách hỏi "dùng model rẻ hơn được không". Nhưng tiện không có nghĩa là an toàn. Muốn trả lời câu hỏi đó cho đàng hoàng, bạn cần một con số đo được, và Pydantic Evals là công cụ để đo.

Pydantic Evals là một gói riêng, cài độc lập bằng pip hoặc uv và không phụ thuộc pydantic-ai. Nhờ vậy bạn dùng được nó cả cho những hệ thống AI không viết bằng Pydantic AI. Logfire là phụ thuộc tùy chọn, dùng khi cần quan sát kết quả.

Cách Evals tổ chức một bài kiểm tra khá gọn. Dataset gồm nhiều Case, mỗi Case là một kịch bản kiểm thử. Task là thứ bạn chạy, ở đây là agent. Evaluator phân tích và chấm điểm kết quả của Task trên từng Case. Đội Pydantic so sánh nó với cách pytest kiểm thử code, và đó cũng là cách nên dùng nó.

**Điểm mấu chốt:** Agent chưa có bộ eval thì mỗi lần đổi model là một lần đánh cược.

## Một bộ eval nhỏ trông thế nào?

Thử hình dung bạn lấy 30 email thật đã được khách ẩn danh, mỗi email là một Case kèm ticket đúng mà nhân viên hỗ trợ đã gán. Evaluator kiểm tra hai việc: mã đơn trích ra có khớp không, và mức ưu tiên có đúng không. Các con số dưới đây là giả định để minh họa.

| Cấu hình | Case pass / 30 | Tỷ lệ |
|---|---|---|
| Model hiện tại | 27 | 90% |
| Model rẻ hơn khách đề xuất | 24 | 80% |

Model rẻ hơn rớt thêm 3 Case, tức là cứ 30 email thì có thêm 3 ticket sai. Lúc này khách tự quyết được: ba ticket sai đó có đáng đổi lấy phần tiết kiệm hay không. Nếu không có bảng này, bạn chỉ có cảm giác để trả lời. Có bảng rồi thì buổi họp chuyển sang bàn về đánh đổi, không còn tranh luận cảm tính.

Việc đầu tiên nên làm ở khách hàng là xin dữ liệu cho Dataset, trước cả khi viết agent. Ba mươi Case có nhãn đúng có giá trị hơn mọi buổi demo.

## Giới hạn: API thay đổi nhanh hơn bạn nghĩ

V1 ra ngày 4/9/2025, kèm cam kết không phá vỡ code ít nhất 6 tháng, và đưa ra khả năng durable execution: agent bị crash giữa một workflow phức tạp có thể chạy tiếp từ đúng chỗ dừng. Với các quy trình dài ở doanh nghiệp, đây là tính năng đáng thử.

Nhưng nhịp phát hành rất nhanh. Bài giới thiệu v2 của Douwe Maan ngày 23/6/2026 đưa ra khái niệm capability, gộp instructions, tool, hook và model settings thành một đơn vị để ghép.

Kèm theo đó là một breaking change dễ gây lỗi âm thầm: tên model `openai:` giờ dùng Responses API, muốn giữ Chat Completions thì phải đổi sang `openai-chat:`. Khoảng thời gian cam kết không phá vỡ code giữa hai bản major cũng rút từ 6 xuống 3 tháng.

Trên PyPI, phiên bản mới nhất là 2.54.0, ra ngày 3/10/2026, yêu cầu Python 3.10 trở lên. Hệ quả cho FDE: luôn ghim phiên bản trong dự án của khách, và chạy lại bộ eval mỗi lần nâng cấp. Bộ eval vừa dùng để so model, vừa là lưới an toàn khi nâng phiên bản.

## Học gì trước, ghi gì vào CV?

Nếu bạn đã quen Pydantic trong FastAPI, bạn đã có sẵn nửa nền tảng. Học theo thứ tự: structured output, rồi tool có kiểu, rồi dependency injection, sau cùng mới tới capability của v2. Song song, viết bộ eval đầu tiên ngay từ tuần đầu, đừng để đến cuối dự án.

Khi đọc JD vị trí FDE hay AI engineer, hãy để ý những cụm như "evaluation", "structured output", "production agent". Trong CV, câu "dùng Pydantic AI" không nói được nhiều. Câu "dựng Dataset 30 Case, phát hiện model thay thế giảm 10 điểm pass trước khi lên production" cho nhà tuyển dụng thấy bạn làm việc như một FDE.

Thư viện còn đổi nhiều. Cách làm nó khuyến khích thì đáng giữ: định nghĩa dữ liệu bằng code, đo hành vi bằng eval, rồi mới đổi model.

**Thử ngay tuần này:**

- Cài pydantic-ai trên Python 3.10 trở lên. Dựng một agent trả về một model Pydantic có ba trường và có một tool tra cứu giả lập.
- Cài riêng pydantic-evals, viết một Dataset 20 Case từ dữ liệu bạn tự bịa, chạy với hai chuỗi model khác nhau và so tỷ lệ pass.
- Mở file dependency của dự án, ghim phiên bản pydantic-ai và ghi chú lại nếu code đang dùng tên model openai:.

## Nguồn

- [Pydantic AI](https://pydantic.dev/docs/ai/overview/)

- [Pydantic Evals](https://pydantic.dev/docs/ai/evals/evals/)

- [Pydantic AI v1: A Predictable & Robust GenAI Framework](https://pydantic.dev/articles/pydantic-ai-v1)

- [Pydantic AI v2: capable agentic loops](https://pydantic.dev/articles/pydantic-ai-v2)

- [GitHub - pydantic/pydantic-ai](https://github.com/pydantic/pydantic-ai)

- [pydantic-ai · PyPI](https://pypi.org/project/pydantic-ai/)