Pydantic AI: Tuotantokäytön opas (Hello Worldin jälkeen)

Pydantic AI: Tuotantokäytön opas (Hello Worldin jälkeen)

Raaka LLM-tulosteet rikkovat sovelluksia. Pyydät JSONia, saat markdownia. Pyydät numeroa väliltä 1–10, saat vastaukseksi ”Totta kai! Tässä on numero: seitsemän.” Jos olet rakentanut mitään konkreettista LLM-APIen avulla, olet kirjoittanut puolustavaa jäsennyskoodia, joka saa kyseenalaistamaan uravalintasi. Pydantic AI korjaa tämän; se on tyyppiturvallinen agenttikehys, jonka on rakentanut sama tiimi Pydanticin ja FastAPIn takana. Ajattele sitä ”FastAPIna tekoälyagenteille”: määrität haluamasi Pythonin tyyppiviitteillä, ja kehys hoitaa validoinnin, uudelleenyritykset ja työkalukutsut.

Tämä Pydantic AI -opas on suunnattu kehittäjille, jotka ovat jo suorittaneet ensimmäisen LLM-kutsunsa ja kaipaavat tuotantokäytön malleja: strukturoidut tulosteet, jotka eivät hajoa, riippuvuuksien injektointi testattavia agentteja varten sekä oikean maailman työkalut säärajapintojen sijaan. Lopussa sinulla on toimivat agentit työkaluineen, DI:nä, striimauksineen ja testeineen.

Pydantic AI pähkinänkuoressa

Erottuvia ominaisuuksia ovat strukturoidut tulosteet (validoitu Pydantic-malleilla), riippuvuuksien injektointi (kuten FastAPIn Depends) ja TestModel (mock-LLM testaamiseen ilman API-kutsuja). Jos tulet LangChainista ja ihmettelet, ”onko olemassa siistimpää vaihtoehtoa?”, tämä on todennäköisesti se.

Asennus ja ensimmäinen agentti

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

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

Ensimmäinen agenttisi viidellä rivillä:

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"

Siinä kaikki. Agent kietoo mallin, run_sync lähettää kehotteen ja palauttaa tuloksen. result.output on tässä vaiheessa pelkkä merkkijono, mutta se on kohta muuttumassa.

Strukturoidut tulosteet, syy Pydantic AI:n olemassaololle

Tämä on ydinominaisuus. Sen sijaan, että saisit LLM:ltä merkkijonon ja toivoisit sen olevan kelvollista JSONia, määrität Pydantic-mallin, ja agentti palauttaa validoidun Python-objektin.

Ennen: Raaka LLM-tuloste

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

Jälkeen: Strukturoitu Pydantic AI:lla

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)

Ero on kuin yöllä ja päivällä. result.output on aito MovieReview-objekti. Jos LLM palauttaa rating: "eight" instead of rating: 8, Pydanticin validointi havaitsee virheen. Syvällisempää tietoa siitä, miten tämä toimii eri palveluntarjoajilla, löytyy oppaastamme strukturoiduista tulosteista eri LLM-palveluntarjoajilla.

Mitä tapahtuu, kun validointi epäonnistuu

Tässä on osa, jota mikään muu opetusohjelma ei näytä: mitä tapahtuu, kun LLM mokaa?

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

Tämä palauteperusteinen uudelleenyrityssilmukka on Pydantic AI:n killer-ominaisuus. LLM oppii omista validointivirheistään. Sinun ei tarvitse kirjoittaa uudelleenyrityslogiikkaa, kehys hoitaa sen.

Arvio: Strukturoidut tulosteet ovat yksittäisin paras syy käyttää Pydantic AI:ta raakojen API-kutsujen sijaan. Jos jäsennät LLM:n JSONia käsin, lopeta.

Työkalut ja funktiokutsut

Työkalut antavat agentillesi mahdollisuuden kutsua Python-funktioita saadakseen todellista dataa. Sen sijaan, että LLM keksisi faktoja, se voi kysyä tietokantaasi, etsiä dokumenteistasi tai kutsua rajapintaa.

Työkalun rekisteröinti

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)

@agent.tool-decorator rekisteröi funktion. Pydantic AI lukee funktion tyyppiviitteet ja docstringin kertoakseen LLM:lle, mitä työkalu tekee, mitä argumentteja se ottaa ja mitä se palauttaa. Ei manuaalista skeeman kirjoittamista, tyyppiviitteesi OVAT skeema. Taustatietoa siitä, miten LLM-funktiokutsut toimivat kulissien takana, löydät omasta oppaastamme.

RunContext: Datan välittäminen työkaluille

Tässä kohdassa Pydantic AI eroaa muista kehyksistä. RunContext antaa sinun välittää ajonaikaista dataa (tietokantayhteydet, käyttäjätiedot, API-asiakkaat) työkaluillesi ilman globaalia tilaa.

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 antaa työkalulle pääsyn mihin tahansa, mitä ajoit runtime-vaiheessa. Työkalu ei tuo globaalia tietokantayhteyttä, vaan se saa sellaisen. Tämä on riippuvuuksien injektointia, ja se tekee agenteistasi testattavia.

Esimerkki todellisesta työkalusta

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

Arvio: Työkalukutsut Pydantic AI:ssa ovat siistimpiä kuin missään muussa kehyksessä, koska tyyppiviitteet tekevät raskaan työn. Kirjoitat normaaleja Python-funktioita tyyppimäärityksillä. Kehys selvittää loput.

Riippuvuuksien injektointi, ominaisuus jonka LangChain toivoisi itsellään olevan

Jos olet käyttänyt FastAPIn Depends-toimintoa, ymmärrät jo Pydantic AI:n DI-järjestelmän. Jos et, tässä lyhyt versio: sen sijaan, että agenttisi hakisi tarvitsemansa itse (globaalit tietokantayhteydet, API-asiakkaat, konfiguraatio), annat sille kaiken runtime-vaiheessa.

Riippuvuuksien määrittely

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

Riippuvuuksien käyttö työkaluissa

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

Miksi DI tekee agenteistasi testattavia

Tässä on varsinainen hyöty. LangChainissa välittäisit kontekstia ketjun kwargsien tai sulkeumien kautta, eikä ole olemassa standardimallia. Pydantic AI:ssa oikeiden riippuvuuksien vaihtaminen testikaksoiskappaleisiin on triviaalia:

# 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

Ei monkey-patchausta. Ei globaalien tuontien mockkausta. Välität vain eri depsit.

Arvio: Riippuvuuksien injektointi on syy, miksi kokeneet Python-kehittäjät suosivat Pydantic AI:ta. FastAPI-vaikutus näkyy selvästi.

Mallipalveluntarjoajat, OpenAI, Anthropic, Gemini, Ollama

Pydantic AI on malliriippumaton. Palveluntarjoajan vaihtaminen on yhden rivin muutos:

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

Kaikki muu, työkalut, strukturoidut tulosteet, DI, pysyy identtisenä. Liiketoimintalogiikkasi ei muutu, kun vaihdat malleja.

Arvio: Malliriippumaton suunnittelu tarkoittaa, ettet ole lukittuna yhteen palveluntarjoajaan. Aloita OpenAI:lla helppouden vuoksi, vertaile Anthropicilla ja käytä Ollamaa paikalliseen kehittämiseen.

Vastausten striimaus

Keskustelukäyttöliittymiä ja reaaliaikaisia sovelluksia varten striimaus on välttämätöntä. Pydantic AI tukee sitä säilyttäen samalla tyyppiturvallisuuden:

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

Tämä toimii saumattomasti yhdessä FastAPIn StreamingResponse-luokan kanssa, sama ekosysteemi, samat mallit. Pydantic AI -agenttien dokumentaatio kattaa edistyneet striimausvaihtoehdot, mukaan lukien pelkän tekstin striimauksen stream_text()-funktiolla.

Pydantic AI vs LangGraph vs OpenAI Agents SDK

Olet täällä, joten kysyt todennäköisesti: ”pitäisikö minun käyttää Pydantic AI:ta vai LangGraphia?” Rehellinen vastaus: ne ratkaisevat eri ongelmia, ja saatat käyttää molempia.

Ominaisuuksien vertailutaulukko

Milloin käyttää mitäkin

Valitse Pydantic AI, kun haluat siistiä, tyyppiturvallista agenttikoodia. Se on ihanteellinen yhden agentin tehtäviin työkaluineen (asiakaspalvelubotit, datan poiminta, koodikatselmointiagentit) ja tilanteisiin, joissa testattavuus on tärkeää. Jos tiimisi käyttää jo FastAPIa ja Pydanticia, oppimiskäyrä on lähes olematon.

Valitse LangGraph, kun tarvitset monimutkaisia monivaiheisia työnkulkuja ehdollisilla haaroituksilla, ihmisen hyväksynnällä silmukassa ja kehittyneellä tilanhallinnalla. LangGraph loistaa useiden vaiheiden orkestroinnissa, ei yksittäisten agenttien laadussa. Syvällistä tarkastelua varten katso täydellinen LangGraph vs CrewAI vs OpenAI Agents SDK -vertailumme.

Valitse OpenAI Agents SDK, kun olet 100 % OpenAI:ssa, haluat mahdollisimman yksinkertaisen asennuksen etkä tarvitse multi-palveluntarjoajatukea tai DI:tä.

Yhdistelmämalli

Tässä on mitä kokeneet tiimit todella tekevät: käyttävät Pydantic AI:ta yksittäisiin agentteihin (siisti koodi, testattava, tyypitetyt tulosteet) ja LangGraphia agenttien väliseen orkestrointiin (reititys, tilakoneet, ehdollinen logiikka). Ne eivät kilpaile, vaan ovat toisiaan täydentäviä kerroksia.

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

Arvio: Valitse Pydantic AI siistiin, testattavaan agenttikoodiin. Valitse LangGraph monimutkaisiin monivaiheisiin työnkulkuhin. Ne eivät ole toisensa poissulkevia.

Agenttiesi testaaminen TestModelilla

Tämä osio erottaa aloittelijan oppaan tuotanto-oppaasta. Jokainen todellinen koodikanta tarvitsee testejä, ja agenttien testaaminen on tunnetusti vaikeaa, LLM-kutsut ovat hitaita, kalliita ja ei-deterministisiä. Pydantic AI tarjoaa ratkaisun: 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 generoi kelvollista dataa, joka vastaa result_type-määritystäsi tekemättä yhtään API-kutsua. Nolla kustannuksia, deterministinen, nopea. Pydantic AI:n testausdokumentaatio kattaa edistyneet mallit kuten FunctionModel mukautettuja vastauksia varten ja capture_run_messages työkalukutsujen tarkasteluun.

Työkalujen ja DI:n testaaminen yhdessä

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)

Ei API-kutsuja. Ei epävakkaita testejä. Ei kustannuksia. Aja tämä CI/CD-putkessa muun testisarjasi rinnalla.

Tämä on SERP:n suurin sisältöaukko. Mikään muu Pydantic AI -opas ei kata testaamista. Jos rakennat agentteja tuotantoon, tätä tarvitset.

Havainnollistaminen, Logfire-integraatio viidessä minuutissa

Tuotantoagentit tarvitsevat tekoälyn havainnollistamista. Haluat nähdä jokaisen LLM-kutsun, työkalukutsun, latenssin, token-määrän ja kustannukset. Pydantic AI integroituu natiivisti Logfireen, Pydantic-tiimin havainnollistamisalustaan (rakennettu OpenTelemetryn päälle).

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

Kolme riviä. Saat täydelliset jäljitykset, jotka näyttävät: lähetetty kehotteen, mallin vastauksen, työkalukutsut (jos niitä oli), validoinnin onnistumiset/epäonnistumiset, uudelleenyritykset, latenssin ja arvioidut kustannukset. Jos Logfire ei ole juttusi, Langfuse on vankka avoimen lähdekoodin vaihtoehto, joka tukee kontekstisuunnittelua kehotteidesi evoluution jäljittämiseen.

FAQ

Mikä on Pydantic AI ja miten se eroaa LangChainista?

Pydantic AI on tyyppiturvallinen agenttikehys, jossa Pythonin tyyppiviitteet ohjaavat validointia, työkaluskeemoja ja riippuvuuksien injektointia. LangChain on suurempi kehys, joka keskittyy LLM-kutsujen ketjuttamiseen. Keskeinen ero: Pydantic AI validoi tulosteet kehystasolla ja tarjoaa sisäänrakennetun riippuvuuksien injektoinnin testattavuutta varten, LangChain ei tee kumpaakaan oletusarvoisesti.

Kuinka rakennan tyyppiturvallisen tekoälyagentin Pydantic AI:lla?

Määritä Pydantic BaseModel tulostettasi varten, välitä se result_type:nä Agent-luokalle ja kutsu run_sync() tai run(). Agentti palauttaa validoidun instanssin mallistasi, ei raakaa merkkijonoa. Katso kokonaiset esimerkit Strukturoitut tulosteet -osiosta.

Pitäisikö minun käyttää Pydantic AI:ta vai LangGraphia tuotantoagentteihin?

Käytä Pydantic AI:ta yksittäisiin agentteihin, joissa tyyppiturvallisuus, testattavuus ja siisti koodi ovat tärkeitä. Käytä LangGraphia monimutkaisten monivaiheisten työnkulkujen orkestrointiin ehdollisella reitityksellä. Monet tiimit käyttävät molempia, Pydantic AI -agentteja LangGraph-orkestrointikerroksen sisällä.

Miten Pydantic AI käsittelee työkalukutsut ja riippuvuuksien injektoinnin?

Koristele funktio @agent.tool:lla, ja Pydantic AI lukee sen tyyppiviitteet generoidakseen työkaluskeeman. DI:tä varten aseta deps_type Agent-luokalle ja hyväksy RunContext[YourDeps] työkaluissa. Runtime-riippuvuudet (DB-yhteydet, API-asiakkaat) virtaavat läpi ilman globaalia tilaa.

Miten lisään striimauksen Pydantic AI -agenttiin?

Käytä agent.run_stream() agent.run():n sijaan. Se palauttaa asynkronisen kontekstihallinnan, joka tuottaa osittaisia tuloksia stream_structured()- tai stream_text()-funktioiden kautta. Lopullinen tulos on edelleen täysin validoitu result_type-määritystäsi vastaan.

Onko Pydantic AI tuotantovalmis vuonna 2026?

Kyllä. Versio 1.0 julkaistiin syyskuussa 2025 API-stabiilisuuslupauksen kera. Sitä tukee Pydantic-tiimi (ladatuin Python-kirjasto datan validointiin) ja se on tällä hetkellä versiossa v1.74.0 säännöllisin päivityksin.

Voinko käyttää Pydantic AI:ta Ollaman ja paikallisten mallien kanssa?

Kyllä. Käytä Agent("ollama:llama3.1") ja varmista, että Ollama on käynnissä paikallisesti. Asenna ollama-palveluntarjoajan lisäosa: pip install "pydantic-ai[ollama]". Strukturoidut tulosteet ja työkalut toimivat samalla tavalla kuin pilvipalveluntarjoajien kanssa.

Miten testaan Pydantic AI -agentteja?

Käytä TestModelia, mock-mallia, joka generoi kelvollista strukturoitua dataa vastaamaan result_type-määritystäsi ilman API-kutsuja. Kiedo testi agent.override(model=TestModel()):n sisään ja aja väitteet tulokselle. Katso Testing-osio kokonaisista pytest-esimerkeistä.

Toimiko Pydantic AI yhdessä FastAPIn kanssa?

Täydellisesti. Ne jakavat saman riippuvuuksien injektointifilosofian ja niiden takana on sama tiimi. Voit käyttää Pydantic AI -agentteja FastAPI-endpointeissa, jakaa riippuvuustyyppejä niiden välillä ja striimata agenttivastauksia StreamingResponse-luokan kautta.

Mikä on ero Pydantic AI:n ja OpenAI Agents SDK:n välillä?

Pydantic AI on malliriippumaton (toimii OpenAI:n, Anthropicin, Geminin, Ollaman jne. kanssa), siinä on riippuvuuksien injektointi, TestModel testaamista varten ja Pydantic-validointi. OpenAI Agents SDK on yksinkertaisempi, mutta lukittu OpenAI-malleihin, ja siitä puuttuu DI ja sisäänrakennettu testaus. Valitse Pydantic AI joustavuuden vuoksi; valitse OpenAI Agents SDK yksinkertaisimpaan mahdolliseen vain-OpenAI-asennukseen.

Keskeiset huomiot ja seuraavat askeleet

Aloita pienellä agentilla, jolla on strukturoidut tulosteet. Lisää työkalu. Lisää riippuvuudet. Kirjoita testi TestModelilla. Tämä on tuotantopolku, ja sinulla on nyt kaikki tarvittava sen kulkemiseen.

Viralliset Pydantic AI -dokumentit ja GitHub-repositorio ovat erinomaisia syventymistä varten. Kehys kehittyy nopeasti, joten lisää muutosloki kirjanmerkkeihisi.

Lähteet

• Pydantic AI, Virallinen dokumentaatio
• Pydantic AI Riippuvuuksien dokumentaatio
• Pydantic AI Testausdokumentaatio
• Pydantic AI v1 Julkaisuannonssi
• Logfire Tekoälyn havainnollistaminen
• pydantic/pydantic-ai, GitHub-repositorio