Chiamate di funzioni avanzate: schemi e convalida
In questa pagina
Chiamate di funzioni avanzate: schemi e convalida
La chiamata di funzioni è il meccanismo fondamentale che permette a un agente di decidere quando e come invocare i tuoi strumenti. Dichiarare uno strumento è sufficiente per un prototipo, ma passare alla produzione richiede di vincolare le chiamate, convalidare i valori aziendali e gestire gli errori senza bloccare l’agente. È proprio questo l’argomento di questa lezione.
Schemi JSON e modalità strict
Le API Responses utilizzano schemi JSON per descrivere i parametri di ciascuno strumento, e la modalità strict garantisce che il modello aderisca esattamente allo schema. Nello specifico, l’uso di un Enum o di un Literal impedisce categoricamente l’invenzione di valori non previsti.
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})"
Con la modalità strict abilitata di default, il modello non può mai inviare una priorità non valida o un componente al di fuori dell’elenco consentito. Non avrai bisogno di scrivere codice backend difensivo per tradurre “urgente” o “P1” in un valore riconosciuto dal tuo sistema di ticketing.
Convalida personalizzata con Pydantic
Il controllo dei tipi blocca i valori impossibili, non quelli assurdi. Un IBAN di quindici caratteri è una stringa perfettamente valida; è la tua logica aziendale a rifiutarla. Pydantic ti permette di incorporare queste regole direttamente nello schema.
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]}..."
I vincoli gt=0 e le=50000 sull’importo svolgono un ruolo simile a un livello diverso: rendono strutturalmente impossibile un trasferimento negativo o uno che superi il limite, indipendentemente da come l’utente formula la richiesta.
Gestione degli errori negli strumenti
Cosa succede quando uno strumento viene eseguito ma fallisce? La tentazione è lasciare che l’eccezione risalga la catena; è un errore, perché interrompe il ciclo dell’agente. Invece, restituisci un messaggio di errore chiaro che il modello possa leggere e interpretare.
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)}"
})
Ogni ramo formatta il messaggio in un linguaggio comprensibile al modello. In caso di timeout, l’agente tenterà un’altra chiamata; in caso di errore HTTP 404, informerà l’utente o cambierà approccio invece di persistere ciecamente.
Output strutturato per gli strumenti
Questo vincolo si applica anche all’output finale. Con output_type, final_output non è più un testo da analizzare, ma un oggetto tipizzato, direttamente utilizzabile dal codice chiamante.
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}")
Pattern: strumenti con contesto condiviso
Un’ultima questione ricorrente: i tuoi strumenti spesso necessitano di uno stato condiviso—sessione utente, connessione al database, chiave API—che sarebbe assurdo passare attraverso il modello. Il contesto risolve questo problema passandolo insieme alla conversazione.
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)
Lo strumento non ha parametri di business: l’identità dell’utente proviene dal contesto, non dal modello. Questa è anche una misura di sicurezza, poiché l’agente non può visualizzare il profilo di qualcun altro modificando un argomento.
Punti chiave
- Gli schemi Pydantic con enum e Literal garantiscono la validità delle chiamate
- I validatori di campo aggiungono la convalida aziendale al controllo dei tipi
- Restituisci messaggi di errore JSON invece di sollevare eccezioni negli strumenti
output_typeforza l’agente a strutturare la sua risposta finale- Il contesto condiviso (
RunContextWrapper) permette agli strumenti di accedere allo stato dell’applicazione