Pydantic AI: Ο Οδηγός Παραγωγής (Πέρα από το Hello World)

Pydantic AI: Ο Οδηγός Παραγωγής (Πέρα από το Hello World)

Οι ακατέργαστες έξοδοι LLM καταστρέφουν τις εφαρμογές. Ζητάτε JSON, παίρνετε markdown. Ζητάτε έναν αριθμό μεταξύ 1 και 10, παίρνετε «Βεβαίως! Ορίστε ένας αριθμός: επτά». Αν έχετε φτιάξει κάτι πραγματικό με LLM APIs, έχετε γράψει αμυντικό κώδικα parsing που σας κάνει να αμφισβητείτε τις επαγγελματικές σας επιλογές. Το Pydantic AI διορθώνει αυτό το πρόβλημα· είναι το type-safe agent framework που δημιουργήθηκε από την ίδια ομάδα πίσω από τα Pydantic και FastAPI. Σκεφτείτε το ως «FastAPI για AI agents»: ορίζετε τι θέλετε με type hints της Python και το framework αναλαμβάνει την επικύρωση, τις επαναπροσπάθειες και την κλήση εργαλείων.

Αυτός ο οδηγός Pydantic AI απευθύνεται σε developers που έχουν ήδη εκτελέσει την πρώτη τους κλήση LLM και θέλουν μοτίβα παραγωγής: δομημένες εξόδους που δεν καταρρέουν, injection εξαρτήσεων για ελέγξιμους agents και εργαλεία πραγματικού κόσμου πέρα από τα APIs καιρού. Στο τέλος, θα έχετε λειτουργικούς agents με εργαλεία, DI, streaming και tests.

Pydantic AI με μια ματιά

Τα κορυφαία χαρακτηριστικά είναι οι δομημένες έξοδοι (επικυρωμένες με μοντέλα Pydantic), το injection εξαρτήσεων (όπως το Depends του FastAPI) και το TestModel (mock LLM για δοκιμές χωρίς κλήσεις API). Αν έρχεστε από το LangChain και αναρωτιέστε «υπάρχει κάτι πιο καθαρό;», πιθανότατα αυτό είναι.

Εγκατάσταση και Πρώτος Agent

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

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

Ο πρώτος σας agent σε 5 γραμμές:

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"

Τέλεια. Το Agent τυλίγει το μοντέλο, το run_sync στέλνει ένα prompt και επιστρέφει ένα αποτέλεσμα. Το result.output είναι εδώ μια απλή συμβολοσειρά, αλλά αυτό πρόκειται να αλλάξει.

Δομημένες Έξοδοι, Γιατί Υπάρχει το Pydantic AI

Αυτό είναι το βασικό χαρακτηριστικό. Αντί να παίρνετε πίσω μια συμβολοσειρά από το LLM και να ελπίζετε ότι είναι valid JSON, ορίζετε ένα μοντέλο Pydantic και ο agent επιστρέφει ένα επικυρωμένο αντικείμενο Python.

Πριν: Ακατέργαστη Έξοδος LLM

# 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.

Μετά: Δομημένη με 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)

Η διαφορά είναι night and day. Το result.output είναι ένα πραγματικό αντικείμενο MovieReview. Αν το LLM επιστρέψει rating: "eight" αντί για rating: 8, η επικύρωση του Pydantic το εντοπίζει. Για μια βαθύτερη ματιά στο πώς λειτουργεί αυτό across different providers, δείτε τον οδηγό μας για δομημένες εξόδους across LLM providers.

Τι Συμβαίνει Όταν Αποτυγχάνει η Επικύρωση

Εδώ είναι το μέρος που κανένα άλλο tutorial δεν δείχνει: τι συμβαίνει όταν το LLM τα κάνει μαντάρα;

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")

Αυτός ο βρόχος επαναπροσπάθειας με feedback είναι το killer feature του Pydantic AI. Το LLM μαθαίνει από τα δικά του σφάλματα επικύρωσης. Δεν γράφετε λογική επαναπροσπάθειας, το framework την αναλαμβάνει.

Συμπέρασμα: Οι δομημένες έξοδοι είναι ο μοναδικός καλύτερος λόγος για να χρησιμοποιήσετε Pydantic AI αντί για ακατέργαστες κλήσεις API. Αν κάνετε parse LLM JSON χειροκίνητα, σταματήστε.

Εργαλεία και Κλήση Συναρτήσεων

Τα εργαλεία επιτρέπουν στον agent σας να καλεί συναρτήσεις Python για να πάρει πραγματικά δεδομένα. Αντί το LLM να παραισθάνεται γεγονότα, μπορεί να κάνει query στη βάση δεδομένων σας, να αναζητήσει στα έγγραφά σας ή να καλέσει ένα API.

Καταχώρηση Εργαλείου

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)

Ο decorator @agent.tool καταχωρεί τη συνάρτηση. Το Pydantic AI διαβάζει τα type hints και το docstring της συνάρτησης για να πει στο LLM τι κάνει το εργαλείο, ποια ορίσματα παίρνει και τι επιστρέφει. Χωρίς χειροκίνητη συγγραφή schema, τα type hints σας ΕΙΝΑΙ το schema. Για υπόβαθρο σχετικά με πώς λειτουργεί η κλήση συναρτήσεων LLM under the hood, έχουμε έναν αφιερωμένο οδηγό.

RunContext: Μετάδοση Δεδομένων στα Εργαλεία

Εδώ αποκλίνει το Pydantic AI από άλλα frameworks. Το RunContext σας επιτρέπει να περνάτε δεδομένα runtime (συνδέσεις βάσεων δεδομένων, πληροφορίες χρήστη, clients API) στα εργαλεία σας χωρίς global state.

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 δίνει πρόσβαση στο εργαλείο σε ό,τι περάσατε κατά το runtime. Το εργαλείο δεν κάνει import μιας global σύνδεσης βάσης δεδομένων, την receives. Αυτό είναι dependency injection και είναι αυτό που κάνει τους agents σας ελέγξιμους.

Ένα Παράδειγμα Εργαλείου Πραγματικού Κόσμου

@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)

Συμπέρασμα: Η κλήση εργαλείων στο Pydantic AI είναι πιο καθαρή από οποιοδήποτε άλλο framework χάρη στα type hints που κάνουν τη βαριά δουλειά. Γράφετε κανονικές συναρτήσεις Python με type annotations. Το framework καταλαβαίνει τα υπόλοιπα.

Injection Εξαρτήσεων, Το Χαρακτηριστικό που Ευχόταν να Είχε το LangChain

Αν έχετε χρησιμοποιήσει το Depends του FastAPI, ήδη καταλαβαίνετε το σύστημα DI του Pydantic AI. Αν όχι, ορίστε η σύντομη εκδοχή: αντί ο agent σας να προσπαθεί να αρπάξει ό,τι χρειάζεται (global συνδέσεις βάσεων δεδομένων, clients API, config), του τα δίνετε όλα κατά το runtime.

Ορισμός Εξαρτήσεων

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."
)

Χρήση Εξαρτήσεων στα Εργαλεία

@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)
)

Γιατί το DI Κάνει τους Agents σας Ελέγξιμους

Αυτό είναι το πραγματικό όφελος. Στο LangChain, θα περνούσατε context μέσω chain kwargs ή closures, δεν υπάρχει standard pattern. Στο Pydantic AI, η αντικατάσταση πραγματικών εξαρτήσεων με test doubles είναι τετριμμένη:

# 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

Χωρίς monkey-patching. Χωρίς mocking global imports. Απλώς περνάτε διαφορετικά deps.

Συμπέρασμα: Το dependency injection είναι ο λόγος που οι experienced Python developers προτιμούν το Pydantic AI. Είναι η επιρροή του FastAPI που φαίνεται.

Πάροχοι Μοντέλων, OpenAI, Anthropic, Gemini, Ollama

Το Pydantic AI είναι model-agnostic. Η αλλαγή παρόχων είναι μια αλλαγή μιας γραμμής:

# 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")

Όλα τα άλλα, εργαλεία, δομημένες έξοδοι, DI, παραμένουν ίδια. Η business logic σας δεν αλλάζει όταν αλλάζετε μοντέλα.

Συμπέρασμα: Ο model-agnostic σχεδιασμός σημαίνει ότι δεν είστε ποτέ locked into έναν πάροχο. Ξεκινήστε με OpenAI για ευκολία, κάντε benchmark με Anthropic και χρησιμοποιήστε Ollama για local development.

Streaming Απαντήσεις

Για chat UIs και real-time applications, το streaming είναι απαραίτητο. Το Pydantic AI το υποστηρίζει διατηρώντας παράλληλα την type safety:

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)")

Αυτό λειτουργεί άψογα με το StreamingResponse του FastAPI, ίδιο ecosystem, ίδια patterns. Τα docs των agents Pydantic AI καλύπτουν advanced streaming options συμπεριλαμβανομένου του text-only streaming με stream_text().

Pydantic AI vs LangGraph vs OpenAI Agents SDK

Είστε εδώ, οπότε πιθανότατα ρωτάτε: «θα πρέπει να χρησιμοποιήσω Pydantic AI ή LangGraph;». Ειλικρινής απάντηση: λύνουν διαφορετικά προβλήματα και ίσως χρησιμοποιήσετε και τα δύο.

Πίνακας Σύγκρισης Χαρακτηριστικών

Πότε να Χρησιμοποιήσετε το Κάθε Ένα

Επιλέξτε Pydantic AI όταν θέλετε καθαρό, type-safe κώδικα agent. Είναι ιδανικό για tasks single-agent με εργαλεία (bots customer support, εξαγωγή δεδομένων, agents code review) και situations όπου η ελεγξιμότητα matters. Αν η ομάδα σας χρησιμοποιεί ήδη FastAPI και Pydantic, η καμπύλη μάθησης είναι σχεδόν επίπεδη.

Επιλέξτε LangGraph όταν χρειάζεστε complex multi-step workflows με conditional branching, human-in-the-loop approval και sophisticated state management. Το LangGraph excels στο orchestrating multiple steps, όχι στην ποιότητα individual agent. Για μια βαθιά ανάλυση, δείτε την πλήρη σύγκρισή μας LangGraph vs CrewAI vs OpenAI Agents SDK.

Επιλέξτε OpenAI Agents SDK όταν είστε 100% στο OpenAI, θέλετε το απλούστερο δυνατό setup και δεν χρειάζεστε υποστήριξη multi-provider ή DI.

Το Μοτίβο Συνδυασμού

Εδώ είναι τι κάνουν πραγματικά οι experienced teams: χρησιμοποιούν Pydantic AI για individual agents (καθαρός κώδικας, ελέγξιμος, typed outputs) και LangGraph για orchestration μεταξύ agents (routing, state machines, conditional logic). Δεν ανταγωνίζονται, είναι complementary layers.

# 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)

Συμπέρασμα: Επιλέξτε Pydantic AI για καθαρό, ελέγξιμο κώδικα agent. Επιλέξτε LangGraph για complex multi-step workflows. Δεν είναι αμοιβαία αποκλειόμενα.

Δοκιμή των Agents σας με TestModel

Αυτό είναι το section που χωρίζει έναν beginner guide από έναν production guide. Κάθε real codebase χρειάζεται tests και οι δοκιμές agents είναι notoriously hard, οι κλήσεις LLM είναι slow, expensive και non-deterministic. Το Pydantic AI διαθέτει μια λύση: 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 generates valid data that matches your result_type without making any API calls. Μηδενικό κόστος, deterministic, fast. Τα docs δοκιμών Pydantic AI καλύπτουν advanced patterns όπως FunctionModel για custom responses και capture_run_messages για inspection tool calls.

Δοκιμή Εργαλείων και DI Μαζί

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)

Χωρίς κλήσεις API. Χωρίς flaky tests. Χωρίς κόστος. Εκτελέστε το σε CI/CD alongside the rest of your test suite.

Αυτό είναι το #1 content gap σε ολόκληρο το SERP. Κανένας άλλος οδηγός Pydantic AI δεν καλύπτει τις δοκιμές. Αν φτιάχνετε agents για παραγωγή, αυτό είναι που χρειάζεστε.

Παρατηρησιμότητα, Ενσωμάτωση Logfire σε 5 Λεπτά

Οι agents παραγωγής χρειάζονται AI observability. Θέλετε να βλέπετε κάθε κλήση LLM, invocation εργαλείου, latency, token count και cost. Το Pydantic AI integrates natively with Logfire, την platform observability της ομάδας Pydantic (built on 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")

Τρεις γραμμές. Παίρνετε full traces showing: prompt sent, model response, tool calls (if any), validation passes/failures, retries, latency, and estimated cost. Αν το Logfire δεν είναι για εσάς, το Langfuse είναι μια solid open-source alternative με υποστήριξη context engineering για tracing how your prompts evolve.

FAQ

Τι είναι το Pydantic AI και πώς διαφέρει από το LangChain;

Το Pydantic AI είναι ένα type-safe agent framework όπου τα type hints της Python驱动 validation, tool schemas και dependency injection. Το LangChain είναι ένα μεγαλύτερο framework focused on chaining LLM calls together. Η βασική διαφορά: το Pydantic AI validates outputs at the framework level και provides built-in dependency injection for testability, το LangChain δεν κάνει κανένα από τα δύο by default.

Πώς φτιάχνω έναν type-safe AI agent με Pydantic AI;

Ορίστε ένα Pydantic BaseModel για την έξοδό σας, περάστε το ως result_type στο Agent και καλέστε run_sync() ή run(). Ο agent επιστρέφει ένα validated instance του μοντέλου σας, όχι μια raw string. Δείτε την ενότητα Structured Outputs για complete examples.

Θα πρέπει να χρησιμοποιήσω Pydantic AI ή LangGraph για agents παραγωγής;

Χρησιμοποιήστε Pydantic AI για individual agents όπου matter η type safety, η ελεγξιμότητα και ο καθαρός κώδικας. Χρησιμοποιήστε LangGraph για orchestrating complex multi-step workflows με conditional routing. Πολλές teams χρησιμοποιούν και τα δύο, agents Pydantic AI inside a LangGraph orchestration layer.

Πώς χειρίζεται το Pydantic AI την κλήση εργαλείων και το dependency injection;

Decorate a function with @agent.tool και το Pydantic AI reads its type hints to generate the tool schema. Για DI, set deps_type στο Agent και accept RunContext[YourDeps] στα tools. Runtime dependencies (DB connections, API clients) flow through without global state.

Πώς προσθέτω streaming σε έναν agent Pydantic AI;

Χρησιμοποιήστε agent.run_stream() αντί για agent.run(). Επιστρέφει έναν async context manager που yields partial results via stream_structured() or stream_text(). Το τελικό result είναι still fully validated against your result_type.

Είναι το Pydantic AI έτοιμο για παραγωγή το 2026;

Ναι. Η έκδοση 1.0 κυκλοφόρησε τον Σεπτέμβριο του 2025 με commitment API stability. Υποστηρίζεται από την ομάδα Pydantic (the most-downloaded Python library for data validation) και βρίσκεται currently at v1.74.0 με regular updates.

Μπορώ να χρησιμοποιήσω Pydantic AI με Ollama και local models;

Ναι. Χρησιμοποιήστε Agent("ollama:llama3.1") και βεβαιωθείτε ότι το Ollama τρέχει locally. Install the ollama provider extra: pip install "pydantic-ai[ollama]". Structured outputs and tools work the same as with cloud providers.

Πώς δοκιμάζω agents Pydantic AI;

Χρησιμοποιήστε TestModel, ένα mock model που generates valid structured data matching your result_type without API calls. Wrap your test in agent.override(model=TestModel()) και run assertions on the output. Δείτε την ενότητα Testing για complete pytest examples.

Λειτουργεί το Pydantic AI με FastAPI;

Άψογα. Μοιράζονται την ίδια φιλοσοφία dependency injection και είναι built by the same team. Μπορείτε να χρησιμοποιήσετε agents Pydantic AI inside FastAPI endpoints, share dependency types between them, και stream agent responses through StreamingResponse.

Ποια είναι η διαφορά μεταξύ Pydantic AI και OpenAI Agents SDK;

Το Pydantic AI είναι model-agnostic (works with OpenAI, Anthropic, Gemini, Ollama, etc.), έχει dependency injection, TestModel for testing, και Pydantic validation. Το OpenAI Agents SDK είναι simpler but locked to OpenAI models και lacks DI and built-in testing. Επιλέξτε Pydantic AI για flexibility· επιλέξτε OpenAI Agents SDK για το simplest possible OpenAI-only setup.

Βασικά Συμπεράσματα και Επόμενα Βήματα

Ξεκινήστε με έναν μικρό agent που έχει δομημένες εξόδους. Προσθέστε ένα εργαλείο. Προσθέστε εξαρτήσεις. Γράψτε ένα test με TestModel. Αυτός είναι ο production path και τώρα έχετε everything you need to walk it.

Τα official docs Pydantic AI και το GitHub repository are excellent for going deeper. Το framework moves fast, so bookmark the changelog.

Πηγές

• Pydantic AI, Επίσημη Τεκμηρίωση
• Τεκμηρίωση Εξαρτήσεων Pydantic AI
• Τεκμηρίωση Δοκιμών Pydantic AI
• Ανακοίνωση Κυκλοφορίας Pydantic AI v1
• Logfire AI Observability
• pydantic/pydantic-ai, GitHub Repository