Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Chiamate di funzioni avanzate: schemi e convalida

Lezione 7 di 25 Aggiornata il 29 luglio 2026 Sviluppatore
In questa pagina
  1. Chiamate di funzioni avanzate: schemi e convalida
  2. Schemi JSON e modalità strict
  3. Convalida personalizzata con Pydantic
  4. Gestione degli errori negli strumenti
  5. Output strutturato per gli strumenti
  6. Pattern: strumenti con contesto condiviso
  7. Punti chiave

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_type forza l’agente a strutturare la sua risposta finale
  • Il contesto condiviso (RunContextWrapper) permette agli strumenti di accedere allo stato dell’applicazione