Definire gli strumenti per il proprio agente
Creerà strumenti personalizzati con il decorator @tool, scriverà descrizioni chiare che l'LLM utilizzerà per decidere quando chiamare ciascuno strumento e aggiungerà la validazione dell'input con Pydantic.
Definire gli strumenti per il proprio agente è una lezione AI Engineering Academy gratuita su CoddyKit. Questa è la lezione 2 di 4. Puoi leggere la lezione completa qui gratuitamente — poi esercitati direttamente nel browser con un editor di codice integrato e un tutor IA disponibile 24/7. Fa parte del percorso di apprendimento AI Engineering Academy, e i tuoi progressi si sincronizzano tra il web e l'app CoddyKit. Il corso AI Engineering Academy include 4 lezioni in totale.
Gli strumenti danno superpoteri agli agenti
Un agente privo di strumenti può ragionare solo su ciò che già conosce: non può cercare sul Web, interrogare un database o inviare un'e-mail. Gli strumenti sono funzioni Python che estendono le capacità dell'agente, consentendogli di compiere azioni nel mondo reale e recuperare informazioni aggiornate. Definire gli strumenti in modo chiaro è uno dei passaggi più importanti per creare un agente affidabile.
Il decoratore @tool in LangChain
Il decoratore @tool di LangChain trasforma qualsiasi funzione Python in uno strumento che l'agente può chiamare. La docstring della funzione diventa la descrizione dello strumento che l'LLM usa per decidere quando chiamarlo. Una descrizione chiara e specifica migliora notevolmente la precisione con cui l'agente seleziona gli strumenti.
from langchain_core.tools import tool
@tool
def get_weather(city: str) -> str:
'''Get the current weather conditions for a given city.
Use this tool when the user asks about weather in a specific location.
Input should be just the city name, e.g. 'London' or 'New York'.
'''
# Real implementation would call a weather API
return f'The weather in {city} is 18 degrees Celsius and partly cloudy.'
print(get_weather.name) # 'get_weather'
print(get_weather.description) # The docstring aboveAnnotazioni di tipo e generazione dello schema
LangChain genera automaticamente uno JSON Schema per ogni strumento a partire dalle annotazioni di tipo Python. L'agente riceve questo schema nel prompt di sistema, così sa quali argomenti sono obbligatori, quali tipi hanno e quali vincoli devono rispettare. Annoti sempre le funzioni degli strumenti con tipi precisi.
from langchain_core.tools import tool
@tool
def calculate_compound_interest(
principal: float,
annual_rate: float,
years: int
) -> float:
'''Calculate compound interest earned over a number of years.
Args:
principal: Initial investment amount in dollars.
annual_rate: Annual interest rate as a decimal (e.g. 0.05 for 5%).
years: Number of years to compound.
Returns:
Final amount after compounding.
'''
return principal * (1 + annual_rate) ** years
# Inspect the auto-generated schema
print(calculate_compound_interest.args_schema.schema())Convalida degli input con Pydantic
Per gli strumenti con input complessi, definisca un modello Pydantic come args_schema. In questo modo ottiene automaticamente la convalida, la conversione dei tipi e una documentazione descrittiva a livello di campo, che l'LLM vede quando decide come chiamare lo strumento.
from langchain_core.tools import tool
from pydantic import BaseModel, Field
class SearchInput(BaseModel):
query: str = Field(description='The search query to look up.')
num_results: int = Field(default=5, ge=1, le=20, description='Number of results to return (1-20).')
@tool(args_schema=SearchInput)
def web_search(query: str, num_results: int = 5) -> str:
'''Search the web for current information on any topic.
Use this for facts that may have changed after the model training cutoff.
'''
return f'Searching for "{query}", returning {num_results} results...'Scrivere descrizioni efficaci degli strumenti
La descrizione dello strumento è la parte più importante della Sua definizione: l'LLM la legge per decidere quando e come chiamare lo strumento. Una buona descrizione risponde alle seguenti domande: che cosa fa questo strumento? Quando deve essere utilizzato? Quale deve essere il formato dell'input? Quale sarà l'output?
- Errata: «Strumento di ricerca.»
- Corretta: «Cerca sul Web notizie, fatti o dati aggiornati. Utilizzalo quando l'utente chiede informazioni su eventi recenti o fatti non presenti nei dati di addestramento. Input: una query di ricerca concisa.»
Tipi restituiti dagli strumenti
Gli strumenti possono restituire stringhe, dizionari o oggetti Pydantic strutturati. Tuttavia, alla fine l'agente ha bisogno del risultato come testo per includerlo nella conversazione. Se restituisce un dict, LangChain lo serializza in una stringa. Per dati annidati complessi, li formatti come un riepilogo leggibile anziché come JSON grezzo, così da aiutare il modello a ragionarci.
from langchain_core.tools import tool
import json
@tool
def get_stock_price(ticker: str) -> str:
'''Look up the current stock price for a given ticker symbol.
Input should be the stock ticker symbol in uppercase, e.g. AAPL or MSFT.
'''
# Stub — real implementation calls a financial API
data = {'ticker': ticker, 'price': 182.50, 'currency': 'USD', 'change': '+1.2%'}
return f'{ticker}: ${data["price"]} ({data["change"]})'Gestire gli errori degli strumenti in modo appropriato
Gli strumenti possono non funzionare. Le API possono diventare indisponibili, possono verificarsi timeout di rete e gli utenti possono fornire input non validi. Invece di lasciare che le eccezioni interrompano il ciclo dell'agente, racchiuda la logica dello strumento in un blocco try/except e restituisca una stringa di errore descrittiva. L'agente potrà quindi ragionare sul problema e decidere se riprovare o adottare un approccio diverso.
from langchain_core.tools import tool
import requests
@tool
def fetch_url(url: str) -> str:
'''Fetch the text content of a web page given its URL.
Use for accessing specific documents or web pages the user references.
'''
try:
resp = requests.get(url, timeout=10)
resp.raise_for_status()
return resp.text[:2000] # Return first 2000 chars
except requests.Timeout:
return 'Error: Request timed out after 10 seconds.'
except requests.HTTPError as e:
return f'Error: HTTP {e.response.status_code}'
except Exception as e:
return f'Error fetching URL: {str(e)}'Strumenti asincroni
Quando l'agente esegue molte chiamate agli strumenti o quando gli strumenti effettuano richieste di rete con attese I/O, definisca funzioni degli strumenti asincrone per evitare di bloccare il ciclo degli eventi. L'agent executor di LangChain supporta nativamente gli strumenti asincroni: Le basta usare async def nella funzione dello strumento.
from langchain_core.tools import tool
import httpx
@tool
async def async_fetch(url: str) -> str:
'''Asynchronously fetch content from a URL.
Preferred over fetch_url when making multiple concurrent requests.
'''
async with httpx.AsyncClient(timeout=10) as client:
try:
resp = await client.get(url)
resp.raise_for_status()
return resp.text[:2000]
except Exception as e:
return f'Error: {str(e)}'Organizzare gli strumenti in un toolkit
Quando dispone di molti strumenti correlati, li raggruppi in un toolkit: una classe che restituisce un elenco di strumenti. I toolkit di LangChain seguono uno schema comune: accettano configurazioni come le chiavi API nel costruttore ed espongono un metodo get_tools(). In questo modo la gestione degli strumenti rimane ordinata e riutilizzabile tra agenti diversi.
from langchain_core.tools import BaseTool
from typing import List
class WeatherToolkit:
def __init__(self, api_key: str):
self.api_key = api_key
def get_tools(self) -> List[BaseTool]:
return [
get_weather, # defined earlier with @tool
get_weather_forecast, # another tool
get_weather_alert # another tool
]
# Usage
toolkit = WeatherToolkit(api_key='your_weather_api_key')
tools = toolkit.get_tools()
print(f'Loaded {len(tools)} weather tools')Limitare l'accesso agli strumenti in base al ruolo dell'utente
Non tutti gli utenti dovrebbero avere accesso a ogni strumento. Un utente con accesso in sola lettura non dovrebbe poter attivare uno strumento send_email o delete_record. Implementi l'accesso agli strumenti basato sui ruoli selezionando gli strumenti da passare all'agente in base alle autorizzazioni dell'utente autenticato.
def get_tools_for_user(user_role: str) -> list:
read_tools = [web_search, get_weather, calculate_compound_interest]
write_tools = [send_email, create_calendar_event, update_record]
if user_role == 'admin':
return read_tools + write_tools
elif user_role == 'member':
return read_tools
else:
return [web_search] # Guest: only public searchBest practice per la documentazione degli strumenti
Gli strumenti ben documentati riducono drasticamente gli errori dell'agente. Segua queste best practice: utilizzi un nome chiaro che inizi con un verbo (search_web, non websearch), descriva esplicitamente il formato di input previsto, specifichi quando NON utilizzare lo strumento per evitare falsi positivi e descriva l'aspetto dell'output, in modo che il modello possa analizzarlo correttamente.
Verifica rapida
Verifichi la Sua comprensione della definizione degli strumenti per gli agent LangChain.
Riepilogo della lezione
In questa lezione ha imparato che: il decoratore @tool trasforma le funzioni Python in strumenti richiamabili dall'agente, utilizzando le relative docstring come descrizioni, gli schemi Pydantic aggiungono input tipizzati e convalidati e gli strumenti dovrebbero gestire gli errori in modo appropriato restituendo stringhe di errore descrittive. Ora assembleremo un agent ReAct completo con LangChain e ne tracceremo i passaggi di ragionamento.
Domande Frequenti
La lezione «Definire gli strumenti per il proprio agente» è gratuita?
Sì — il testo completo di «Definire gli strumenti per il proprio agente» è gratuito qui sul web. Per esercitarvi in modo interattivo (un editor di codice integrato e un tutor IA 24/7) e sbloccare il resto del corso AI Engineering Academy, passa a CoddyKit PRO. Il corso AI Engineering Academy include 4 lezioni in totale.
Cosa imparerò in «Definire gli strumenti per il proprio agente»?
Creerà strumenti personalizzati con il decorator @tool, scriverà descrizioni chiare che l'LLM utilizzerà per decidere quando chiamare ciascuno strumento e aggiungerà la validazione dell'input con Pyd… Eserciti AI Engineering Academy con codice pratico che esegui direttamente nel browser, e un tutor IA 24/7 risponde alle tue domande mentre lavori sulla lezione.
Ho bisogno di esperienza per iniziare AI Engineering Academy?
Non è richiesta alcuna esperienza precedente. AI Engineering Academy su CoddyKit è strutturato per principianti e studenti avanzati, quindi puoi iniziare da qui o dall'inizio e procedere al tuo ritmo. Questa è la lezione 2 di 4.
Quanto tempo richiede la lezione «Definire gli strumenti per il proprio agente»?
La maggior parte delle lezioni CoddyKit richiede circa 5–10 minuti. Ogni lezione è breve e interattiva, quindi fai progressi costanti e riprendi esattamente da dove hai lasciato su web e app.
Posso scrivere ed eseguire codice in questa lezione AI Engineering Academy?
Sì. Ogni lezione AI Engineering Academy include un editor di codice integrato, quindi scrivi ed esegui codice reale direttamente nel tuo browser e ricevi feedback istantaneo dall'IA — nessuna configurazione locale necessaria.
Tutte le lezioni di questo corso
- Il framework ReAct: pensare, agire, osservare
- Definire gli strumenti per il proprio agente
- Creare un agente ReAct con LangChain
- Gestire i fallimenti e i loop degli agenti