Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Ricerca Strumenti: Strumenti Dinamici

Lezione 10 di 25 Aggiornata il 29 luglio 2026 Sviluppatore
In questa pagina
  1. Ricerca Strumenti: Strumenti Dinamici
  2. Il problema di troppi strumenti
  3. Abilitare la Ricerca Strumenti
  4. Pattern: Selezione Manuale degli Strumenti
  5. Pattern: Strumenti Dinamici Consapevoli del Contesto
  6. Ottimizzare le Descrizioni degli Strumenti
  7. Punti chiave

Ricerca Strumenti: Strumenti Dinamici

Un agente dimostrativo se la cava benissimo con tre o quattro strumenti. Un agente enterprise, invece, ne accumula inevitabilmente decine, a volte centinaia: fatturazione, risorse umane, CRM, documenti, pianificazione. A quella scala, inviare l’intero catalogo al modello ad ogni richiesta diventa inefficiente e costoso in termini di token. La Ricerca Strumenti risolve questo problema selezionando dinamicamente gli strumenti rilevanti per ogni richiesta.

Il problema di troppi strumenti

Immagina un agente con 50 strumenti. Ad ogni chiamata API, gli schemi di tutti e 50 gli strumenti vengono inviati nel prompt. Questo consuma migliaia di token e può confondere il modello: più la lista è lunga, più le descrizioni diventano simili e più il modello esita tra strumenti affini. I costi salgono mentre la precisione scende: la combinazione peggiore possibile.

# Problema: troppi strumenti
agent = Agent(
    name="Super Agent",
    instructions="Puoi fare qualsiasi cosa.",
    tools=[tool_1, tool_2, tool_3, ... , tool_50],  # 50 strumenti = molti token
)

Abilitare la Ricerca Strumenti

La Ricerca Strumenti utilizza un indice semantico per selezionare gli strumenti rilevanti in base alla richiesta. Dichiar i tuoi strumenti come al solito, ma il parametro tool_use_behavior="auto" permette al modello di scegliere dal catalogo invece di caricare tutto in anticipo. Nell’esempio seguente, una richiesta per inviare un sollecito di pagamento non attiverà gli strumenti delle risorse umane, e viceversa.

from agents import Agent, Runner, function_tool

# Definisci molti strumenti
@function_tool
def create_invoice(client: str, amount: float) -> str:
    """Crea una fattura per un cliente."""
    return f"Fattura creata per {client}: €{amount}"

@function_tool
def send_reminder(invoice_id: str) -> str:
    """Invia un sollecito di pagamento per una fattura non saldata."""
    return f"Sollecito inviato per la fattura {invoice_id}"

@function_tool
def generate_hr_report(month: str) -> str:
    """Genera un report delle risorse umane per un dato mese."""
    return f"Report HR generato per {month}"

@function_tool
def schedule_interview(candidate: str, date: str) -> str:
    """Programma un colloquio di lavoro con un candidato."""
    return f"Colloquio programmato con {candidate} il {date}"

# Molti altri strumenti...

agent = Agent(
    name="Enterprise Agent",
    instructions="Gestisci le operazioni aziendali.",
    tools=[
        create_invoice,
        send_reminder,
        generate_hr_report,
        schedule_interview,
        # ... altri 50 strumenti
    ],
    tool_use_behavior="auto",  # Il modello seleziona dinamicamente
)

Pattern: Selezione Manuale degli Strumenti

Se desideri il controllo totale sulla selezione degli strumenti, implementa la tua logica. Il principio è semplice: un piccolo agente router legge la richiesta e nomina semplicemente il dominio rilevante. Costruisci quindi l’agente specializzato al volo con solo gli strumenti per quel dominio. Una frase come “invia un sollecito per la fattura F-2026-114” esce dal router con la risposta accounting, e l’agente di esecuzione non vede mai gli strumenti HR.

from agents import Agent, Runner, function_tool

# Raggruppa gli strumenti per dominio
accounting_tools = [create_invoice, send_reminder]
hr_tools = [generate_hr_report, schedule_interview]

# Un agente router che seleziona il dominio
router = Agent(
    name="Router",
    instructions="""Determina il dominio della richiesta.
    Rispondi solo con 'accounting' o 'hr'.""",
    model="gpt-5.6-terra",  # Veloce ed economico per il routing
    output_type=str,
)

async def handle_request(message: str):
    # Passo 1: Determina il dominio
    route = await Runner.run(router, message)
    domain = route.final_output.strip().lower()

    # Passo 2: Crea l'agente specializzato con gli strumenti giusti
    if domain == "accounting":
        tools = accounting_tools
        instructions = "Gestisci la contabilità aziendale."
    elif domain == "hr":
        tools = hr_tools
        instructions = "Gestisci le risorse umane."
    else:
        tools = accounting_tools + hr_tools
        instructions = "Gestisci le operazioni aziendali."

    specialized_agent = Agent(
        name=f"{domain.capitalize()} Agent",
        instructions=instructions,
        tools=tools,
        model="gpt-5.6-terra",
    )

    result = await Runner.run(specialized_agent, message)
    return result.final_output

L’uso di gpt-5.6-terra sia per il routing che per l’esecuzione appartiene alla generazione precedente di modelli; il ragionamento alla base del pattern rimane identico con la famiglia GPT-5.6, dove le impostazioni di sforzo distinguono il router veloce dall’esecutore.

Pattern: Strumenti Dinamici Consapevoli del Contesto

La selezione non dipende solo dalla domanda posta, ma anche da chi la pone. Puoi adattare gli strumenti disponibili in base all’utente loggato, ottenendo due risultati con un solo sforzo: meno token inviati e, soprattutto, controlli di accesso applicati prima ancora che il modello ragioni. Un impiegato commerciale ottiene strumenti di preventivo, ma delete_account semplicemente non esiste nel suo agente.

from dataclasses import dataclass

@dataclass
class UserContext:
    role: str  # "admin", "manager", "employee"
    department: str

def get_tools_for_role(ctx: UserContext) -> list:
    """Restituisce gli strumenti autorizzati in base al ruolo."""
    base_tools = [search_document, view_schedule]

    if ctx.role in ("admin", "manager"):
        base_tools.extend([create_invoice, generate_hr_report])

    if ctx.role == "admin":
        base_tools.extend([modify_permissions, delete_account])

    if ctx.department == "sales":
        base_tools.extend([search_client, create_quote])

    return base_tools

async def create_agent_for_user(ctx: UserContext):
    tools = get_tools_for_role(ctx)
    return Agent(
        name="Custom Agent",
        instructions=f"Assisti un {ctx.role} nel dipartimento {ctx.department}.",
        tools=tools,
        model="gpt-5.6-terra",
    )

Ottimizzare le Descrizioni degli Strumenti

Qualunque meccanismo di selezione tu scelga, si basa su un unico materiale: il testo delle tue descrizioni. La qualità di queste descrizioni impatta direttamente sulla rilevanza della selezione. Confronta le due dichiarazioni seguenti: la prima non dice nulla sullo scenario d’uso, mentre la seconda nomina gli input, l’output e quando usarlo.

# Male: descrizione vaga
@function_tool
def process_data(data: str) -> str:
    """Elabora i dati."""
    return "OK"

# Bene: descrizione precisa e contestualizzata
@function_tool
def calculate_gross_margin(revenue: float, production_cost: float) -> str:
    """Calcola il margine lordo in percentuale dai ricavi
    e dal costo di produzione. Utile per l'analisi finanziaria trimestrale."""
    margin = ((revenue - production_cost) / revenue) * 100
    return f"Margine lordo: {margin:.1f}% (Ricavi: €{revenue}, Costi: €{production_cost})"

Una buona descrizione di uno strumento è come un buon docstring: spiega quando usare lo strumento, non solo cosa fa. Prenditi dieci minuti per rivedere le descrizioni del tuo agente, chiedendoti per ognuna se un collega potrebbe scegliere lo strumento giusto leggendo solo quella frase. Questo è esattamente l’esercizio che svolge il modello.

Punti chiave

  • La Ricerca Strumenti seleziona dinamicamente gli strumenti rilevanti per ogni richiesta
  • Con molti strumenti, un agente router può determinare il dominio in anticipo
  • Adatta gli strumenti disponibili in base al ruolo e al contesto dell’utente
  • La qualità della descrizione dello strumento impatta sulla precisione della selezione
  • Usa un modello leggero per un routing veloce e un modello capace per l’esecuzione