Pokročilé volání funkcí: schémata a validace
Na této stránce
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_typedonutí agenta strukturovat svou konečnou odpověď- Sdílený kontext (
RunContextWrapper) umožňuje nástrojům přístup ke stavu aplikace