Prejsť na hlavný obsah
Slovenčina— Vyberte jazyk
Menu

Pokročilé volanie funkcií: schémy a validácia

Lekcia 7 z 25 Aktualizované 29. júla 2026 Vývojár
Na tejto strane
  1. Pokročilé volanie funkcií: schémy a validácia
  2. JSON schémy a striktný režim
  3. Vlastná validácia s Pydantic
  4. Spracovanie chýb v nástrojoch
  5. Štruktúrovaný výstup pre nástroje
  6. Vzorec: nástroje so zdieľaným kontextom
  7. Kľúčové poznatky

Pokročilé volanie funkcií: schémy a validácia

Volanie funkcií je kľúčový mechanizmus, ktorý agentovi umožňuje rozhodovať, kedy a ako využiť tvoje nástroje. Na vytvorenie prototypu stačí nástroj len deklarovať, no nasadenie do produkcie si vyžaduje obmedzenie volaní, validáciu obchodných hodnôt a ošetrenie chýb bez pádu agenta. Presne toto pokrýva táto lekcia.

JSON schémy a striktný režim

API Responses využíva JSON schémy na opis parametrov pre každý nástroj a režim strict (striktný) zaručuje, že sa model bude týmito schémami presne riadiť. Konkrétne použitie typu Enum alebo Literal znemožňuje modelu vymýšľať si hodnoty.

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="Krátky názov tiketu (max 100 znakov)")
    description: str = Field(description="Podrobný opis problému")
    priority: Priority = Field(description="Úroveň priority tiketu")
    component: Literal["frontend", "backend", "infra", "data"] = Field(
        description="Dotknutá technická komponenta"
    )
    tags: list[str] = Field(
        default_factory=list,
        description="Voliteľné tagy na kategorizáciu tiketu"
    )

@function_tool
def create_support_ticket(ticket: CreateTicket) -> str:
    """Vytvorí nový tiket technickej podpory."""
    # V produkcii: volanie Jira, Linear, GitHub Issues atď.
    return f"Ticket created: [{ticket.priority.value}] {ticket.title} ({ticket.component})"

So štandardne zapnutým striktným režimom model nikdy neodošle neplatnú prioritu ani komponentu mimo povoleného zoznamu. Nebudeš musieť písať obranný backendový kód na prevod hodnôt ako „urgent“ alebo „P1“ na formát, ktorý rozpozná tvoj systém na správu tiketov.

Vlastná validácia s Pydantic

Kontrola typov zastaví nemožné hodnoty, nie však absurdné. Pätnásťznakový IBAN je technicky platný reťazec, no tvoja obchodná logika ho odmietne. Pydantic ti umožňuje vložiť tieto pravidlá priamo do schémy.

from pydantic import BaseModel, Field, field_validator

class MoneyTransfer(BaseModel):
    source_account: str = Field(description="IBAN zdrojového účtu")
    destination_account: str = Field(description="IBAN cieľového účtu")
    amount: float = Field(gt=0, le=50000, description="Suma v eurách (max 50 000)")
    reason: str = Field(min_length=5, max_length=200, description="Dôvod prevodu")

    @field_validator("source_account", "destination_account")
    @classmethod
    def validate_iban(cls, v):
        if not v.startswith("FR"):
            raise ValueError("Akceptujeme iba francúzske IBANy")
        if len(v) != 27:
            raise ValueError("IBAN musí mať 27 znakov")
        return v

@function_tool
def execute_transfer(transfer: MoneyTransfer) -> str:
    """Vykoná bankový prevod medzi dvoma účtami."""
    return f"Transfer of €{transfer.amount} initiated from {transfer.source_account[:8]}... to {transfer.destination_account[:8]}..."

Obmedzenia gt=0 a le=50000 pre sumu hrajú podobnú úlohu na inej úrovni: robia záporný prevod alebo prevod presahujúci limit štrukturálne nemožným, bez ohľadu na to, ako používateľ formulovať požiadavku.

Spracovanie chýb v nástrojoch

Čo robiť, keď sa nástroj spustí, ale zlyhá? Pokúsiť sa nechať výnimku prebublávať nahor je chyba, pretože to preruší slučku agenta. Namiesto toho vráť jasnú chybovú správu, ktorú si model dokáže prečítať a interpretovať.

import json
from agents import function_tool

@function_tool
def query_external_api(endpoint: str, parameters: dict) -> str:
    """Dopytuje externé API so zadanými parametrami."""
    try:
        # V produkcii: skutočné HTTP volanie
        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"Timeout calling {endpoint}. Retry in a few moments."
        })
    except httpx.HTTPStatusError as e:
        return json.dumps({
            "error": True,
            "message": f"HTTP error {e.response.status_code} on {endpoint}.",
            "details": str(e)
        })
    except Exception as e:
        return json.dumps({
            "error": True,
            "message": f"Unexpected error: {str(e)}"
        })

Každá vetva formátuje správu jazykom, ktorému model rozumie. Pri časovom limite sa agent pokúsi o ďalšie volanie; pri chybe HTTP 404 informuje používateľa alebo zmení prístup, namiesto toho, aby slepo trval na svojom.

Štruktúrovaný výstup pre nástroje

Toto obmedzenie platí aj pre konečný výstup. Pomocou output_type sa final_output prestáva byť textom na parsovanie a stáva sa typizovaným objektom, ktorý môže volajúci kód priamo využiť.

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="Analyst",
    instructions="Analyze the provided data and produce a structured report.",
    model="gpt-5.6-terra",
    output_type=AnalysisResponse,
)

result = Runner.run_sync(agent, "Analyze Q1 2026 sales trends.")
# result.final_output is of type AnalysisResponse
print(f"Summary: {result.final_output.summary}")
print(f"Score: {result.final_output.confidence_score}")

Vzorec: nástroje so zdieľaným kontextom

Posledný často sa opakujúci problém: tvoje nástroje často potrebujú zdieľaný stav – reláciu používateľa, pripojenie k databáze, API kľúč – ktorý by bolo absurdné odovzdávať cez model. Kontext toto rieši tak, že ho odovzdáva spolu s konverzáciou.

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

@dataclass
class AppContext:
    user_id: str
    db_connection: object  # Tvoje pripojenie k DB
    api_key: str

@function_tool
def get_user_profile(ctx: RunContextWrapper[AppContext]) -> str:
    """Načíta profil aktuálneho používateľa."""
    user_id = ctx.context.user_id
    # Použi ctx.context.db_connection na dopyt
    return f"User profile {user_id}: Premium, active since 2024"

agent = Agent(
    name="Personalized Agent",
    instructions="You assist the logged-in user.",
    tools=[get_user_profile],
)

context = AppContext(user_id="usr_123", db_connection=None, api_key="xxx")
result = Runner.run_sync(agent, "What is my profile?", context=context)

Nástroj nemá žiadne obchodné parametre: identita používateľa pochádza z kontextu, nie od modelu. Je to tiež bezpečnostné opatrenie, keďže agent nemôže zobraziť cudzí profil zmenou argumentu.

Kľúčové poznatky

  • Schémy Pydantic s enumami a Literals zaručujú platnosť volaní
  • Validátory polí pridávajú obchodnú validáciu navyše ku kontrole typov
  • V nástrojoch vracaaj chybové správy vo formáte JSON namiesto vyvolávania výnimiek
  • output_type núti agenta štruktúrovať svoju konečnú odpoveď
  • Zdieľaný kontext (RunContextWrapper) umožňuje nástrojom pristupovať k stavu aplikácie