Apelarea avansată de funcții: scheme și validare
Pe această pagină
Apelarea avansată de funcții: scheme și validare
Apelarea de funcții reprezintă mecanismul central care permite unui agent să decidă când și cum să invoce instrumentele dumneavoastră. Declararea unui instrument este suficientă pentru un prototip, însă trecerea la producție necesită constrângerea apelurilor, validarea valorilor comerciale și gestionarea erorilor fără a bloca agentul. Acesta este subiectul acestei lecții.
Scheme JSON și modul strict
API-ul Responses utilizează scheme JSON pentru a descrie parametrii fiecărui instrument, iar modul strict garantează că modelul respectă exact schema. În mod specific, utilizarea unui Enum sau a unui Literal elimină posibilitatea generării de valori inventate.
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})"
Cu modul strict activat implicit, modelul nu poate trimite niciodată o prioritate invalidă sau o componentă care nu se află în lista permisă. Nu va fi nevoie să scrieți cod defensiv în backend pentru a traduce „urgent“ sau „P1“ într-o valoare recunoscută de sistemul dumneavoastră de ticketing.
Validare personalizată cu Pydantic
Verificarea tipurilor oprește valorile imposibile, nu și pe cele absurde. Un IBAN de cincisprezece caractere este un șir perfect valid; logica dumneavoastră de afaceri este cea care îl respinge. Pydantic vă permite să încorporați aceste reguli direct în schemă.
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]}..."
Constrângerile gt=0 și le=50000 aplicate sumei joacă un rol similar la un nivel diferit: ele fac imposibilă structural o transfer negativ sau unul care depășește limita, indiferent de modul în care utilizatorul formulează cererea.
Gestionarea erorilor în instrumente
Ce se întâmplă când un instrument se execută, dar eșuează? Tentația este de a lăsa excepția să se propage; aceasta este o greșeală, deoarece întrerupe bucla agentului. În schimb, returnați un mesaj de eroare clar pe care modelul îl poate citi și interpreta.
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)}"
})
Fiecare ramură formatează mesajul într-un limbaj pe care modelul îl înțelege. În cazul unui timeout, agentul va încerca un nou apel; în cazul unei erori HTTP 404, acesta va informa utilizatorul sau va schimba abordarea, în loc să persiste orbește.
Ieșire structurată pentru instrumente
Această constrângere se aplică și rezultatului final. Cu output_type, final_output nu mai este un text de parsat, ci un obiect tipat, utilizabil direct de către codul apelant.
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}")
Model: instrumente cu context partajat
O ultimă problemă recurentă: instrumentele dumneavoastră au adesea nevoie de o stare partajată – sesiunea utilizatorului, conexiunea la baza de date, cheia API – pe care ar fi absurd să o transmiteți prin intermediul modelului. Contextul rezolvă această problemă prin transmiterea sa alături de conversație.
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)
Instrumentul nu are parametri de afaceri: identitatea utilizatorului provine din context, nu de la model. Aceasta este, de asemenea, o măsură de securitate, deoarece agentul nu poate vizualiza profilul altei persoane modificând un argument.
Puncte cheie
- Schemele Pydantic cu enum-uri și Literals garantează validitatea apelurilor
- Validatorii de câmp adaugă validare de afaceri peste verificarea tipurilor
- Returnați mesaje de eroare JSON în loc să aruncați excepții în instrumente
output_typeforțează agentul să structureze răspunsul final- Contextul partajat (
RunContextWrapper) permite instrumentelor să acceseze starea aplicației