Pydantic AI: Panduan Produksi (Melampaui Hello World)

Pydantic AI: Panduan Produksi (Melampaui Hello World)

Output LLM mentah merusak aplikasi. Anda meminta JSON, Anda mendapatkan markdown. Anda meminta angka antara 1 dan 10, Anda mendapatkan "Tentu! Ini angkanya: tujuh." Jika Anda pernah membangun sesuatu yang nyata dengan API LLM, Anda pasti telah menulis kode parsing defensif yang membuat Anda mempertanyakan pilihan karier Anda. Pydantic AI memperbaiki ini; ini adalah kerangka kerja agen yang aman secara tipe yang dibangun oleh tim yang sama di balik Pydantic dan FastAPI. Anggap saja sebagai "FastAPI untuk agen AI": Anda mendefinisikan apa yang Anda inginkan dengan hint tipe Python, dan kerangka kerja menangani validasi, percobaan ulang, serta pemanggilan alat.

Panduan Pydantic AI ini ditujukan untuk developer yang sudah menjalankan panggilan LLM pertama mereka dan menginginkan pola produksi: output terstruktur yang tidak rusak, injeksi dependensi untuk agen yang dapat diuji, dan alat dunia nyata di luar API cuaca. Pada akhirnya, Anda akan memiliki agen yang berfungsi dengan alat, DI, streaming, dan tes.

Sekilas Tentang Pydantic AI

Fitur yang menonjol adalah output terstruktur (divalidasi dengan model Pydantic), injeksi dependensi (seperti Depends milik FastAPI), dan TestModel (LLM mock untuk pengujian tanpa panggilan API). Jika Anda berasal dari LangChain dan bertanya-tanya "apakah ada sesuatu yang lebih bersih?", kemungkinan besar inilah jawabannya.

Instalasi dan Agen Pertama

# Install with OpenAI support (swap openai for anthropic, google, etc.)
pip install "pydantic-ai[openai]"

# Set your API key
export OPENAI_API_KEY="sk-..."

Agen pertama Anda dalam 5 baris:

from pydantic_ai import Agent

agent = Agent("openai:gpt-4o", system_prompt="You are a helpful assistant.")

result = agent.run_sync("What's the capital of France?")
print(result.output)  # "Paris"

Selesai. Agent membungkus model, run_sync mengirim prompt dan mengembalikan hasil. result.output di sini adalah string biasa, tetapi itu akan segera berubah.

Output Terstruktur, Alasan Pydantic AI Ada

Ini adalah fitur inti. Alih-alih mendapatkan string kembali dari LLM dan berharap itu adalah JSON yang valid, Anda mendefinisikan model Pydantic dan agen mengembalikan objek Python yang telah divalidasi.

Sebelumnya: Output LLM Mentah

# The old way -- hope for the best
from openai import OpenAI

client = OpenAI()
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Review the movie Inception. Return JSON with title, rating (1-10), summary."}]
)
# response.choices[0].message.content is a string
# Maybe it's JSON. Maybe it has markdown code fences. Maybe rating is "eight".
# You're on your own.

Sesudah: Terstruktur dengan Pydantic AI

from pydantic import BaseModel
from pydantic_ai import Agent

class MovieReview(BaseModel):
    title: str
    rating: int  # Guaranteed to be an int, not "eight"
    summary: str
    recommended: bool

agent = Agent("openai:gpt-4o", result_type=MovieReview)

result = agent.run_sync("Review the movie Inception")
review = result.output  # This is a MovieReview instance, not a string

print(f"{review.title}: {review.rating}/10")
print(f"Recommended: {review.recommended}")
print(review.summary)

Perbedaannya sangat jelas. result.output adalah objek MovieReview yang nyata. Jika LLM mengembalikan rating: "eight" alih-alih rating: 8, validasi Pydantic akan menanganinya. Untuk tinjauan lebih mendalam tentang cara kerjanya di berbagai penyedia, lihat panduan kami tentang output terstruktur di berbagai penyedia LLM.

Apa yang Terjadi Ketika Validasi Gagal

Inilah bagian yang tidak ditunjukkan oleh tutorial lain: apa yang terjadi ketika LLM melakukan kesalahan?

from pydantic import BaseModel, Field
from pydantic_ai import Agent

class StrictReview(BaseModel):
    title: str
    rating: int = Field(ge=1, le=10)  # Must be 1-10
    pros: list[str] = Field(min_length=2)  # At least 2 pros

agent = Agent("openai:gpt-4o", result_type=StrictReview)

# If the LLM returns rating=15 or only 1 pro:
# 1. Pydantic validation fails
# 2. The error message is sent BACK to the LLM
# 3. The LLM tries again with the corrected output
# 4. This repeats up to the retry limit
result = agent.run_sync("Review the movie Inception")

Loop percobaan ulang dengan umpan balik ini adalah fitur unggulan Pydantic AI. LLM belajar dari kesalahan validasinya sendiri. Anda tidak perlu menulis logika percobaan ulang, kerangka kerja yang menanganinya.

Vonis: Output terstruktur adalah alasan tunggal terbaik untuk menggunakan Pydantic AI dibandingkan panggilan API mentah. Jika Anda mengurai JSON LLM secara manual, hentikan sekarang.

Alat dan Pemanggilan Fungsi

Alat memungkinkan agen Anda memanggil fungsi Python untuk mendapatkan data nyata. Alih-alih LLM berhalusinasi fakta, ia dapat menanyakan database Anda, mencari dokumen Anda, atau memanggil API.

Mendaftarkan Alat

from pydantic_ai import Agent

agent = Agent("openai:gpt-4o")

@agent.tool
async def search_docs(query: str) -> str:
    """Search the documentation for relevant articles."""
    # Your actual search logic here
    results = await doc_search_engine.search(query, limit=5)
    return "\n".join(r.title + ": " + r.snippet for r in results)

Dekorator @agent.tool mendaftarkan fungsi tersebut. Pydantic AI membaca hint tipe dan docstring fungsi untuk memberitahu LLM apa yang dilakukan alat tersebut, argumen apa yang diambilnya, dan apa yang dikembalikannya. Tidak perlu penulisan skema manual, hint tipe Anda ADALAH skemanya. Untuk latar belakang tentang cara kerja pemanggilan fungsi LLM di balik layar, kami memiliki panduan khusus.

RunContext: Meneruskan Data ke Alat

Di sinilah Pydantic AI berbeda dari kerangka kerja lain. RunContext memungkinkan Anda meneruskan data waktu proses (koneksi database, info pengguna, klien API) ke alat Anda tanpa status global.

from dataclasses import dataclass
from pydantic_ai import Agent, RunContext

@dataclass
class SupportDeps:
    customer_id: str
    db_connection: DatabaseConnection

agent = Agent("openai:gpt-4o", deps_type=SupportDeps)

@agent.tool
async def get_order_history(ctx: RunContext[SupportDeps], limit: int = 5) -> str:
    """Fetch recent orders for the current customer."""
    orders = await ctx.deps.db_connection.query(
        "SELECT * FROM orders WHERE customer_id = $1 ORDER BY date DESC LIMIT $2",
        ctx.deps.customer_id, limit
    )
    return format_orders(orders)

ctx.deps memberikan akses alat kepada apa pun yang Anda berikan saat runtime. Alat tersebut tidak mengimpor koneksi database global, melainkan menerimanya. Ini adalah injeksi dependensi, dan inilah yang membuat agen Anda dapat diuji.

Contoh Alat Dunia Nyata

@agent.tool
async def run_sql_query(ctx: RunContext[SupportDeps], sql: str) -> str:
    """Run a read-only SQL query against the analytics database.
    Only SELECT queries are allowed."""
    if not sql.strip().upper().startswith("SELECT"):
        return "Error: only SELECT queries are allowed"
    results = await ctx.deps.db_connection.fetch(sql)
    return json.dumps(results, default=str)

Vonis: Pemanggilan alat di Pydantic AI lebih bersih daripada kerangka kerja lain berkat hint tipe yang melakukan pekerjaan berat. Anda menulis fungsi Python normal dengan anotasi tipe. Kerangka kerja mengurus sisanya.

Injeksi Dependensi, Fitur yang Diinginkan LangGraph

Jika Anda pernah menggunakan Depends milik FastAPI, Anda sudah memahami sistem DI Pydantic AI. Jika belum, berikut versi singkatnya: alih-alih agen Anda reaching out untuk mengambil apa yang dibutuhkannya (koneksi database global, klien API, konfigurasi), Anda memberikannya semuanya saat runtime.

Mendefinisikan Dependensi

from dataclasses import dataclass
from pydantic_ai import Agent

@dataclass
class AppDeps:
    db: AsyncDatabasePool
    search_client: SearchAPIClient
    current_user: User

agent = Agent(
    "openai:gpt-4o",
    deps_type=AppDeps,
    system_prompt="You are a customer support agent."
)

Menggunakan Dependensi dalam Alat

@agent.tool
async def lookup_account(ctx: RunContext[AppDeps]) -> str:
    """Look up the current user's account details."""
    account = await ctx.deps.db.fetchrow(
        "SELECT * FROM accounts WHERE user_id = $1",
        ctx.deps.current_user.id
    )
    return json.dumps(account, default=str)

# Run with real dependencies
result = await agent.run(
    "What's my account status?",
    deps=AppDeps(db=real_db, search_client=real_search, current_user=user)
)

Mengapa DI Membuat Agen Anda Dapat Diuji

Ini adalah hasil nyatanya. Di LangChain, Anda akan meneruskan konteks melalui kwargs rantai atau closure, tidak ada pola standar. Di Pydantic AI, menukar dependensi nyata dengan double tes sangatlah mudah:

# In your test file
from pydantic_ai import Agent
from your_app import agent, AppDeps

async def test_account_lookup():
    mock_deps = AppDeps(
        db=MockDatabase({"user_123": {"status": "active", "plan": "pro"}}),
        search_client=MockSearch(),
        current_user=User(id="user_123")
    )
    result = await agent.run("What's my account status?", deps=mock_deps)
    assert "active" in result.output
    assert "pro" in result.output

Tidak ada monkey-patching. Tidak ada mocking impor global. Anda cukup meneruskan deps yang berbeda.

Vonis: Injeksi dependensi adalah alasan mengapa developer Python berpengalaman lebih memilih Pydantic AI. Ini adalah pengaruh FastAPI yang terlihat jelas.

Penyedia Model, OpenAI, Anthropic, Gemini, Ollama

Pydantic AI bersifat agnostik model. Mengganti penyedia hanyalah perubahan satu baris:

# OpenAI
agent = Agent("openai:gpt-4o")

# Anthropic
agent = Agent("anthropic:claude-sonnet-4-20250514")

# Google Gemini
agent = Agent("google-gla:gemini-2.0-flash")

# Local Ollama
agent = Agent("ollama:llama3.1")

Segala hal lainnya, alat, output terstruktur, DI, tetap identik. Logika bisnis Anda tidak berubah saat Anda mengganti model.

Vonis: Desain agnostik model berarti Anda tidak pernah terkunci pada satu penyedia. Mulailah dengan OpenAI untuk kenyamanan, lakukan benchmark dengan Anthropic, dan gunakan Ollama untuk pengembangan lokal.

Streaming Respons

Untuk UI chat dan aplikasi real-time, streaming sangat penting. Pydantic AI mendukungnya sambil mempertahankan keamanan tipe:

from pydantic_ai import Agent
from pydantic import BaseModel

class AnalysisResult(BaseModel):
    summary: str
    sentiment: str
    confidence: float

agent = Agent("openai:gpt-4o", result_type=AnalysisResult)

async def stream_analysis(text: str):
    async with agent.run_stream(f"Analyze this text: {text}") as stream:
        async for partial in stream.stream_structured():
            # partial is a partially-validated AnalysisResult
            print(f"Streaming: {partial}")

        # Final result is fully validated
        result = await stream.get_output()
        print(f"Final: {result.summary} ({result.confidence:.0%} confident)")

Ini bekerja dengan indah bersama StreamingResponse milik FastAPI, ekosistem yang sama, pola yang sama. Dokumentasi agen Pydantic AI mencakup opsi streaming lanjutan termasuk streaming teks saja dengan stream_text().

Pydantic AI vs LangGraph vs OpenAI Agents SDK

Anda berada di sini, jadi Anda mungkin bertanya: "haruskah saya menggunakan Pydantic AI atau LangGraph?" Jawaban jujur: mereka memecahkan masalah yang berbeda, dan Anda mungkin menggunakan keduanya.

Tabel Perbandingan Fitur

Kapan Menggunakan Masing-Masing

Pilih Pydantic AI ketika Anda menginginkan kode agen yang bersih dan aman secara tipe. Ini ideal untuk tugas agen tunggal dengan alat (bot dukungan pelanggan, ekstraksi data, agen tinjauan kode) dan situasi di mana kemampuan pengujian menjadi penting. Jika tim Anda sudah menggunakan FastAPI dan Pydantic, kurva belajarnya hampir datar.

Pilih LangGraph ketika Anda memerlukan alur kerja multi-langkah yang kompleks dengan percabangan kondisional, persetujuan human-in-the-loop, dan manajemen status yang canggih. LangGraph unggul dalam mengorkestrasi banyak langkah, bukan kualitas agen individu. Untuk pendalaman, lihat perbandingan lengkap LangGraph vs CrewAI vs OpenAI Agents SDK kami.

Pilih OpenAI Agents SDK ketika Anda 100% menggunakan OpenAI, menginginkan setup sesederhana mungkin, dan tidak memerlukan dukungan multi-penyedia atau DI.

Pola Kombinasi

Inilah yang sebenarnya dilakukan oleh tim berpengalaman: gunakan Pydantic AI untuk agen individu (kode bersih, dapat diuji, output bertipe) dan LangGraph untuk orkestrasi antar agen (perutean, mesin status, logika kondisional). Mereka tidak bersaing, mereka adalah lapisan yang saling melengkapi.

# Pydantic AI agent -- clean, testable, type-safe
support_agent = Agent("openai:gpt-4o", result_type=SupportResponse, deps_type=SupportDeps)

# LangGraph graph -- orchestrates when to call which agent
graph = StateGraph(SupportState)
graph.add_node("classify", classify_intent)
graph.add_node("support", lambda state: support_agent.run_sync(state["query"]))
graph.add_node("escalate", escalate_to_human)

Vonis: Pilih Pydantic AI untuk kode agen yang bersih dan dapat diuji. Pilih LangGraph untuk alur kerja multi-langkah yang kompleks. Keduanya tidak saling eksklusif.

Menguji Agen Anda dengan TestModel

Ini adalah bagian yang membedakan panduan pemula dari panduan produksi. Setiap codebase nyata membutuhkan tes, dan menguji agen sangatlah sulit; panggilan LLM lambat, mahal, dan non-deterministik. Pydantic AI menyediakan solusi: TestModel.

from pydantic_ai import Agent
from pydantic_ai.models.test import TestModel
from pydantic import BaseModel

class SupportResponse(BaseModel):
    answer: str
    confidence: float
    escalate: bool

agent = Agent("openai:gpt-4o", result_type=SupportResponse)

# In tests: swap the real model for TestModel
def test_support_agent():
    with agent.override(model=TestModel()):
        result = agent.run_sync("I need help with billing")
        # TestModel returns valid structured data matching your result_type
        assert isinstance(result.output, SupportResponse)
        assert isinstance(result.output.confidence, float)
        assert isinstance(result.output.escalate, bool)

TestModel menghasilkan data valid yang cocok dengan result_type Anda tanpa melakukan panggilan API apa pun. Biaya nol, deterministik, cepat. Dokumentasi pengujian Pydantic AI mencakup pola lanjutan seperti FunctionModel untuk respons kustom dan capture_run_messages untuk memeriksa panggilan alat.

Menguji Alat dan DI Secara Bersamaan

def test_order_lookup_tool():
    # Mock dependencies
    mock_deps = SupportDeps(
        customer_id="test-123",
        db_connection=MockDB(orders=[{"id": "ord-1", "status": "shipped"}])
    )

    with agent.override(model=TestModel()):
        result = agent.run_sync(
            "Where is my order?",
            deps=mock_deps
        )
        assert isinstance(result.output, SupportResponse)

Tidak ada panggilan API. Tidak ada tes yang flaky. Tidak ada biaya. Jalankan ini di CI/CD bersamaan dengan sisa suite tes Anda.

Ini adalah kesenjangan konten #1 di seluruh SERP. Tidak ada panduan Pydantic AI lain yang membahas pengujian. Jika Anda membangun agen untuk produksi, inilah yang Anda butuhkan.

Observabilitas, Integrasi Logfire dalam 5 Menit

Agen produksi membutuhkan observabilitas AI. Anda ingin melihat setiap panggilan LLM, pemanggilan alat, latensi, jumlah token, dan biaya. Pydantic AI terintegrasi secara native dengan Logfire, platform observabilitas tim Pydantic (dibangun di atas OpenTelemetry).

import logfire
from pydantic_ai import Agent

logfire.configure()  # Uses LOGFIRE_TOKEN env var
logfire.instrument_pydantic_ai()

agent = Agent("openai:gpt-4o", result_type=MovieReview)
# Every run is now traced automatically
result = agent.run_sync("Review Inception")

Tiga baris. Anda mendapatkan jejak lengkap yang menunjukkan: prompt yang dikirim, respons model, panggilan alat (jika ada), keberhasilan/kegagalan validasi, percobaan ulang, latensi, dan estimasi biaya. Jika Logfire bukan pilihan Anda, Langfuse adalah alternatif open-source yang solid dengan dukungan rekayasa konteks untuk melacak bagaimana prompt Anda berkembang.

FAQ

Apa itu Pydantic AI dan bagaimana bedanya dengan LangChain?

Pydantic AI adalah kerangka kerja agen aman tipe di mana hint tipe Python mendorong validasi, skema alat, dan injeksi dependensi. LangChain adalah kerangka kerja yang lebih besar yang berfokus pada penyambungan panggilan LLM. Perbedaan utamanya: Pydantic AI memvalidasi output di tingkat kerangka kerja dan menyediakan injeksi dependensi bawaan untuk kemampuan pengujian, sedangkan LangChain tidak melakukan keduanya secara default.

Bagaimana cara membangun agen AI aman tipe dengan Pydantic AI?

Definisikan BaseModel Pydantic untuk output Anda, berikan sebagai result_type ke Agent, dan panggil run_sync() atau run(). Agen mengembalikan instance model Anda yang telah divalidasi, bukan string mentah. Lihat bagian Output Terstruktur untuk contoh lengkap.

Haruskah saya menggunakan Pydantic AI atau LangGraph untuk agen produksi?

Gunakan Pydantic AI untuk agen individu di mana keamanan tipe, kemampuan pengujian, dan kode bersih menjadi penting. Gunakan LangGraph untuk mengorkestrasi alur kerja multi-langkah yang kompleks dengan perutean kondisional. Banyak tim menggunakan keduanya, agen Pydantic AI di dalam lapisan orkestrasi LangGraph.

Bagaimana Pydantic AI menangani pemanggilan alat dan injeksi dependensi?

Hiasi fungsi dengan @agent.tool dan Pydantic AI membaca hint tipenya untuk menghasilkan skema alat. Untuk DI, setel deps_type pada Agent dan terima RunContext[YourDeps] dalam alat. Dependensi runtime (koneksi DB, klien API) mengalir tanpa status global.

Bagaimana cara menambahkan streaming ke agen Pydantic AI?

Gunakan agent.run_stream() alih-alih agent.run(). Ini mengembalikan context manager async yang menghasilkan hasil parsial melalui stream_structured() atau stream_text(). Hasil akhir tetap divalidasi sepenuhnya terhadap result_type Anda.

Apakah Pydantic AI siap produksi pada tahun 2026?

Ya. Versi 1.0 diluncurkan pada September 2025 dengan komitmen stabilitas API. Ini didukung oleh tim Pydantic (pustaka Python paling banyak diunduh untuk validasi data) dan saat ini berada di v1.74.0 dengan pembaruan rutin.

Bisakah saya menggunakan Pydantic AI dengan Ollama dan model lokal?

Ya. Gunakan Agent("ollama:llama3.1") dan pastikan Ollama berjalan secara lokal. Instal ekstra penyedia ollama: pip install "pydantic-ai[ollama]". Output terstruktur dan alat bekerja sama seperti dengan penyedia cloud.

Bagaimana cara menguji agen Pydantic AI?

Gunakan TestModel, model mock yang menghasilkan data terstruktur valid yang cocok dengan result_type Anda tanpa panggilan API. Bungkus tes Anda dalam agent.override(model=TestModel()) dan jalankan asersi pada output. Lihat bagian Pengujian untuk contoh pytest lengkap.

Apakah Pydantic AI bekerja dengan FastAPI?

Sempurna. Mereka berbagi filosofi injeksi dependensi yang sama dan dibangun oleh tim yang sama. Anda dapat menggunakan agen Pydantic AI di dalam endpoint FastAPI, berbagi tipe dependensi di antara keduanya, dan streaming respons agen melalui StreamingResponse.

Apa perbedaan antara Pydantic AI dan OpenAI Agents SDK?

Pydantic AI bersifat agnostik model (bekerja dengan OpenAI, Anthropic, Gemini, Ollama, dll.), memiliki injeksi dependensi, TestModel untuk pengujian, dan validasi Pydantic. OpenAI Agents SDK lebih sederhana tetapi terkunci pada model OpenAI dan lacks DI serta pengujian bawaan. Pilih Pydantic AI untuk fleksibilitas; pilih OpenAI Agents SDK untuk setup khusus OpenAI yang paling sederhana.

Poin Penting dan Langkah Selanjutnya

Mulailah dengan agen kecil yang memiliki output terstruktur. Tambahkan alat. Tambahkan dependensi. Tulis tes dengan TestModel. Itulah jalur produksi, dan Anda kini memiliki semua yang dibutuhkan untuk menjalaninya.

Dokumentasi resmi Pydantic AI dan repositori GitHub sangat bagus untuk mendalami lebih lanjut. Kerangka kerja ini bergerak cepat, jadi tandai changelog.

Sumber

• Pydantic AI, Dokumentasi Resmi
• Dokumentasi Dependensi Pydantic AI
• Dokumentasi Pengujian Pydantic AI
• Pengumuman Rilis Pydantic AI v1
• Observabilitas AI Logfire
• pydantic/pydantic-ai, Repositori GitHub