Přejít na hlavní obsah
Čeština— Vyberte jazyk
Menu

Pokročilé volání funkcí: schémata a validace

Lekce 7 z 25 Aktualizováno 29. července 2026 Vývojář
Na této stránce
  1. Pokročilé volání funkcí: schémata a validace
  2. JSON schémata a striktní režim
  3. Vlastní validace s knihovnou Pydantic
  4. Zpracování chyb v nástrojích
  5. Strukturovaný výstup pro nástroje
  6. Vzor: Nástroje se sdíleným kontextem
  7. Klíčové poznatky

Pokročilé volání funkcí: schémata a validace

Volání funkcí je klíčový mechanismus, který agentovi umožňuje rozhodovat, kdy a jak využít vaše nástroje. Pro prototyp stačí nástroj pouze deklarovat, ale nasazení do produkce vyžaduje omezení volání, validaci obchodních dat a zpracování chyb bez pádu agenta. Přesně tím se zabývá tato lekce.

JSON schémata a striktní režim

API Responses využívá JSON schémata k popisu parametrů pro každý nástroj a režim strict zaručuje, že se model bude schématem řídit do posledního detailu. Konkrétně použití Enum nebo Literal zcela znemožňuje generování vymyšlených hodnot.

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="Short ticket title (max 100 characters)")
    description: str = Field(description="Detailed problem description")
    priority: Priority = Field(description="Ticket priority level")
    component: Literal["frontend", "backend", "infra", "data"] = Field(
        description="Affected technical component"
    )
    tags: list[str] = Field(
        default_factory=list,
        description="Optional tags to categorize the ticket"
    )

@function_tool
def create_support_ticket(ticket: CreateTicket) -> str:
    """Creates a new technical support ticket."""
    # In production: call Jira, Linear, GitHub Issues, etc.
    return f"Ticket created: [{ticket.priority.value}] {ticket.title} ({ticket.component})"

Díky výchozímu zapnutí striktního režimu model nikdy nepošle neplatnou prioritu ani komponentu mimo povolený seznam. Nebudeš muset psát obranný kód na straně backendu, který by převáděl hodnoty jako „urgent“ nebo „P1“ na formát rozpoznatelný tvým systémem pro správu úkolů.

Vlastní validace s knihovnou Pydantic

Kontrola typů sice zamezí nemožným hodnotám, ale neodfiltruje nesmysly. Patnáctiznakový IBAN je technicky platný řetězec, ale tvoje obchodní logika ho musí odmítnout. Pydantic ti umožňuje vložit tato pravidla přímo do schématu.

from pydantic import BaseModel, Field, field_validator

class MoneyTransfer(BaseModel):
    source_account: str = Field(description="Source account IBAN")
    destination_account: str = Field(description="Destination account IBAN")
    amount: float = Field(gt=0, le=50000, description="Amount in euros (max 50,000)")
    reason: str = Field(min_length=5, max_length=200, description="Reason for transfer")

    @field_validator("source_account", "destination_account")
    @classmethod
    def validate_iban(cls, v):
        if not v.startswith("FR"):
            raise ValueError("Only French IBANs are accepted")
        if len(v) != 27:
            raise ValueError("IBAN must contain 27 characters")
        return v

@function_tool
def execute_transfer(transfer: MoneyTransfer) -> str:
    """Executes a bank transfer between two accounts."""
    return f"Transfer of €{transfer.amount} initiated from {transfer.source_account[:8]}... to {transfer.destination_account[:8]}..."

Omezení gt=0 a le=50000 u částky hrají podobnou roli na jiné úrovni: činí záporný převod nebo převod překračující limit strukturálně nemožným, bez ohledu na to, jak uživatel požadavek formuluje.

Zpracování chyb v nástrojích

Co dělat, když se nástroj spustí, ale selže? Může tě lákat nechat výjimku probublat nahoru, ale to by byla chyba, protože by to přerušilo smyčku agenta. Místo toho vrať jasnou chybovou zprávu, kterou si model dokáže přečíst a interpretovat.

import json
from agents import function_tool

@function_tool
def query_external_api(endpoint: str, parameters: dict) -> str:
    """Queries an external API with the specified parameters."""
    try:
        # In production: real HTTP call
        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á větev formátuje zprávu jazykem, kterému model rozumí. Při časovém limitu se agent pokusí o další volání; při chybě HTTP 404 informuje uživatele nebo změní přístup, místo aby slepě trval na původním postupu.

Strukturovaný výstup pro nástroje

Toto omezení platí i pro konečný výstup. Díky parametru output_type není final_output již textem k parsování, ale typizovaným objektem, který může volající kód přímo využít.

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

Vzor: Nástroje se sdíleným kontextem

Poslední často se opakující problém: tvoje nástroje často potřebují sdílený stav – relaci uživatele, připojení k databázi, API klíč – který by bylo absurdní předávat přes model. Kontext tento problém řeší předáním těchto dat společně s konverzací.

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

@dataclass
class AppContext:
    user_id: str
    db_connection: object  # Your DB connection
    api_key: str

@function_tool
def get_user_profile(ctx: RunContextWrapper[AppContext]) -> str:
    """Retrieves the current user's profile."""
    user_id = ctx.context.user_id
    # Use ctx.context.db_connection for the query
    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á žádné obchodní parametry: identita uživatele pochází z kontextu, nikoliv od modelu. Je to také bezpečnostní opatření, protože agent nemůže zobrazit cizí profil pouhou změnou argumentu.

Klíčové poznatky

  • Schémata Pydantic s výčty (enums) a literály garantují platnost volání
  • Validátory polí přidávají nad rámec kontroly typů také obchodní validaci
  • V nástrojích vracej chybové zprávy ve formátu JSON místo vyhazování výjimek
  • output_type donutí agenta strukturovat svou konečnou odpověď
  • Sdílený kontext (RunContextWrapper) umožňuje nástrojům přístup ke stavu aplikace