Dichiarare gli strumenti nell'SDK
In questa pagina
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_tooltrasforma 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