Jika Anda pernah merilis fitur LLM dan menyaksikannya mengembalikan JSON yang salah format dalam produksi, PydanticAI dibuat untuk Anda. Ini adalah kerangka kerja agen Python dari tim di balik Pydantic, dan ini menempatkan keluaran yang aman-tipe dan tervalidasi sebagai pusat pengembangan agen. Panduan ini menjelaskan apa itu PydanticAI, mengapa keamanan tipe penting untuk agen, konsep inti yang akan Anda gunakan, dan bagaimana ia dibandingkan dengan kerangka kerja Python lainnya seperti LangGraph.
Apa itu PydanticAI
PydanticAI adalah kerangka kerja agen sumber terbuka dan agnostik penyedia untuk Python. Ini dikelola oleh tim yang sama yang membangun Pydantic Validation dan Pydantic Logfire, sehingga mewarisi fondasi validasi yang kuat dan tujuan desain yang jelas: membawa "perasaan FastAPI" ke pengembangan agen.
Secara sederhana, Anda mendeskripsikan apa yang harus dilakukan agen Anda, alat apa yang dapat dipanggilnya, dan bentuk seperti apa keluaran yang harus diambilnya. PydanticAI menangani panggilan model, memvalidasi semuanya terhadap model Pydantic Anda, dan mencoba lagi ketika model mengembalikan sesuatu yang tidak sesuai.
Proyek ini mencapai rilis stabil v2.0.0 pada 23 Juni 2026, setelah serangkaian versi beta. V2 menganut desain yang mengutamakan harnes di mana alat, hook, instruksi, dan pengaturan model agen disusun sebagai unit yang dapat digunakan kembali. Anda dapat menginstalnya dengan pip install pydantic-ai atau uv add pydantic-ai.
Mengapa keamanan tipe penting untuk agen
LLM bersifat non-deterministik. Tanyakan pertanyaan yang sama dua kali dan Anda bisa mendapatkan dua bentuk jawaban yang berbeda. Itu tidak masalah untuk kotak obrolan, tetapi akan rusak saat Anda menyambungkan keluaran model ke kode nyata: penulisan database, panggilan API, perhitungan tagihan.
Sebagian besar bug agen berasal dari celah ini. Model "sebagian besar" mengembalikan JSON yang valid, parser Anda berfungsi dalam pengujian, lalu respons produksi menghilangkan bidang atau membungkus jawaban dalam prosa dan alur kerja Anda gagal. Anda akhirnya menulis penguraian defensif, pembersihan regex, dan perulangan percobaan ulang secara manual.
PydanticAI menutup celah ini dengan menjadikan kontrak keluaran sebagai bagian dari kerangka kerja. Anda mendefinisikan model Pydantic, meneruskannya sebagai tipe keluaran, dan kerangka kerja menjamin nilai yang Anda dapatkan kembali sesuai dengan model tersebut. Jika model mengembalikan sesuatu yang tidak valid, PydanticAI mengirimkan kesalahan validasi kembali ke LLM dan memintanya untuk mencoba lagi. Kode hilir Anda menerima objek bertipe, bukan string yang penuh harapan.
Ide yang sama juga berlaku untuk argumen alat. Ketika model memanggil salah satu alat Anda, PydanticAI memvalidasi argumen terhadap petunjuk tipe fungsi Anda sebelum fungsi berjalan. Argumen yang buruk tidak akan pernah mencapai logika bisnis Anda.
Konsep inti
PydanticAI menjaga area permukaannya tetap kecil. Lima ide mencakup sebagian besar yang akan Anda bangun.
Agen
Kelas Agent adalah titik masuk utama. Anda membuat satu dengan pengidentifikasi model dan instruksi opsional. Kelas ini bersifat generik atas dua parameter tipe: tipe dependensi dan tipe keluaran, yang memberikan visibilitas nyata kepada editor dan pemeriksa tipe Anda ke dalam agen Anda.
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)
String model tersebut adalah satu-satunya yang Anda ubah untuk beralih penyedia, yang menjaga kode Anda tetap portabel.
Keluaran bertipe
Teruskan model Pydantic sebagai output_type dan hasil agen akan divalidasi terhadapnya. Anda mendapatkan objek bertipe kembali, dan IDE Anda mengetahui setiap bidang. Berikut adalah sketsa keluaran terstruktur:
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
Jika model mengembalikan prioritas sebagai teks atau menghilangkan ringkasan, validasi akan gagal dan kerangka kerja akan meminta ulang. Anda tidak pernah menguraikan respons mentah sendiri.
Alat
Alat memungkinkan model menjangkau ke luar dirinya: mengkueri database, memanggil REST API, menjalankan perhitungan. Anda mendaftarkan alat dengan dekorator @agent.tool. PydanticAI membaca petunjuk tipe dan docstring fungsi untuk membangun skema yang dilihat model, lalu memvalidasi setiap panggilan terhadapnya.
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)
Model memutuskan kapan harus memanggil alat. Fungsi Anda hanya berjalan dengan argumen yang telah lolos validasi.
Dependensi
Agen nyata membutuhkan konteks: koneksi database, klien HTTP, pengguna saat ini, kunci API. PydanticAI menangani ini dengan injeksi dependensi. Anda mendeklarasikan deps_type pada agen, lalu membacanya melalui RunContext di dalam alat dan instruksi dinamis. Seluruh rantai tetap aman-tipe, dan pengujian menjadi lebih mudah karena Anda dapat menukar dependensi nyata dengan yang palsu.
Penyedia agnostik model dan streaming
PydanticAI mendukung daftar panjang penyedia: OpenAI, Anthropic, Gemini, DeepSeek, Grok, Cohere, Mistral, Perplexity, ditambah opsi cloud seperti Azure AI Foundry dan Amazon Bedrock serta model yang di-host sendiri. Pergantian biasanya hanya perubahan satu baris pada string model.
Ini juga melakukan streaming keluaran terstruktur dengan validasi yang diterapkan saat data tiba, sehingga Anda dapat merender hasil parsial tanpa mengabaikan jaminan tipe. Dan karena tim juga membangun Pydantic Logfire, observabilitas sudah tersedia: pelacakan, debugging, dan pelacakan biaya untuk setiap eksekusi.
Perbandingan PydanticAI dengan kerangka kerja agen Python lainnya
Tidak ada kerangka kerja "terbaik" tunggal. Mereka dioptimalkan untuk hal yang berbeda. Berikut adalah gambaran jujur tentang posisi PydanticAI.
| Kerangka Kerja | Kekuatan Inti | Terbaik saat Anda menginginkan |
|---|---|---|
| PydanticAI | Keluaran dan argumen alat yang aman-tipe dan tervalidasi | Keandalan produksi dan aliran data bertipe yang bersih |
| LangGraph | Grafik stateful eksplisit dan kontrol alur | Alur kerja multi-langkah, bercabang, berjalan lama |
| Google ADK | Orkestrasi multi-agen dalam ekosistem Google | Integrasi Gemini dan Vertex AI yang mendalam |
| OpenAI Agents SDK | Integrasi OpenAI yang erat dengan serah terima | Tumpukan yang mengutamakan OpenAI dan pengaturan cepat |
Keunggulan PydanticAI adalah lapisan validasi. Jika agen Anda memasukkan data bertipe ke sistem lain, jaminan bahwa keluaran sesuai dengan model Pydantic menghilangkan seluruh kelas kesalahan runtime. LangGraph memberi Anda kontrol yang lebih halus atas mesin status dan alur yang kompleks. OpenAI Agents SDK sangat cocok jika Anda sudah berkomitmen pada OpenAI dan menginginkan fitur seperti serah terima agen dan dukungan server MCP.
Anda juga bisa menggabungkannya. PydanticAI berfungsi dengan baik sebagai lapisan keluaran bertipe di dalam orkestrasi yang lebih besar.
Kapan menggunakan PydanticAI
- Keluaran agen Anda masuk ke kode, bukan hanya jendela obrolan, dan bentuknya harus benar.
- Anda ingin pemeriksa tipe dan IDE Anda memahami agen Anda dari ujung ke ujung.
- Anda sudah menggunakan Pydantic dalam codebase Anda, sehingga definisi model terasa alami.
- Anda membutuhkan fleksibilitas penyedia dan tidak ingin menulis ulang agen Anda untuk beralih model.
- Observabilitas penting dan pelacakan bawaan Logfire menarik.
Cari di tempat lain ketika Anda membutuhkan orkestrasi berbasis grafik yang berat dengan percabangan yang kompleks, di mana kerangka kerja mesin status memberi Anda kontrol yang lebih langsung.
Menguji dan memalsukan API di balik agen Anda
Agen PydanticAI hanya bisa diandalkan seperti API yang diandalkannya. Setiap eksekusi memanggil penyedia LLM, dan sebagian besar agen yang berguna juga memanggil endpoint REST Anda sendiri atau alat pihak ketiga. Panggilan-panggilan itulah tempat munculnya perilaku yang tidak stabil, biaya tak terduga, dan ketidaksesuaian bentuk. PydanticAI memvalidasi keluaran model, tetapi tidak dapat memvalidasi bahwa API alat hulu yang Anda panggil mengembalikan apa yang Anda harapkan.
Di sinilah Apidog berperan, dan ini adalah pekerjaan yang berbeda dari kerangka kerja. Apidog adalah platform API tempat Anda menguji dan memalsukan API dasar yang dihubungkan oleh agen Anda.
Beberapa penggunaan konkret:
- Memalsukan LLM atau endpoint alat. Selama pengembangan, arahkan alat ke API palsu yang mengembalikan respons deterministik. Anda berhenti membuang token pada setiap pengujian dan Anda menghindari batas laju penyedia saat berulang.
- Memastikan bentuk respons. Sebelum Anda menyambungkan endpoint REST ke fungsi
@agent.tool, gunakan penegasan API untuk mengonfirmasi respons nyata cocok dengan struktur yang diharapkan alat Anda. Tangkap bidang yang hilang di lapisan API, bukan jauh di dalam eksekusi agen. - Mengelola kunci per lingkungan. Simpan kunci penyedia dan URL dasar di lingkungan Apidog terpisah sehingga eksekusi lokal, staging, dan CI mencapai target yang benar tanpa perubahan kode.
- Verifikasi langsung endpoint LLM. Jika Anda memanggil penyedia melalui HTTP, Anda dapat menguji API ChatGPT dengan Apidog untuk mengonfirmasi format otentikasi, streaming, dan panggilan alat sebelum agen Anda bergantung padanya.
Apidog tidak membangun atau mengorkestrasi agen, dan ini bukan alternatif untuk PydanticAI. Ini adalah bangku tempat Anda menguji dan memalsukan permukaan API tempat agen Anda berjalan. Jika Anda ingin mencobanya, unduh Apidog dan palsukan salah satu endpoint alat Anda terlebih dahulu.
Pertanyaan yang Sering Diajukan
Apakah PydanticAI gratis dan sumber terbuka?
Ya. PydanticAI adalah sumber terbuka dan Anda menginstalnya dari PyPI dengan pip install pydantic-ai atau uv add pydantic-ai. Anda tetap akan membayar penyedia LLM apa pun yang Anda gunakan, karena kerangka kerja ini memanggil API tersebut atas nama Anda. Untuk menjaga biaya penyedia tetap rendah saat Anda membangun, Anda dapat memalsukan respons API selama pengujian alih-alih memanggil model langsung di setiap eksekusi.
Model apa saja yang dapat bekerja dengan PydanticAI?
Ini agnostik penyedia. Dokumennya mencantumkan OpenAI, Anthropic, Gemini, DeepSeek, Grok, Cohere, Mistral, dan Perplexity, ditambah opsi cloud seperti Azure AI Foundry dan Amazon Bedrock serta model yang di-host sendiri. Anda memilih model dengan meneruskan string seperti 'anthropic:claude-sonnet-4-6' atau 'openai:gpt-4o' ke konstruktor Agent, dan pergantian biasanya hanya perubahan satu baris.
Bagaimana PydanticAI berbeda dari LangChain atau LangGraph?
PydanticAI berpusat pada keamanan tipe: keluaran terstruktur yang tervalidasi dan argumen alat yang tervalidasi yang didukung oleh model Pydantic. LangGraph berpusat pada grafik stateful eksplisit untuk alur kerja multi-langkah dan bercabang. Jika prioritas Anda adalah bentuk keluaran yang terjamin dan aliran data bertipe yang bersih, PydanticAI sangat cocok. Jika Anda membutuhkan kontrol yang detail atas mesin status yang kompleks, kerangka kerja grafik memberi Anda lebih banyak kendali langsung.
Apakah saya perlu mengetahui Pydantic untuk menggunakannya?
Membantu, tetapi dasar-dasarnya cepat dipelajari. Anda mendefinisikan bentuk data sebagai kelas yang mewarisi dari BaseModel, dan PydanticAI menggunakannya untuk keluaran dan skema alat. Jika Anda pernah menggunakan Python untuk pengujian API atau bekerja dengan FastAPI, model mentalnya akan terasa akrab.
Kesimpulan
PydanticAI membawa sesuatu yang praktis untuk pengembangan agen: jaminan bahwa keluaran model dan panggilan alat Anda cocok dengan tipe yang Anda deklarasikan. Itu menghilangkan sumber bug produksi yang nyata dan menjaga aliran data Anda tetap bersih. Pilih ini ketika keandalan dan keluaran bertipe lebih penting daripada orkestrasi grafik yang berat.
Kerangka kerja apa pun yang Anda pilih, API di balik agen Anda masih memerlukan pengujian. Palsukan endpoint LLM dan alat Anda, pastikan bentuk responsnya, dan kelola kunci per lingkungan di Apidog sehingga agen Anda berjalan di atas fondasi yang telah Anda verifikasi.