Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Dichiarare gli strumenti nell'SDK

Lezione 6 di 25 Aggiornata il 2 novembre 2026 Sviluppatore
In questa pagina
  1. Dichiarare gli strumenti nell’SDK
  2. Il decoratore @function_tool
  3. Personalizzare nome e descrizione
  4. Tipi di parametri supportati
  5. Restituire risultati strutturati
  6. Strumenti ospitati da OpenAI
  7. Combinare strumenti personalizzati e ospitati
  8. Punti chiave

Dichiarare gli strumenti nell’SDK

Gli strumenti sono le capacità concrete del tuo agente. Senza strumenti, un agente può solo generare testo; con gli strumenti, può interrogare database, chiamare API e inviare email. Devi però dichiararli correttamente, perché la qualità di uno strumento non dipende solo dal suo codice, ma anche da quanto bene il modello lo comprende.

Il decoratore @function_tool

Il modo più semplice per creare uno strumento è il decoratore @function_tool, che trasforma una normale funzione Python in una capacità che l’agente può invocare.

from agents import function_tool

@function_tool
def search_customer(email: str) -> str:
    """Search for a customer by email address in the database.

    Args:
        email: The customer's email address to search for.
    """
    # In production: call your database
    customers = {
        "[email protected]": {"name": "Alice Dupont", "plan": "Pro", "since": "2024"},
        "[email protected]": {"name": "Bob Martin", "plan": "Starter", "since": "2025"},
    }
    customer = customers.get(email)
    if customer:
        return f"Customer found: {customer['name']}, plan {customer['plan']}, customer since {customer['since']}"
    return f"No customer found with email {email}"

Nulla viene dichiarato due volte: l’SDK utilizza il nome della funzione come nome dello strumento, il docstring come descrizione e i type hints per generare lo schema JSON dei parametri. In altre parole, il tuo docstring non è più solo un commento per i colleghi; è il testo che il modello legge per decidere se chiamare questa funzione. Un docstring vago porta a chiamate imprecise.

Personalizzare nome e descrizione

Quando il nome della tua funzione segue convenzioni interne piuttosto che la logica di business, puoi sovrascrivere ciò che il modello vede.

@function_tool(
    name_override="search_crm",
    description_override="Search for a customer in the CRM by email, name, or account number."
)
def search_customer(identifier: str) -> str:
    """Search for a customer."""
    # ...
    return "Result"

Tipi di parametri supportati

Oltre ai tipi nativi di Python, l’SDK accetta modelli Pydantic. Quando uno strumento richiede tre o più parametri, raggruppali: lo schema diventa più leggibile per il modello e la convalida ti protegge da valori anomali.

from pydantic import BaseModel, Field
from typing import Optional
from agents import function_tool

class SearchFilter(BaseModel):
    category: str = Field(description="Product category")
    max_price: Optional[float] = Field(None, description="Maximum price in euros")
    in_stock: bool = Field(True, description="Only products in stock")

@function_tool
def search_products(filter: SearchFilter) -> str:
    """Search for products based on specified criteria."""
    results = []
    # Search logic using filter.category, filter.max_price, etc.
    return f"Found {len(results)} products in {filter.category}"

I modelli Pydantic convalidano automaticamente gli input e forniscono al modello descrizioni ricche, campo per campo.

Restituire risultati strutturati

Uno strumento restituisce sempre una stringa. Quando i tuoi dati hanno una struttura—metriche multiple, una lista, tipi misti—serializzali come JSON invece di comporre una frase: il modello leggerà le chiavi in modo molto più affidabile rispetto al testo libero.

import json
from agents import function_tool

@function_tool
def get_sales_stats(month: str, year: int) -> str:
    """Retrieve sales statistics for a given month."""
    stats = {
        "month": month,
        "year": year,
        "revenue": 145000,
        "sales_count": 342,
        "avg_basket": 423.98,
        "top_products": ["Laptop Pro", "Tablet Air", "Monitor 4K"]
    }
    return json.dumps(stats, ensure_ascii=False, indent=2)

Strumenti ospitati da OpenAI

Oltre alle tue funzioni personalizzate, l’SDK fornisce accesso a strumenti gestiti da OpenAI che vengono eseguiti lato piattaforma.

from agents import Agent, WebSearchTool, FileSearchTool, CodeInterpreterTool

agent = Agent(
    name="General-purpose assistant",
    instructions="You are an assistant capable of searching the web, analyzing files, and executing code.",
    tools=[
        WebSearchTool(),
        FileSearchTool(
            vector_store_ids=["vs_abc123"],
            max_num_results=10,
        ),
        CodeInterpreterTool(tool_config={"type": "code_interpreter", "container": {"type": "auto"}}),
    ],
)

WebSearchTool permette all’agente di cercare su Internet in tempo reale e non richiede alcuna configurazione. FileSearchTool esegue una ricerca semantica tra i tuoi file, ma presuppone una configurazione preliminare: devi creare un vector store tramite le API di OpenAI e caricarvi i tuoi documenti, da qui il vs_abc123 passato come parametro. CodeInterpreterTool consente all’agente di scrivere ed eseguire codice Python in un container isolato, rendendolo la scelta ideale per l’analisi dei dati e la generazione di grafici. Richiede un tool_config che specifichi questo container: {"type": "auto"} lo crea su richiesta (l’SDK openai-agents rifiuta CodeInterpreterTool() senza di esso).

Combinare strumenti personalizzati e ospitati

La vera potenza risiede nella combinazione. Un analista finanziario ha bisogno dei tuoi dati interni, delle capacità di calcolo e del contesto di mercato: tre fonti che nessun singolo strumento copre da solo.

agent = Agent(
    name="Financial analyst",
    instructions="""You are a financial analyst.
    Use internal tools to retrieve data,
    the code interpreter to analyze it,
    and web search for market context.""",
    tools=[
        get_sales_stats,
        search_customer,
        WebSearchTool(),
        CodeInterpreterTool(tool_config={"type": "code_interpreter", "container": {"type": "auto"}}),
    ],
)

Nota come le istruzioni specifichino a cosa serve ogni famiglia di strumenti. Senza questa chiarezza, un agente con quattro strumenti esita, ne prova due inutilmente e aumenta la latenza senza motivo.

Punti chiave

  • @function_tool trasforma una funzione Python in uno strumento per l’agente
  • Il docstring e i type hints generano automaticamente lo schema JSON
  • Usa Pydantic per parametri complessi con convalida
  • Gli strumenti restituiscono sempre stringhe (JSON se strutturati)
  • Combina i tuoi strumenti personalizzati con WebSearchTool, FileSearchTool e CodeInterpreterTool