Bedah Produk Keren: Mengupas Arsitektur Agen Type-Safe di Balik pydantic/pydantic-ai

Ringkasan: Pydantic AI adalah Python AI SDK yang membawa level type-safety dan dependency injection ala FastAPI ke dalam arsitektur LLM agent. Framework ini memungkinkan engineer membangun agent loop yang tervalidasi penuh secara end-to-end, bersifat model-agnostic (bisa ganti model hanya dengan ubah string), dan siap berjalan di berbagai environment mulai dari terminal hingga durable background queue seperti Temporal.

Selamat datang di bedah arsitektur DO-AI di Bicara IT. Kalau kalian sering nongkrong di repositori GitHub akhir-akhir ini, kalian pasti sadar bahwa ekosistem AI engineering sedang mengalami pergeseran besar. Kita mulai bergerak dari era "bikin prompt panjang dan berdoa LLM mengembalikan JSON yang benar" menuju era software engineering yang sesungguhnya. Dan di tengah pergeseran ini, ada satu tool yang menurut gue benar-benar mengubah cara kita menulis kode AI di Python.

Hari ini, di bicarait.com, kita akan melakukan teardown teknis mendalam untuk salah satu cool products yang sedang naik daun: Pydantic AI. Mari kita bongkar bagaimana tim di balik library validasi data paling populer di Python ini merancang arsitektur agent yang type-safe.

Apa Itu Cool Products: Inside pydantic/pydantic-ai Type-Safe Agent Architecture & Mengapa Sedang Trending?

Jika kalian pernah membangun aplikasi berbasis LLM di production, kalian pasti tahu betapa flaky atau rapuhnya sistem tersebut. LLM pada dasarnya adalah mesin penebak teks probabilistik. Ketika kita menyuruh mereka memanggil fungsi (function calling) atau mengembalikan data terstruktur, sering kali mereka berhalusinasi dengan memberikan argumen yang salah tipe, atau menghilangkan field yang wajib ada.

Di sinilah pydantic/pydantic-ai masuk dan langsung meledak di kalangan developer. Pydantic AI pada dasarnya adalah Python AI SDK yang dirancang dengan satu filosofi utama: Setiap model, setiap antarmuka, harus memiliki tipe (typed) dari ujung ke ujung.

Mengapa repository ini sangat trending? Karena ia memecahkan masalah fundamental dalam pengembangan agentic workflow. Alih-alih menggunakan framework yang membungkus LLM dengan abstraksi black-box yang tebal dan sulit di-debug, Pydantic AI menggunakan pendekatan yang sangat Pythonic. Mereka membawa konsep yang membuat FastAPI sangat sukses—yaitu validasi data berbasis Pydantic dan Dependency Injection—langsung ke dalam agent loop.

Berdasarkan dokumentasi resminya di Pydantic AI Docs, framework ini tidak hanya sekadar wrapper API. Ia adalah extensible agent loop di mana setiap model LLM (baik itu OpenAI, Anthropic, Gemini, Groq, atau Ollama lokal) hanya berjarak satu "string swap" saja. Kalian bisa menjalankan agent yang sama persis di belakang web frontend, di dalam terminal CLI, pada panggilan suara (voice call) secara realtime, atau bahkan di atas durable background queue menggunakan Temporal atau DBOS.

Selain itu, Pydantic AI juga memperkenalkan Pydantic AI Harness. Ini adalah kumpulan capabilities yang bisa langsung "ditempelkan" (snapped on) ke agent kalian untuk menangani pekerjaan kompleks yang berjalan lama. Butuh memory? Ada. Butuh sub-agents? Tinggal pasang. Butuh context management atau bahkan coding agent lengkap dengan akses file system dan shell? Semuanya sudah tersedia di dalam harness ini. Ini bukan sekadar mainan; ini adalah fondasi untuk membangun sistem AI kelas enterprise yang bisa diandalkan.

Di Balik Layar: Arsitektur & Keputusan Desain

Sebagai systems engineer, hal pertama yang gue cari ketika mengevaluasi framework baru adalah bagaimana mereka mengatur state dan dependensi. Banyak framework AI di luar sana yang mengandalkan global state atau context object yang sangat kotor, membuat unit testing menjadi mimpi buruk. Pydantic AI mengambil rute yang jauh lebih elegan.

Mari kita lihat arsitektur internalnya melalui diagram eksekusi berikut:

flowchart LR
    Client([Client Application]) --> |run_sync / run| AgentContainer
    
    subgraph Pydantic_AI_Architecture["Pydantic AI Architecture"]
        Deps[(Dependencies<br/>Dataclass)] --> |Injected via| RunContext
        
        subgraph AgentContainer [Agent Class]
            RunContext --> SystemPrompt["@agent.system_prompt"]
            RunContext --> Tools["@agent.tool"]
            
            SystemPrompt --> InstructionBuilder
            Tools --> FunctionSchema
        end
        
        InstructionBuilder --> LLMRequest
        FunctionSchema --> LLMRequest
    end
    
    LLMRequest --> |Network Call| LLM((LLM Provider<br/>OpenAI, Anthropic,<br/>Gemini, dll))
    LLM --> |Raw JSON / Tool Call| Validator[Pydantic Validator]
    Validator --> |Type-Safe| StructuredOutput[Output Type]
    StructuredOutput --> Client

Berdasarkan dokumentasi Agents, kelas Agent di Pydantic AI sebenarnya adalah sebuah container. Ia bukan entitas yang aktif berjalan sendiri, melainkan wadah yang menyimpan:

1. Instructions: Instruksi dasar untuk LLM.
2. Function tools: Fungsi-fungsi Python murni yang bisa dipanggil oleh LLM.
3. Structured output type: Skema data (biasanya berupa BaseModel dari Pydantic) yang wajib dikembalikan oleh LLM di akhir run.
4. Dependency type constraint: Tipe data untuk dependensi yang akan disuntikkan saat runtime.

Sistem Dependency Injection (DI) Ini adalah fitur pembunuh (killer feature) dari Pydantic AI. Menurut panduan Dependencies, Pydantic AI menggunakan sistem DI untuk menyediakan data dan layanan (seperti koneksi database atau HTTP client) ke system prompts, tools, dan output validators.

Kalian mendefinisikan dependensi sebagai sebuah dataclass Python biasa. Kemudian, kalian memberikan tipe dataclass tersebut ke parameter deps_type saat menginisialisasi Agent. Saat runtime, dependensi ini diakses melalui objek RunContext. Ini berarti fungsi tool kalian tidak perlu memanggil global variable. Semuanya disuntikkan secara eksplisit. Jika kalian ingin melakukan mocking database untuk unit test, kalian cukup melempar dataclass dependensi palsu saat memanggil agent.run(). Sangat brilian dan sangat testable.

Abstraksi Model dan Provider Keputusan desain cerdas lainnya ada pada lapisan model. Merujuk pada dokumentasi Models, Pydantic AI memisahkan konsep Model dan Provider.

• Model adalah kelas yang mengimplementasikan API agnostik (misalnya OpenAIChatModel atau AnthropicModel).
• Provider adalah kelas spesifik yang menangani autentikasi dan koneksi (misalnya AzureProvider jika kalian menggunakan OpenAI via Azure).

Desain ini memungkinkan fitur seperti Fallback Model. Jika API utama kalian (misalnya OpenAI) mengalami rate limit atau downtime, Pydantic AI bisa secara otomatis melakukan fallback ke model lain (misalnya Gemini atau model lokal via Ollama) tanpa mengubah satu baris pun logika agent kalian.

Quickstart Praktis & Bedah Kode

Cukup dengan teorinya, mari kita lihat bagaimana kode aslinya berjalan. Gue akan menunjukkan dua use case utama yang diambil langsung dari dokumentasi resmi mereka: membangun Coding Agent di terminal dan melakukan Data Extraction yang type-safe.

1. Menjalankan Coding Agent di Terminal

Pydantic AI Harness menyediakan agen coder bawaan yang memiliki akses ke file system kalian, shell yang di-allowlist, orientasi repositori, dan manajemen konteks. Kalian bahkan tidak perlu menulis kode untuk mencobanya pertama kali. Kalian bisa menggunakan CLI Pydantic AI (clai) via uvx (tool dari ekosistem Astral/Ruff yang sangat cepat).

Jalankan perintah ini di terminal kalian:

uvx --with pydantic-ai-harness clai -a pydantic_ai_harness.coder:coder_agent -m anthropic:claude-fable-5

Perintah di atas akan mengunduh dependensi secara on-the-fly dan langsung menjalankan agen coder menggunakan model Claude.

Jika kalian ingin membangunnya sendiri di dalam skrip Python dan menambahkan capabilities lain seperti Web Search dan Advisor (model kedua yang memberikan opini tambahan jika model pertama stuck), kodenya terlihat seperti ini:

uv add pydantic-ai pydantic-ai-harness

from pydantic_ai import Agent
from pydantic_ai.capabilities import WebSearch
from pydantic_ai_harness import Advisor, Coder

agent = Agent(
    'anthropic:claude-fable-5',
    capabilities=[
        Coder(),  # files, shell, repo context, planning, sub-agents, context management
        WebSearch(),  # look up docs and error messages on the web
        Advisor('openai:gpt-5.6-sol'),  # a second opinion from another model when stuck
    ],
)

agent.to_cli_sync()

Perhatikan bagaimana Coder() bukanlah sebuah black box. Di balik layar, ia hanyalah komposisi dari capabilities kecil seperti FileSystem('.'), Shell(cwd='.'), dan Planning(). Ini memberi engineer kontrol penuh untuk membongkar pasang kemampuan agent sesuai kebutuhan keamanan infrastruktur.

2. Data Extraction dengan Validasi Ketat

Ini adalah skenario di mana Pydantic AI benar-benar bersinar. Katakanlah kita ingin mengekstrak sentimen dari ulasan produk. Kita ingin LLM mengembalikan data yang terstruktur, bukan teks bebas.

uv add pydantic-ai

from typing import Literal
from pydantic import BaseModel, Field
from pydantic_ai import Agent, RunContext

# 1. Definisikan struktur output yang kita inginkan
class Sentiment(BaseModel):
    label: Literal['positive', 'negative', 'neutral']
    score: float = Field(ge=-1, le=1)

# 2. Inisialisasi Agent dengan output_type
agent = Agent('openai:gpt-5.6-sol', output_type=Sentiment)

# 3. Berikan tool kepada agent menggunakan decorator
@agent.tool
def recent_reviews(ctx: RunContext[None], product: str) -> list[str]:
    """Fetch recent review snippets for a product."""
    # Di dunia nyata, ini akan melakukan query ke database
    return ['The new release fixed everything I complained about!']

# 4. Jalankan agent
result = agent.run_sync('How are people feeling about the Extract app?')

print(result.output)
#> label='positive' score=0.9

Bedah Kode:

• Kita mendefinisikan Sentiment sebagai BaseModel. Kita bahkan menggunakan Field(ge=-1, le=1) untuk memastikan skor berada di antara -1 dan 1.
• Kita memasukkan output_type=Sentiment ke dalam Agent. Pydantic AI akan secara otomatis menerjemahkan skema Pydantic ini menjadi JSON Schema yang dimengerti oleh LLM (menggunakan fitur Structured Outputs dari OpenAI atau tool calling di model lain).
• Fungsi recent_reviews dihiasi dengan @agent.tool. Perhatikan parameter ctx: RunContext[None]. Ini adalah jalur masuk untuk Dependency Injection yang kita bahas sebelumnya. Sisa dari signature fungsi dan docstring-nya (product: str dan deskripsinya) secara otomatis diubah menjadi skema tool yang diberikan ke LLM.
• Hasil akhirnya (result.output) dijamin merupakan instance dari kelas Sentiment. IDE kalian (seperti VS Code atau PyCharm), type checker (seperti Mypy), dan LLM semuanya sepakat pada tipe data yang dikembalikan. Tidak ada lagi parsing error!

Analisis Jujur Saya: Kapan Harus Menggunakannya (Pro & Kontra)

Sebagai engineer yang telah mencoba berbagai framework AI mulai dari LangChain, LlamaIndex, hingga menulis wrapper API mentah sendiri, gue punya pandangan yang cukup jelas tentang di mana posisi Pydantic AI dalam stack teknologi kita saat ini.

Kelebihan (Pros)

1. Type-Safety adalah Raja: Ini adalah alasan utama gue merekomendasikan Pydantic AI. Mengetahui bahwa output dari LLM dijamin sesuai dengan skema Pydantic (atau akan di-retry secara otomatis jika gagal) memberikan ketenangan pikiran yang luar biasa saat mendeploy ke production.
2. Dependency Injection yang Masuk Akal: Penggunaan RunContext dan deps_type menyelesaikan masalah state management yang selama ini menjadi wabah di framework lain. Membuat unit test untuk tools yang membutuhkan koneksi database kini semudah memanggil fungsi Python biasa dengan mock object.
3. Durable Execution: Ini sangat underrated. Pydantic AI memiliki integrasi first-party dengan Temporal dan DBOS. Jika kalian membangun agent yang harus melakukan web scraping, menunggu respons API eksternal, dan berjalan selama berjam-jam, kalian bisa membungkusnya dengan TemporalDurability(). Jika server kalian mati di tengah jalan, workflow akan dilanjutkan tepat di titik terakhir ia berhenti. Ini adalah fitur kelas enterprise sejati.
4. Dukungan Realtime Voice & Multimodal: Pydantic AI tidak hanya untuk teks. Kemampuan untuk memasang agent yang sama ke sesi suara langsung (live voice session) menggunakan model seperti gpt-realtime dengan tools yang tetap berfungsi adalah lompatan besar untuk membangun asisten suara interaktif.

Trade-offs & Keterbatasan (Kontra)

Namun, tentu saja tidak ada silver bullet dalam software engineering. Ada beberapa hal yang perlu kalian pertimbangkan:

1. Kurva Pembelajaran Pydantic V2: Jika tim kalian belum terbiasa dengan fitur-fitur lanjutan Pydantic V2 (seperti computed fields, custom validators, atau pemahaman mendalam tentang JSON Schema generation), Pydantic AI bisa terasa sedikit mengintimidasi. Framework ini sangat bergantung pada pemahaman yang kuat tentang sistem pengetikan (typing system) Python modern.
2. Ekosistem "Pre-built" yang Lebih Kecil: Dibandingkan dengan LangChain yang memiliki ribuan integrasi loader dokumen dan vector store pihak ketiga, Pydantic AI jauh lebih ramping. Pydantic AI berasumsi bahwa kalian adalah engineer yang bisa menulis fungsi koneksi database atau pencarian vector kalian sendiri menggunakan pustaka standar (seperti psycopg atau httpx), lalu membungkusnya sebagai @agent.tool. Bagi gue, ini adalah nilai plus karena mengurangi bloatware, tapi bagi pemula yang mencari solusi plug-and-play untuk RAG, ini mungkin terasa kurang instan.
3. Verbosity untuk Skrip Sederhana: Jika kalian hanya ingin membuat skrip 10 baris untuk merangkum teks dengan LLM, menggunakan Pydantic AI mungkin terasa overkill. Mendefinisikan dataclass dependensi dan RunContext untuk tugas sekali jalan (throwaway script) bisa memperlambat momentum.

Verdict Akhir Gue: Kapan gue akan menggunakan Pydantic AI? Jawabannya: Hampir di semua proyek AI production mulai sekarang.

Jika kalian sedang membangun sistem di mana keandalan data sangat kritis—seperti agen dukungan bank, ekstraksi data medis, atau coding assistant otomatis—Pydantic AI adalah pilihan yang jauh lebih superior dan maintainable dibandingkan framework berbasis chain yang kaku. Ia memaksa kita untuk menulis kode AI layaknya kita menulis backend service tradisional: terstruktur, dapat diuji (testable), dan aman dari segi tipe data.

Pydantic AI membuktikan bahwa kita tidak butuh paradigma pemrograman baru yang aneh untuk bekerja dengan LLM. Kita hanya butuh praktik software engineering yang baik, dan framework ini menyediakannya dengan sangat elegan. Cobalah jalankan uv add pydantic-ai di proyek kalian selanjutnya, dan rasakan sendiri bedanya.

Use Case Nyata di Lapangan: Ide Implementasi Praktis

Bagi CTO dan Lead Engineer, nilai utama Pydantic AI bukan pada kebaruan teknologi AI agent, melainkan pada keandalan eksekusinya. Dengan memaksakan skema yang ketat dan dependency injection, framework ini mengubah output LLM yang tidak terprediksi menjadi aliran data stabil yang dapat diintegrasikan ke dalam logika bisnis mission-critical tanpa takut sistem crash atau data korup.

1. Audit Kepatuhan Keuangan Otomatis

• Masalah Sehari-hari di Lapangan: Tim kepatuhan meninjau ribuan log transaksi secara manual untuk mencari pola yang melanggar kebijakan internal, namun LLM sering kali memberikan ringkasan yang tidak konsisten sehingga merusak dashboard pelaporan otomatis.
• Cara Kerja Implementasinya: Agent didefinisikan dengan model Pydantic ComplianceReport sebagai tipe output. Agent menggunakan RunContext untuk menyuntikkan koneksi database read-only, memungkinkannya menanyakan metadata transaksi sementara validator Pydantic memastikan setiap temuan menyertakan 'PolicyID' dan 'RiskScore' yang wajib ada.
• Dampak Nyata pada Bisnis & Sistem: Validitas skema 100% untuk pelaporan hilir, mengurangi pengawasan audit manual sebesar 70% sambil mempertahankan audit trail yang ketat untuk setiap pemanggilan tool.

2. Agen Dukungan & Inventaris E-commerce Dinamis

• Masalah Sehari-hari di Lapangan: Bot dukungan pelanggan sering berhalusinasi tentang ketersediaan produk atau harga karena mereka tidak memiliki akses real-time ke database inventaris atau gagal menangani struktur JSON kompleks yang diperlukan oleh sistem ERP.
• Cara Kerja Implementasinya: Menggunakan dependency injection Pydantic AI, agent diberikan InventoryClient secara langsung. Saat pengguna bertanya tentang produk, agent memanggil tool bertipe check_stock(sku: str). Framework memastikan SKU dalam format string yang valid sebelum tool dieksekusi, dan respons akhir divalidasi berdasarkan tingkatan keanggotaan pengguna (misalnya, menampilkan harga 'Gold' vs 'Standard').
• Dampak Nyata pada Bisnis & Sistem: Penghapusan halusinasi harga dan pengurangan 40% dalam eskalasi tiket dukungan karena pengambilan data real-time yang akurat.

3. Ekstraksi Data & Triase Layanan Kesehatan

• Masalah Sehari-hari di Lapangan: Mengekstraksi data terstruktur dari catatan dokter yang tidak terstruktur rentan terhadap kesalahan, di mana LLM mungkin menukar ID pasien atau salah menafsirkan unit dosis, yang menyebabkan risiko klinis yang berbahaya.
• Cara Kerja Implementasinya: Agent Pydantic AI dikonfigurasi dengan skema ClinicalSummary yang ketat yang memerlukan unit spesifik (misalnya, 'mg', 'ml'). Jika LLM mengembalikan dosis tanpa unit, logika retry Pydantic AI secara otomatis meminta model untuk memperbaiki data yang hilang berdasarkan kesalahan validasi, memastikan hanya data yang diformat sempurna yang masuk ke sistem Rekam Medis Elektronik (EHR).
• Dampak Nyata pada Bisnis & Sistem: Pengurangan signifikan dalam kesalahan entri data dan proses triase yang lebih efisien yang memungkinkan klinisi fokus pada kasus berisiko tinggi yang diidentifikasi oleh data yang tervalidasi.