Lähe põhisisu juurde
Eesti— Vali keel
Menüü

Funktsioonide kutsumine edasijõudnutele: skeemid ja valideerimine

Õppetund 7 / 25 Värskendatud 29. juuli 2026 Arendajatele
Sellel lehel
  1. Funktsioonide kutsumine edasijõudnutele: skeemid ja valideerimine
  2. JSON-skeemid ja range režiim
  3. Kohandatud valideerimine Pydanticuga
  4. Vigade käsitlemine tööriistades
  5. Struktureeritud väljund tööriistade jaoks
  6. Muster: ühise kontekstiga tööriistad
  7. Peamised punktid

Funktsioonide kutsumine edasijõudnutele: skeemid ja valideerimine

Funktsioonide kutsumine on põhimehhanism, mis võimaldab agendil otsustada, millal ja kuidas sinu tööriistu kasutada. Tööriista deklareerimine piisab prototüübi jaoks, kuid tootmisse viimisel pead piirama kutseid, valideerima ärireegleid ja käsitlema tõrkeid nii, et agent ei krahhiks. Seda käsitlemegi selles tunnis.

JSON-skeemid ja range režiim

Vastuste API kasutab JSON-skeeme iga tööriista parameetrite kirjeldamiseks ning range (strict) režiim tagab, et mudel järgib skeemi täpselt. Täpsemalt öeldes välistab Enum või Literal kasutamine väljamõeldud väärtused.

from agents import function_tool
from pydantic import BaseModel, Field
from typing import Literal
from enum import Enum

class Priority(str, Enum):
    LOW = "low"
    MEDIUM = "medium"
    HIGH = "high"
    CRITICAL = "critical"

class CreateTicket(BaseModel):
    title: str = Field(description="Lühike pöördumise pealkiri (max 100 tähemärki)")
    description: str = Field(description="Üksikasjalik probleemi kirjeldus")
    priority: Priority = Field(description="Pöördumise prioriteedi tase")
    component: Literal["frontend", "backend", "infra", "data"] = Field(
        description="Mõjutatud tehniline komponent"
    )
    tags: list[str] = Field(
        default_factory=list,
        description="Valikulised sildid pöördumise kategoriseerimiseks"
    )

@function_tool
def create_support_ticket(ticket: CreateTicket) -> str:
    """Loob uue tehnilise toe pöördumise."""
    # Tootmises: helista Jirale, Linearile, GitHub Issues'ile jne.
    return f"Pöördumine loodud: [{ticket.priority.value}] {ticket.title} ({ticket.component})"

Vaikimisi lubatud range režiimiga ei saa mudel kunagi saata vigast prioriteeti ega komponenti, mis pole lubatud loendis. Sa ei pea kirjutama kaitsvat taustakoodi, et tõlkida „kiireloomuline“ või „P1“ väärtuseks, mida sinu pöördumiste süsteem tunneb ära.

Kohandatud valideerimine Pydanticuga

Tüübikontroll peatab võimatud väärtused, mitte aga absurdsed. Viieteistmekohaline IBAN on tehniliselt kehtiv string; sinu äriloogika lükkab selle tagasi. Pydantic võimaldab need reeglid otse skeemi sisse põimida.

from pydantic import BaseModel, Field, field_validator

class MoneyTransfer(BaseModel):
    source_account: str = Field(description="Konto IBAN, kust raha saadetakse")
    destination_account: str = Field(description="Konto IBAN, kuhu raha saadetakse")
    amount: float = Field(gt=0, le=50000, description="Summa eurodes (max 50 000)")
    reason: str = Field(min_length=5, max_length=200, description="Ülekande põhjus")

    @field_validator("source_account", "destination_account")
    @classmethod
    def validate_iban(cls, v):
        if not v.startswith("FR"):
            raise ValueError("Aktsepteeritakse ainult Prantsuse IBAN-e")
        if len(v) != 27:
            raise ValueError("IBAN peab sisaldama 27 tähemärki")
        return v

@function_tool
def execute_transfer(transfer: MoneyTransfer) -> str:
    """Teostab pangaulekande kahe konto vahel."""
    return f"Ülekanne summas €{transfer.amount} algatatud kontolt {transfer.source_account[:8]}... kontole {transfer.destination_account[:8]}..."

Piirangud gt=0 ja le=50000 summale mängivad sarnast rolli teisel tasandil: need muudavad negatiivse ülekande või limiiti ületava ülekande struktuurselt võimatuks, sõltumata sellest, kuidas kasutaja soovi väljendab.

Vigade käsitlemine tööriistades

Mis saab siis, kui tööriist käivitub, kuid ebaõnnestub? Kiusatus on lasta erindil edasi kanduda; see on viga, sest see katkestab agendi tsükli. Selle asemel tagasta selge veateade, mida mudel saab lugeda ja tõlgendada.

import json
from agents import function_tool

@function_tool
def query_external_api(endpoint: str, parameters: dict) -> str:
    """Päring välisele API-le määratud parameetritega."""
    try:
        # Tootmises: tegelik HTTP-päring
        import httpx
        response = httpx.get(f"https://api.example.com/{endpoint}", params=parameters, timeout=10)
        response.raise_for_status()
        return json.dumps(response.json(), ensure_ascii=False)
    except httpx.TimeoutException:
        return json.dumps({
            "error": True,
            "message": f"Aegumine päringul {endpoint}. Proovi mõne hetke pärast uuesti."
        })
    except httpx.HTTPStatusError as e:
        return json.dumps({
            "error": True,
            "message": f"HTTP viga {e.response.status_code} päringul {endpoint}.",
            "details": str(e)
        })
    except Exception as e:
        return json.dumps({
            "error": True,
            "message": f"Ootamatu viga: {str(e)}"
        })

Iga haru vormindab sõnumi keeles, mida mudel mõistab. Aegumise korral püüab agent uut kutset; HTTP 404 vea korral teavitab ta kasutajat või muudab lähenemist, selle asemel et pimesi jätkata.

Struktureeritud väljund tööriistade jaoks

See piirang kehtib ka lõppväljundi kohta. Kasutades output_type, ei ole final_output enam parsitav tekst, vaid tüübitud objekt, mida kutsev kood saab otse kasutada.

from pydantic import BaseModel
from agents import Agent, Runner

class AnalysisResponse(BaseModel):
    summary: str
    key_points: list[str]
    recommendation: str
    confidence_score: float

agent = Agent(
    name="Analüütik",
    instructions="Analüüsi esitatud andmeid ja koosta struktureeritud aruanne.",
    model="gpt-5.6-terra",
    output_type=AnalysisResponse,
)

result = Runner.run_sync(agent, "Analüüsi 2026. aasta esimese kvartali müügitrende.")
# result.final_output on tüüpi AnalysisResponse
print(f"Kokkuvõte: {result.final_output.summary}")
print(f"Skoor: {result.final_output.confidence_score}")

Muster: ühise kontekstiga tööriistad

Viimane korduv probleem: sinu tööriistad vajavad sageli ühist olekut – kasutaja seanss, andmebaasiühendus, API võti –, mida oleks absurdne mudeli kaudu edastada. Kontekst lahendab selle, edastades need koos vestlusega.

from dataclasses import dataclass
from agents import Agent, Runner, RunContextWrapper, function_tool

@dataclass
class AppContext:
    user_id: str
    db_connection: object  # Sinu andmebaasiühendus
    api_key: str

@function_tool
def get_user_profile(ctx: RunContextWrapper[AppContext]) -> str:
    """Toob praeguse kasutaja profiili."""
    user_id = ctx.context.user_id
    # Kasuta ctx.context.db_connection päringu tegemiseks
    return f"Kasutaja profiil {user_id}: Premium, aktiivne alates 2024"

agent = Agent(
    name="Isikupärastatud agent",
    instructions="Sa abistad sisselogitud kasutajat.",
    tools=[get_user_profile],
)

context = AppContext(user_id="usr_123", db_connection=None, api_key="xxx")
result = Runner.run_sync(agent, "Mis on minu profiil?", context=context)

Tööriistal puuduvad äriparameetrid: kasutaja identiteet pärineb kontekstist, mitte mudelilt. See on ka turvameede, kuna agent ei saa kellegi teise profiili vaadata, muutes argumenti.

Peamised punktid

  • Pydantici skeemid koos enumide ja Literalidega tagavad kutsete kehtivuse
  • Välja valideerijad lisavad tüübikontrollile ärireeglite valideerimise
  • Tagasta tööriistades JSON-vormingus veateated erindite tõstmise asemel
  • output_type sunnib agenti struktureerima oma lõppvastust
  • Ühine kontekst (RunContextWrapper) võimaldab tööriistadel juurdepääsu rakenduse olekule