Pydantic AI: Panduan Pemula dengan Contoh Praktis

Membangun aplikasi berbasis AI sering kali menghasilkan output tidak terstruktur, ketidaksesuaian tipe, dan masalah keandalan di produksi. Pendekatan tradisional untuk mengintegrasikan LLM ke dalam aplikasi Python kurang memiliki struktur dan validasi yang dibutuhkan untuk sistem produksi. Pydantic AI mengatasinya dengan menggabungkan validasi data Pydantic dengan kerangka kerja agen untuk interaksi LLM.

Dalam tutorial ini, Anda akan mempelajari cara membuat agen AI terstruktur yang menghasilkan output tervalidasi dan menjaga keamanan tipe. Kita akan membahas penyiapan agen dengan system prompt, membangun fungsi tools yang dapat dipanggil LLM selama percakapan, dan menerapkan validasi output terstruktur. Anda juga akan menemukan cara mengelola dependensi di seluruh komponen agen dan melakukan streaming respons untuk aplikasi real-time. Pada akhirnya, Anda akan mendapatkan pengalaman langsung membangun aplikasi AI yang menangani alur kerja kompleks.

Jika Anda mencari kursus praktik membangun sistem AI agen, saya merekomendasikan kursus Building Multi-Agent Systems with LangGraph. 

Apa itu Pydantic AI?

Pydantic AI adalah kerangka kerja agen Python yang menghadirkan struktur dan keamanan tipe ke aplikasi LLM. Berbeda dengan integrasi LLM dasar yang mengembalikan teks mentah, Pydantic AI memperlakukan interaksi AI sebagai percakapan terstruktur dengan input dan output tervalidasi, sehingga lebih mudah membangun aplikasi yang andal.

Fitur dan manfaat utama:

• Validasi output terstruktur — Respons AI Anda otomatis sesuai dengan model Pydantic, mencegah kesalahan parsing dan memastikan konsistensi data
• Function tools — LLM dapat memanggil fungsi Python Anda selama percakapan, memberi akses ke data nyata dan komputasi
• Keamanan tipe — Dukungan typing penuh berarti lebih sedikit error saat runtime dan bantuan IDE yang lebih baik saat membangun alur kerja AI kompleks
• System prompts — Tentukan instruksi yang jelas untuk agen AI Anda yang konsisten di semua interaksi
• Dependency injection — Bagikan konteks, koneksi basis data, dan preferensi pengguna di seluruh komponen agen secara rapi
• Mode eksekusi beragam — Jalankan agen secara sinkron, asinkron, atau lakukan streaming respons secara real-time sesuai kebutuhan
• Dapat digunakan kembali — Buat agen sekali dan gunakan kembali di seluruh aplikasi Anda, mirip dengan router FastAPI

Pendekatan ini mengubah AI dari generasi teks yang tidak terduga menjadi interaksi bertipe yang andal dan menyatu secara alami dengan aplikasi Python yang ada. Alih-alih bergulat dengan rekayasa prompt dan parsing output, Anda dapat fokus membangun fungsionalitas yang benar-benar dibutuhkan pengguna.

Prasyarat

Sebelum masuk ke tutorial ini, Anda memerlukan beberapa hal:

Pengetahuan yang diperlukan:

• Dasar-dasar Python : Kuasai penggunaan class dan function
• Dasar-dasar pemrograman asinkron di Python
• Dasar-dasar Pydantic : Pahami model, validasi field, dan anotasi tipe
• Keakraban dengan LLM :  Pengetahuan dasar tentang cara kerja model bahasa dan apa itu prompt

Bermanfaat namun tidak wajib:

• Konsep agen :  Sedikit pemahaman tentang agen AI dan pemanggilan tool, meskipun ini akan kita bahas

Kebutuhan setup:

• Python 3.9 atau lebih baru
• Kunci API OpenAI dan Anthropic
• Kemampuan dasar terminal/command line untuk instalasi paket

Jika Anda baru mengenal Pydantic, dokumentasi resminya membahas dasar-dasarnya dengan baik. Untuk dasar-dasar LLM, panduan pengantar ChatGPT atau model serupa akan memberi Anda latar belakang yang cukup untuk mengikuti.

Mulai Menggunakan Pydantic AI

Sepanjang tutorial ini, kita akan membangun agen analisis data yang membantu memahami performa penjualan di berbagai wilayah dan produk. Agen ini akan dimulai sederhana dan menjadi lebih canggih saat kita menambahkan fitur seperti tools kustom, output terstruktur, dan kemampuan streaming.

Instalasi dan penyiapan

Sebelum masuk ke kode, mari instal Pydantic AI dan siapkan lingkungan kita:

pip install pydantic-ai

Anda juga memerlukan kunci API OpenAI dan Anthropic. Setel sebagai variabel lingkungan:

export OPENAI_API_KEY="your-api-key-here"export ANTHROPIC_API_KEY="your-api-key-here"

> Kita akan menggunakan model OpenAI dan Anthropic karena ada beberapa fitur di Pydantic AI yang didukung di salah satunya tetapi tidak di yang lain.

Untuk contoh analisis data, kita juga akan menggunakan pandas untuk manipulasi data:

pip install pandas

Membuat agen pertama Anda

Mari mulai dengan agen sesederhana mungkin — yang dapat menjawab pertanyaan dasar tentang data penjualan. Di Pydantic AI, agen adalah antarmuka utama Anda untuk interaksi LLM (jalankan kode berikut dalam skrip Python):

from pydantic_ai import Agent# Create a basic sales analysis agentsales_agent = Agent(   'openai:gpt-4o',   system_prompt=(       "You are a data analyst specializing in sales performance. "       "Provide clear, actionable insights based on the data provided."   ))# Run the agent with a simple questionresult = sales_agent.run_sync("What are the key metrics I should track for sales performance? Answer in two sentences.")print(result.output)

Output:

Key metrics to track for sales performance include conversion rate, which measures the percentage of leads that result in sales, and average deal size, indicating the average revenue earned per transaction. Additionally, monitoring customer acquisition cost (CAC) and customer lifetime value (CLV) helps evaluate the efficiency and profitability of sales efforts.

Ini membuat agen yang memahami perannya sebagai analis penjualan dan dapat memberikan saran yang relevan. system_prompt memberikan konteks kepada LLM tentang jenis respons yang Anda inginkan, sementara run_sync() mengeksekusi agen dan mengembalikan hasil.

Di sini, fungsi run_sync() hanya berfungsi dalam skrip Python. Untuk menjalankan agen di Jupyter Notebook, Anda dapat menggunakan sintaks berikut:

result = await agent.run("...")print(result.output)

Mengganti LLM dan pengaturannya

Pydantic AI mendukung banyak penyedia LLM dan memungkinkan Anda menyesuaikan perilaku model. Berikut cara bereksperimen dengan berbagai opsi:

# Creating agents with different modelsclaude_agent = Agent('anthropic:claude-3-5-sonnet-20241022', system_prompt="You are a sales analyst.")gpt_mini_agent = Agent('openai:gpt-4o-mini', system_prompt="You are a sales analyst.")

Setiap model menghadirkan kemampuan berbeda ke alur kerja analisis data Anda. Model Claude unggul dalam penalaran mendetail dan analisis kompleks, ideal saat Anda membutuhkan insight mendalam dari data penjualan. GPT-4o-mini menawarkan respons lebih cepat dan biaya lebih rendah, cocok untuk pertanyaan cepat atau saat memproses volume kueri besar.

Selain memilih model berbeda, Anda dapat menyetel perilakunya menggunakan pengaturan model:

# Add model-specific settingsconfigured_agent = Agent(   'openai:gpt-4o',   system_prompt="You are a sales analyst.",   model_settings={       'temperature': 0.3,  # More focused, less creative responses       'max_tokens': 500,   # Limit response length   })

Pengaturan model yang dapat Anda sesuaikan:

• temperature — Mengendalikan kreativitas (0.0 = fokus, 1.0 = kreatif)
• max_tokens — Membatasi panjang respons
• top_p — Alternatif untuk temperature guna mengendalikan keacakan

Untuk tugas analisis data, nilai temperature yang lebih rendah (0,1–0,3) biasanya lebih baik karena Anda menginginkan respons yang konsisten dan faktual, bukan interpretasi kreatif. Menyetel max_tokens membantu mengontrol panjang respons, berguna saat Anda membutuhkan ringkasan singkat atau memiliki kekhawatiran biaya API.

Menggunakan Tools dalam Agen

Sejauh ini, agen analisis penjualan kita hanya dapat bekerja dengan informasi yang kita berikan dalam prompt. Namun, analisis data nyata sering kali memerlukan akses ke informasi eksternal, menjalankan perhitungan, atau menghubungkan ke sistem bisnis. Di sinilah tools berperan — tools memberi agen Anda kemampuan untuk mengambil tindakan dan mengumpulkan informasi selama percakapan.

Tools bawaan

Tools bawaan adalah fungsi siap pakai yang disediakan oleh penyedia LLM. Pydantic AI mendukung web search dan tools eksekusi kode yang berjalan langsung pada infrastruktur penyedia.

Mari mulai dengan web search, yang cocok untuk mendapatkan informasi pasar terkini:

from pydantic_ai import Agent, WebSearchTool# Create an agent with web search abilitiesmarket_research_agent = Agent(   'anthropic:claude-3-5-sonnet-20241022',   builtin_tools=[WebSearchTool()],   system_prompt=(       "You are a sales analyst. Use web search to find current information. "       "Keep responses to 3-4 sentences maximum."   ))# Get current market informationresult = market_research_agent.run_sync(   "Search for 2025 laptop sales trends and average selling prices. Give me the main trends.")print(result.output)

Let me search for current laptop sales trends.Based on the search results, here are the key laptop market trends for 2025:…

Ini mengubah analisis data Anda dari bekerja dengan informasi lama menjadi memasukkan data pasar real-time. Alih-alih menganalisis data saja, agen Anda kini dapat membandingkan performa perusahaan dengan tren industri saat ini.

Sekarang mari tambahkan eksekusi kode untuk analisis matematis dan pemrosesan data:

from pydantic_ai import Agent, CodeExecutionTool# Agent that can run calculations and data analysiscalculation_agent = Agent(   'anthropic:claude-sonnet-4-0',   builtin_tools=[CodeExecutionTool()],   system_prompt=(       "You are a data analyst. Use code to perform calculations and create visualizations. "       "Show your work and provide clear explanations."   ))# Analyze sales data with calculationsresult = calculation_agent.run_sync("""I have sales data for Q1 2025:- North region: 150 laptops at $1,500 each, 320 phones at $500 each- South region: 89 laptops at $1,500 each, 245 phones at $500 each - East region: 201 laptops at $1,500 each, 180 phones at $500 each- West region: 167 laptops at $1,500 each, 290 phones at $500 eachCalculate total revenue by region and create a simple chart showing the results.""")print(result.output)```plaintext## SummaryBased on the Q1 2025 sales data analysis, here are the key findings:**Total Revenue by Region:**- **West Region**: $395,500 (highest)- **East Region**: $391,500- **North Region**: $385,000- **South Region**: $256,000 (lowest)

Eksekusi kode melampaui respons teks sederhana menjadi analisis komputasional nyata. Agen Anda kini dapat melakukan perhitungan kompleks, membuat visualisasi, dan memproses data yang mustahil dilakukan hanya melalui percakapan. Objek hasil berisi analisis agen dan file yang dihasilkan selama eksekusi kode, yang dapat Anda unduh untuk penggunaan lebih lanjut.

Menulis tools kustom

Meskipun tools bawaan berguna, Anda sering membutuhkan tools kustom yang bekerja dengan sistem bisnis spesifik Anda. Tools kustom adalah fungsi Python yang dapat dipanggil agen Anda selama percakapan.

Mari buat tools yang menghitung metrik penjualan umum:

from pydantic_ai import Agent# Create an agent with custom business toolssales_agent = Agent(   'anthropic:claude-sonnet-4-0',   system_prompt=(       "You are a sales analyst. Use tools to calculate metrics and analyze business data. "       "Give concise answers in 3-4 sentences maximum."   ))@sales_agent.tool_plaindef calculate_conversion_rate(leads: int, sales: int) -> str:   """Calculate conversion rate from leads to sales."""   if leads == 0:       return "Cannot calculate conversion rate: no leads provided"     conversion_rate = (sales / leads) * 100   return f"Conversion rate: {conversion_rate:.2f}% ({sales} sales from {leads} leads)"@sales_agent.tool_plaindef calculate_average_order_value(total_revenue: float, total_orders: int) -> str:   """Calculate average order value."""   if total_orders == 0:       return "Cannot calculate AOV: no orders provided"     aov = total_revenue / total_orders   return f"Average Order Value: ${aov:.2f} (${total_revenue:,.0f} revenue from {total_orders} orders)"# Use the custom toolsresult = sales_agent.run_sync(   "Calculate conversion rate for 500 leads that resulted in 75 sales, and AOV for $180,000 revenue from 120 orders")print(result.output)

Your conversion rate is 15.00%, meaning you're successfully converting 75 out of every 500 leads into sales. The average order value is $1,500.00, indicating strong revenue per transaction. These metrics suggest effective sales processes with high-value customers, though there's room to improve lead conversion rates.

Tools kustom ini menangani perhitungan penjualan spesifik yang sering digunakan bisnis Anda. Tool conversion rate membantu mengukur kinerja pemasaran, sementara tool average order value melacak pola belanja pelanggan. Tools kustom menghubungkan agen Anda dengan logika bisnis dan sistem spesifik Anda.

Untuk pola tool yang lebih lanjut, termasuk dependency injection dan penanganan error, lihat dokumentasi tools lengkap.

Menggunakan Output Terstruktur

Sejauh ini agen kita mengembalikan respons teks biasa, yang cocok untuk eksplorasi namun menimbulkan masalah di aplikasi produksi. Saat Anda perlu memproses respons agen secara terprogram, mengurai poin data tertentu, atau mengintegrasikan output AI dengan sistem lain, Anda memerlukan struktur yang terjamin.

Misalnya Anda ingin menganalisis data penjualan dan selalu mendapatkan metrik tertentu. Dengan teks biasa, AI bisa mengembalikan format berbeda setiap saat. Dengan output terstruktur, Anda menentukan persis apa yang Anda inginkan:

from pydantic import BaseModelfrom pydantic_ai import Agentclass SalesInsight(BaseModel):   total_revenue: float   best_performing_region: str   worst_performing_region: str   recommendation: str# Create an agent that returns structured analysisanalysis_agent = Agent(   'anthropic:claude-sonnet-4-0',   output_type=SalesInsight,   system_prompt="Analyze sales data and provide structured insights with clear recommendations.")# Get structured analysisresult = analysis_agent.run_sync("""Q1 2025 sales data:- North: $385,000 revenue (470 units)- South: $256,000 revenue (334 units) - East: $391,500 revenue (381 units)- West: $395,500 revenue (457 units)Analyze this data and provide insights.""")print(f"Total Revenue: ${result.output.total_revenue:,.0f}")print(f"Best Region: {result.output.best_performing_region}")print(f"Recommendation: {result.output.recommendation}")

Total Revenue: $1,428,000Best Region: WestRecommendation: Focus on improving South region performance through targeted marketing and sales training, as it significantly underperforms with only $256,000 revenue. The West region's success ($395,500) should be analyzed and replicated across other regions. Additionally, investigate why East region has the lowest average selling price per unit ($1,028) compared to West's highest ($865) - there may be pricing strategy opportunities.

Perhatikan parameter output_type=SalesInsight. Ini memberi tahu agen bahwa ia harus mengembalikan objek SalesInsight dengan tepat empat field tersebut. Tidak lebih, tidak kurang. Hasilnya kembali sebagai result.output yang otomatis divalidasi dan memiliki tipe.

Output terstruktur bekerja dengan mengonversi model Pydantic Anda menjadi skema JSON yang diikuti LLM. AI tidak bisa menyimpang dari struktur Anda — jika mencoba mengembalikan sesuatu yang lain, Pydantic AI akan memintanya untuk mencoba lagi.

Untuk skenario analisis yang lebih kompleks, Anda dapat menumpuk model dan menggunakan list:

from typing import Listfrom pydantic import BaseModelclass RegionalMetrics(BaseModel):   region: str   revenue: float   units_sold: int   average_price: float   performance_rating: str  # "excellent", "good", "needs_improvement"class ComprehensiveAnalysis(BaseModel):   total_revenue: float   total_units: int   regional_breakdown: List[RegionalMetrics]   top_performer: str   areas_for_improvement: List[str]   quarterly_grade: str# Agent with detailed structured outputdetailed_agent = Agent(   'anthropic:claude-sonnet-4-0',   output_type=ComprehensiveAnalysis,   system_prompt=(       "Provide comprehensive sales analysis with detailed regional metrics. "       "Rate each region's performance and give an overall quarterly grade (A-F)."   ))result = detailed_agent.run_sync("""Analyze Q1 2025 performance:- North: $385k revenue, 470 units- South: $256k revenue, 334 units- East: $391.5k revenue, 381 units - West: $395.5k revenue, 457 units""")# Access structured datafor region in result.output.regional_breakdown:   print(f"{region.region}: {region.performance_rating} (${region.average_price:.2f} avg price)")print(f"Quarterly Grade: {result.output.quarterly_grade}")

North: B ($819.15 avg price)South: C ($766.47 avg price)East: A ($1027.56 avg price)West: A- ($865.43 avg price)Quarterly Grade: B+

Pendekatan ini mengubah AI dari generasi teks yang tidak terduga menjadi pemrosesan data yang andal. Anda dapat menyimpan tiap metrik regional ke basis data, memicu peringatan berdasarkan peringkat performa, atau membuat dasbor eksekutif secara otomatis. Tanpa regex parsing, tanpa menangani format respons berbeda — hanya data bersih dan tervalidasi setiap saat.

Parameter output_type menerima model Pydantic apa pun, dataclass Python, TypedDict, atau bahkan tipe sederhana seperti int atau list[str]. Untuk alur kerja analisis data, ini berarti Anda dapat membangun pipeline andal di mana analisis AI langsung memberi makan ke dalam sistem bisnis yang sudah ada.

Pesan dan Riwayat Chat di Agen Pydantic

Saat bekerja dengan agen analisis data, Anda sering membutuhkan percakapan yang membentang di beberapa interaksi. Mungkin Anda mulai dengan menanyakan tren penjualan, kemudian ingin menggali lebih dalam wilayah tertentu, atau membandingkan periode waktu berbeda. Pesan dan riwayat chat memungkinkan Anda mempertahankan konteks di seluruh percakapan ini.

Mengakses riwayat pesan

Setiap kali Anda menjalankan agen, Pydantic AI melacak seluruh percakapan. Anda dapat mengakses riwayat ini untuk memahami apa yang terjadi atau melanjutkan percakapan nanti:

from pydantic_ai import Agent# Create our sales analysis agentsales_agent = Agent(   'anthropic:claude-sonnet-4-0',   system_prompt="You are a sales analyst. Provide clear, concise analysis.")# First questionresult1 = sales_agent.run_sync("What are the main KPIs I should track for Q1 2025 sales?")print(result1.output)# Access the conversation historyall_messages = result1.all_messages()print(f"Total messages in conversation: {len(all_messages)}")# Just the new messages from this runnew_messages = result1.new_messages()print(f"New messages from this run: {len(new_messages)}")

Here are the essential KPIs to track for Q1 2025 sales:...Total messages in conversation: 2New messages from this run: 2

Metode all_messages() memberi Anda semuanya - system prompt, pertanyaan pengguna, dan respons agen. Metode new_messages() hanya mengembalikan apa yang terjadi pada run saat ini. Ini berguna saat Anda membangun percakapan lebih panjang dan ingin melacak apa yang berubah.

Melanjutkan percakapan dengan riwayat pesan

Untuk melanjutkan percakapan sebelumnya, teruskan riwayat pesan ke run agen berikutnya. Ini memungkinkan agen mengingat apa yang Anda diskusikan sebelumnya:

# Continue the conversation from where we left offresult2 = sales_agent.run_sync(   "How should I calculate conversion rates for each of those KPIs?",   message_history=result1.all_messages())print(result2.output)# The agent now has context from both interactionsprint(f"Full conversation length: {len(result2.all_messages())}")# Ask a follow-up that references the entire conversationresult3 = sales_agent.run_sync(   "Which of these metrics would be most important for a monthly executive report?",   message_history=result2.all_messages())print(result3.output)

Setiap run baru membangun konteks sebelumnya. Agen mengingat bukan hanya pertanyaan Anda, tetapi juga responsnya sendiri sebelumnya, sehingga tercipta percakapan analitis yang koheren.

Menyimpan dan memuat pesan ke JSON

Untuk penyimpanan jangka panjang atau berbagi percakapan antar sistem, Anda dapat melakukan serialisasi riwayat pesan ke JSON:

import json# Get the conversation as JSONconversation_json = result3.all_messages_json()# Save to filewith open('sales_analysis_conversation.json', 'w') as f:   f.write(conversation_json.decode('utf-8'))print("Conversation saved to JSON file")# Load it back laterwith open('sales_analysis_conversation.json', 'r') as f:   loaded_conversation = f.read()# You can now use this loaded conversation in a new agent run# (Note: You'd need to convert back from JSON to message objects for actual use)print(f"Loaded conversation size: {len(loaded_conversation)} characters")

Metode all_messages_json() mengembalikan percakapan sebagai byte JSON, ideal untuk menyimpan ke database, mengirim melalui API, atau mengarsipkan sesi analisis. Ada juga new_messages_json() jika Anda hanya ingin menyimpan bagian percakapan terbaru.

Pendekatan ini memungkinkan Anda membangun alur kerja analitis yang persisten. Anda bisa menyimpan tiap sesi analisis klien, melanjutkan investigasi data kompleks selama beberapa hari, atau berbagi konteks percakapan antar anggota tim yang mengerjakan analisis yang sama.

Bekerja dengan Gambar dan Dokumen

Analisis data nyata sering melibatkan lebih dari sekadar teks dan angka. Anda mungkin perlu menganalisis bagan dari laporan, mengekstrak data dari PDF, atau menafsirkan grafik dan visualisasi. Pydantic AI mendukung input gambar dan dokumen, memungkinkan agen Anda bekerja langsung dengan sumber data kaya ini.

Menganalisis gambar dari URL

Saat Anda memiliki bagan, grafik, atau visualisasi yang dihosting online, Anda dapat menunjukkannya langsung ke agen Anda:

from pydantic_ai import Agent, ImageUrl# Create an agent that can analyze visual datavisual_agent = Agent(   'anthropic:claude-sonnet-4-0',   system_prompt="You are a data analyst who can interpret charts, graphs, and business documents.")# Analyze a sales chart from a URLresult = visual_agent.run_sync([   "What are the main trends shown in this sales chart? Give me 3 key takeaways.",   ImageUrl(url='https://example.com/q1-sales-chart.png')])print(result.output)

Agen dapat mengidentifikasi jenis bagan, membaca nilai dari sumbu, melihat tren, dan memberikan insight bisnis seperti halnya analis manusia saat melihat visualisasi yang sama.

Bekerja dengan gambar lokal

Untuk gambar yang disimpan secara lokal — seperti tangkapan layar dari alat BI Anda atau bagan yang diekspor dari Excel — gunakan BinaryContent:

from pathlib import Pathfrom pydantic_ai import Agent, BinaryContent# Load a local sales dashboard screenshotdashboard_path = Path('sales_dashboard_jan_2025.png')result = visual_agent.run_sync([   "Analyze this sales dashboard. What metrics need attention based on what you see?",   BinaryContent(       data=dashboard_path.read_bytes(),       media_type='image/png'   )])print(result.output)

Pendekatan ini sangat cocok untuk alur kerja pelaporan otomatis. Anda dapat mengambil screenshot dasbor secara terprogram, lalu meminta AI memberikan analisis tertulis untuk melengkapi visual.

Menganalisis dokumen dari URL

Banyak dokumen bisnis dibagikan melalui URL — laporan di intranet perusahaan, PDF di cloud storage, atau makalah riset publik yang menginformasikan analisis Anda:

from pydantic_ai import Agent, DocumentUrl# Create an agent for document analysisdoc_agent = Agent(   'anthropic:claude-sonnet-4-0',   system_prompt="Extract and summarize business-relevant insights from documents.")# Analyze a quarterly report PDFresult = doc_agent.run_sync([   "Read this quarterly earnings report and summarize the revenue trends and outlook.",   DocumentUrl(url='https://company.com/reports/q1-2025-earnings.pdf')])print(result.output)

Agen dapat membaca seluruh dokumen, mengekstrak poin data relevan, dan memberikan ringkasan yang biasanya memerlukan waktu lebih lama jika dilakukan manusia.

Memproses dokumen lokal

Untuk dokumen di sistem lokal Anda — seperti laporan yang diekspor, kontrak, atau presentasi internal — gunakan BinaryContent:

from pathlib import Pathfrom pydantic_ai import Agent, BinaryContent# Load a local Excel export saved as PDFreport_path = Path('monthly_sales_analysis_jan_2025.pdf')result = doc_agent.run_sync([   "Extract the key performance metrics from this monthly sales report and identify any concerning trends.",   BinaryContent(       data=report_path.read_bytes(),       media_type='application/pdf'   )])print(result.output)

Ini membuka kemungkinan otomatisasi yang kuat. Anda dapat memproses tumpukan laporan, mengekstrak data dari invoice, atau menganalisis ketentuan kontrak — semua tugas yang biasanya memerlukan peninjauan manual.

Catatan penting:

Model yang berbeda mendukung format file yang berbeda. Sebagian besar menangani format gambar umum (PNG, JPEG) dan PDF, tetapi periksa dokumentasi model Anda untuk detail spesifik. Beberapa model seperti Vertex AI milik Google dapat mengakses URL cloud storage secara langsung, sementara yang lain mengunduh kontennya terlebih dahulu.

Untuk alur kerja analisis data, kemampuan multimodal ini menjembatani kesenjangan antara laporan visual Anda dan insight bertenaga AI, sehingga memungkinkan otomatisasi analisis atas berbagai dokumen bisnis yang Anda gunakan setiap hari.

Mengaktifkan Streaming di Pydantic AI

Saat mengerjakan tugas analisis data yang kompleks, Anda ingin melihat hasil saat dihasilkan alih-alih menunggu respons lengkap. Streaming memungkinkan pengguna menyaksikan analisis berlangsung secara real-time, yang bernilai saat menanyakan pertanyaan rinci tentang performa penjualan.

Pydantic AI menyediakan streaming bawaan melalui metode run_stream(). Begini cara kerjanya:

import asynciofrom pydantic_ai import Agent# Create our sales analysis agentsales_agent = Agent(   'anthropic:claude-sonnet-4-0',   system_prompt=(       "You are a data analyst specializing in sales performance. "       "Provide detailed, actionable insights based on the data provided."   ))async def demo_streaming():   question = """   Analyze this sales scenario: Our company sold 1,200 laptops and 2,300 phones   last quarter across 4 regions. Laptops average $1,500 each, phones $500 each.   What are the key insights and recommendations?   """     async with sales_agent.run_stream(question) as result:       async for text in result.stream_text():           print(text, end='', flush=True)# Run the streaming analysisasyncio.run(demo_streaming())

Memahami sintaks streaming:

async with membuat koneksi ke LLM yang tetap terbuka saat menerima potongan teks. Anggap seperti membuka panggilan telepon - Anda perlu membangun koneksi, melakukan percakapan, lalu menutupnya dengan benar.

Loop async for memproses tiap potongan teks saat tiba. Perhatikan bahwa stream_text() meregenerasi teks lengkap setiap kali - jadi Anda mendapat "Hello", lalu "Hello world", kemudian "Hello world, how". Ini memberi konteks penuh tetapi bisa repetitif untuk tampilan.

Mengapa async dan asyncio bekerja bersama:

Saat Anda mengajukan pertanyaan ke LLM, dibutuhkan waktu untuk menghasilkan respons — biasanya 3–10 detik. Selama waktu ini, model mengirimkan potongan teks kecil setiap 50–200 milidetik.

Tanpa async, program Anda akan membeku menunggu setiap potongan. Dengan async, event loop Python (sistem yang mengelola periode menunggu ini) dapat beralih antar tugas. Ini berarti program Anda tetap responsif dan bahkan dapat menjalankan beberapa percakapan sekaligus.

asyncio.run() adalah yang memulai seluruh proses - ia membuat event loop yang mengoordinasikan semuanya. Saat Anda memanggil asyncio.run(demo_streaming()), itu menyiapkan lingkungan tempat fungsi async Anda dapat jeda dan dilanjutkan sesuai kebutuhan saat menunggu respons LLM.

Sekarang mari buat fungsi yang dapat digunakan kembali yang hanya menampilkan delta teks baru untuk pengalaman streaming yang lebih baik:

from pydantic_ai.messages import PartDeltaEvent, TextPartDeltaasync def stream_agent_response(agent: Agent, task: str):   """   Stream a response from any Pydantic AI agent showing just new text deltas.   """   async def event_handler(ctx, event_stream):       async for event in event_stream:           if isinstance(event, PartDeltaEvent) and isinstance(               event.delta, TextPartDelta           ):               print(event.delta.content_delta, end="", flush=True)   # Use agent.run() with event_stream_handler for proper streaming   result = await agent.run(task, event_stream_handler=event_handler)   print()  # Add a newline when streaming is complete   return result# Usage exampleresponse = asyncio.run(stream_agent_response(   sales_agent,   "What are the top 3 metrics I should track for quarterly sales analysis?"))

Uraian fungsi streaming:

Fungsi stream_agent_response() menciptakan pengalaman streaming yang lebih natural dengan hanya menampilkan teks baru saat tiba. Begini cara kerjanya:

1. Penyiapan event handler: Fungsi event_handler() di dalamnya mendengarkan event spesifik selama pemrosesan agen. Ia memfilter PartDeltaEvent dengan TextPartDelta - ini merepresentasikan potongan teks baru yang sedang dihasilkan.
2. Delta konten: Alih-alih mendapatkan teks yang diregenerasi penuh tiap kali, event.delta.content_delta memberi kita hanya kata atau karakter baru. Ini menciptakan efek mesin tik di mana Anda melihat respons ditulis kata demi kata.
3. Eksekusi agen: Kita menggunakan agent.run() dengan parameter event_stream_handler. Ini memberi tahu agen untuk memanggil handler kustom kita untuk tiap event streaming, memberi kontrol terperinci atas apa yang ditampilkan.
4. Output real-time: print(event.delta.content_delta, end="", flush=True) menampilkan tiap potongan baru seketika tanpa menambah baris baru, menciptakan aliran teks yang mulus.

Pendekatan ini memberi nuansa alami menyaksikan AI memikirkan analisis secara real-time, alih-alih menunggu respons lengkap atau melihat teks yang diregenerasi berulang. Kita akan menggunakan fungsi ini di bagian berikut untuk menampilkan respons streaming di seluruh contoh analisis data kita.

Kesimpulan

Sepanjang tutorial ini, Anda telah membangun pemahaman lengkap tentang Pydantic AI melalui contoh analisis data praktis. Anda telah mempelajari cara membuat agen dengan system prompt, menambahkan tools bawaan dan kustom, menstrukturkan output dengan model Pydantic, dan melakukan streaming respons untuk umpan balik real-time. Komponen-komponen ini berpadu menciptakan sistem AI yang lebih mirip mitra analitis daripada sekadar chatbot.

Aplikasinya jauh melampaui contoh analisis penjualan yang kita bahas. Kini Anda dapat membangun agen AI yang membaca sumber data spesifik Anda, mengikuti aturan bisnis Anda, dan mengembalikan hasil dalam format yang sesuai dengan sistem yang sudah ada. Baik Anda mengotomatiskan pembuatan laporan, menganalisis umpan balik pelanggan, atau memproses data keuangan, Pydantic AI memberi struktur dan keandalan yang dibutuhkan untuk aplikasi produksi.

Jika Anda tertarik untuk membangun sistem multi-agen dengan LangGraph, jangan lewatkan kursus praktik kami.