Aggiunta di strumenti

La pagina precedente ha mostrato come incapsulare un LLM in un agente possa fornire un'identità persistente, delle istruzioni e la gestione delle sessioni. Ma anche con tutto questo, l'agente può generare solo contenuto (testo, immagini e così via), non può cercare il prezzo azionario di oggi, inviare un messaggio di posta elettronica o eseguire query sul database. Risponde a qualsiasi informazione inserita durante il training e a qualsiasi contesto fornito nella richiesta.

Gli strumenti consentono di colmare questo divario. Offrono all'agente la possibilità di agire , per raggiungere oltre i dati di training e interagire con il mondo reale. L'aggiunta di strumenti è il singolo passaggio più significativo che è possibile eseguire per rendere un agente veramente utile.

Quando usare questa opzione

Aggiungi strumenti al tuo agente quando:

  • L'agente deve accedere a dati in tempo reale o esterni , ovvero prezzi in tempo reale, meteo, record di database, risultati della ricerca, che non si trovano nei dati di training del modello.
  • L'agente deve eseguire azioni , ovvero l'invio di messaggi di posta elettronica, la creazione di ticket, la chiamata di API, la scrittura di file, piuttosto che la semplice produzione di contenuti.

Considerazioni

Considerazione dettagli
Latenza Ogni chiamata di funzione aggiunge un round trip: il modello genera una richiesta di funzione, il tuo codice lo esegue e il risultato viene inviato prima che il modello possa procedere. Il multi-strumento modifica il composto.
Overhead del token Le definizioni degli strumenti (nomi, descrizioni, schemi di parametri) sono incluse in ogni richiesta. Altri strumenti indicano un minor numero di token disponibili per la cronologia delle conversazioni e la risposta del modello.
Analisi della complessità Quando si verifica un errore, la causa potrebbe essere nella selezione dello strumento del modello, negli argomenti scelti o nell'esecuzione dello strumento. Si sta eseguendo il debug del ragionamento e del codice insieme.
Affidabilità Il modello può chiamare gli strumenti in modo non corretto, passare argomenti non validi o richiamare uno strumento quando non dovrebbe. Le buone descrizioni e l'approvazione degli strumenti mitigano questo, ma non lo eliminano.

Perché gli agenti necessitano di strumenti

Come descritto in LLM Fundamentals, un LLM viene addestrato per generare token, incluso un formato strutturato speciale che rappresenta un'invocazione di uno strumento. Ma il modello stesso non esegue mai nulla. Si tratta dell'applicazione (o di Agent Framework) che analizza l'output del modello, esegue la funzione effettiva e restituisce il risultato.

Ciò significa che gli strumenti non modificano ciò che il modello è , ma modificano le operazioni che l'agente può eseguire. Senza strumenti, un agente è un conversatore. Con gli strumenti diventa un operatore.

Si consideri un agente di prenotazione viaggi. Senza strumenti, può discutere i voli e suggerire itinerari basati su conoscenze generali. Con gli strumenti, può:

  • Cerca un'API per la disponibilità e i prezzi in tempo reale
  • Prenotare un volo per conto dell'utente

Ognuna di queste azioni richiede uno strumento, ovvero un frammento di codice che l'agente può richiamare per interagire con il mondo esterno.

Funzionamento del ciclo di chiamata degli strumenti

Quando si assegnano strumenti agente, Agent Framework gestisce automaticamente un ciclo di chiamata degli strumenti:

┌──────────────────────────────────────────────────────┐
│  User: "What's the weather in Seattle?"              │
└──────────────┬───────────────────────────────────────┘
               ▼
┌──────────────────────────────────────────────────────┐
│  Agent sends messages + tool definitions to LLM      │
└──────────────┬───────────────────────────────────────┘
               ▼
       ┌───────────────┐
       │ LLM responds  │
       └───┬───────┬───┘
           │       │
     Tool call?    No ──────────────────────────┐
           │                                    │
           ▼                                    ▼
┌─────────────────────────────┐   ┌─────────────────────────────┐
│  Agent Framework executes   │   │  Final response:            │
│  the tool (e.g.,            │   │  "It's cloudy in Seattle    │
│  get_weather("Seattle"))    │   │   with a high of 15°C."     │
└──────────────┬──────────────┘   └─────────────────────────────┘
               │
               ▼
┌─────────────────────────────┐
│  Agent sends tool result    │
│  back to the LLM            │
└──────────────┬──────────────┘
               │
               └──────► (back to "LLM responds")

Diagramma che mostra il ciclo di chiamata degli strumenti: LLM interagisce con strumenti esterni e memoria in un ciclo prima di restituire una risposta finale.

Punti principali:

  1. Non è necessario scrivere il ciclo. Agent Framework gestisce il rilevamento delle chiamate degli strumenti nella risposta del modello, l'esecuzione degli strumenti e l'inserimento dei risultati. Definisci gli strumenti; il framework orchestra il resto.
  2. Più chiamate di strumenti a turno. Il modello può chiamare diversi strumenti (potenzialmente in parallelo) prima di produrre una risposta finale , o chiamate di strumenti a catena in cui l'output di uno informa il successivo.
  3. Il modello decide quando chiamare gli strumenti. In base alla richiesta dell'utente e alle descrizioni degli strumenti fornite, il modello giudica se è necessario uno strumento. Le descrizioni degli strumenti migliori portano a una migliore selezione degli strumenti.

Suggerimento

Per una procedura dettagliata sull'aggiunta del primo strumento e sulla visualizzazione di questo ciclo in azione, vedere Passaggio 2: Aggiungere strumenti nell'esercitazione Introduttiva.

Tipi di strumenti

Agent Framework supporta diverse categorie di strumenti. Scegliere quello giusto dipende da cosa deve fare l'agente e da dove si trova la funzionalità.

Strumenti per le funzioni

Gli strumenti per le funzioni sono funzioni personalizzate scritte e registrate con l'agente. Vengono eseguiti nel vostro processo, offrendo il controllo completo sulla logica, sui limiti di sicurezza e sulla gestione degli errori.

Utilizzare gli strumenti delle funzioni quando:

  • È disponibile una logica di business personalizzata che l'agente deve richiamare (eseguire query su un database, chiamare un'API interna, eseguire un calcolo)
  • È necessario che tu esegua lo strumento nel tuo ambiente con accesso alle tue risorse.
  • Si vuole verificare la sicurezza e la verificabilità dei tipi in fase di compilazione

Gli strumenti per le funzioni sono il tipo di strumento più comune e flessibile. La maggior parte degli agenti inizia qui.

Informazioni di riferimento sugli strumenti per le funzioni

Strumenti MCP (Model Context Protocol)

MCP è uno standard aperto che definisce il modo in cui le applicazioni forniscono strumenti ai modelli linguistici di grandi dimensioni. Invece di scrivere manualmente la logica degli strumenti, ci si connette a un server MCP che espone un set di strumenti su un protocollo standard, in modo analogo a come un'API REST espone gli endpoint.

Agent Framework supporta due versioni:

Sapore Che cos'è Quando usarlo
Strumenti MCP ospitati Server MCP ospitati e gestiti da Microsoft Foundry o da altri provider Si vuole l'accesso chiavi in mano alle funzionalità comuni (ad esempio, ricerca di file, esecuzione del codice) senza gestire l'infrastruttura
Strumenti MCP locali Server MCP che gestisci tu stesso o connessi da qualsiasi provider Si dispone di un server MCP personalizzato o di terze parti oppure sono necessari strumenti eseguiti nel proprio ambiente

Usare gli strumenti MCP quando:

  • Un server MCP predefinito offre già la funzionalità necessaria
  • Si vogliono riutilizzare gli strumenti in più agenti o applicazioni tramite un server condiviso
  • Stai integrando con un servizio di terze parti che offre un endpoint MCP

Informazioni di riferimento sugli strumenti MCP ospitati- Informazioni di riferimento sugli strumenti MCP locali

Strumenti ospitati dal provider

Alcuni provider offrono strumenti predefiniti eseguiti nell'infrastruttura del provider, senza richiedere codice locale. Questi includono:

Strumento Funzionamento
Interprete di codice Esegue il codice in un ambiente in modalità sandbox nell'infrastruttura del provider
Ricerca file Cerca i file caricati nel provider
Ricerca Web Cerca nel Web informazioni in tempo reale

Usare gli strumenti ospitati dal provider quando:

  • Sono necessarie funzionalità come l'esecuzione del codice o la ricerca Web senza compilare o ospitare manualmente lo strumento
  • Il provider offre già una versione gestita che soddisfa i requisiti

Annotazioni

La disponibilità degli strumenti ospitati dal provider varia in base al provider. Per la matrice di supporto completo del provider, vedere Panoramica degli strumenti .

Annotazioni

Alcuni provider LLM possono eseguire strumenti ospitati nell'infrastruttura durante l'inferenza, ad esempio l'API Risposte di OpenAI. Si considerino questi servizi di inferenza come servizi semi agentici che combinano l'inferenza con l'esecuzione degli strumenti. Non cambia il funzionamento del modello sottostante, ma significa che l'esecuzione degli strumenti può avvenire come parte della generazione della risposta del servizio. Questi servizi non possono eseguire strumenti locali, che devono essere eseguiti nella propria infrastruttura.

Scelta del tipo di strumento corretto

Domanda Raccomandazione
Dispongo di una logica di business personalizzata? Strumenti per le funzioni : scrivere e registrare funzioni personalizzate
Esiste un server MCP che esegue già le operazioni necessarie? MCP tools connettersi al server anziché crearlo da zero, ad esempio GitHub server MCP
È necessaria l'esecuzione del codice, la ricerca di file o la ricerca Web? Strumenti ospitati dal provider: verificare se il provider li supporta
Sono necessari strumenti di più categorie? Combinarli : gli agenti possono usare gli strumenti per le funzioni, gli strumenti MCP e gli strumenti ospitati dal provider contemporaneamente

Le descrizioni degli strumenti sono importanti

Il modello seleziona gli strumenti in base ai nomi e alle descrizioni. Una descrizione vaga porta a una scarsa selezione degli strumenti: il modello può chiamare lo strumento sbagliato, ignorare uno strumento che deve usare o passare argomenti non corretti.

Scrivere descrizioni degli strumenti nello stesso modo in cui scrivere un documento dell'API: dire cosa fa lo strumento, cosa significa ogni parametro e cosa restituisce. Più chiara è la descrizione, migliore è il giudizio del modello.

Suggerimento

Le definizioni degli strumenti (nomi, descrizioni, schemi di parametri) sono incluse nel prompt e usano i token nella finestra di contesto. Se si registrano molti strumenti, il sovraccarico può essere significativo. Registrare solo gli strumenti necessari all'agente.

Approvazione degli strumenti: con supervisione umana

Alcune azioni sono sensibili: trasferimento di denaro, eliminazione di record, invio di messaggi di posta elettronica. È possibile che l'agente non voglia eseguire questi strumenti in modo autonomo. L'approvazione dello strumento consente di richiedere una conferma umana prima dell'esecuzione di uno strumento.

Quando uno strumento viene contrassegnato come richiede l'approvazione, l'agente sospende l'esecuzione e restituisce una risposta che indica che è necessaria l'approvazione. L'applicazione è responsabile di presentare questo all'utente e di restituire la loro decisione.

Questo modello viene spesso chiamato human-in-the-loop ed è essenziale per la creazione di agenti affidabili che gestiscono azioni consequenziali.

Informazioni di riferimento sulle approvazioni degli strumenti

Inconvenienti comuni

Trappola Linee guida
Troppi strumenti Ogni definizione dello strumento utilizza i token. Registrare solo gli strumenti rilevanti per lo scopo dell'agente.
Descrizioni vaghe "Esegue operazioni sui dati" non aiuterà il modello. Specifica: "Esegue una query sul database di inventario per la disponibilità del prodotto in base allo SKU".
Nessuna gestione degli errori Gli strumenti possono avere esito negativo (errori di rete, input non valido). Restituisce messaggi di errore chiari in modo che il modello possa ragionare su ciò che è andato storto e riprovare o informare l'utente.
Strumenti eccessivamente permissivi Uno strumento che può "eseguire qualsiasi query SQL" è un rischio per la sicurezza. Strumenti di ambito per operazioni specifiche e ben definite.
Approvazione mancante per le azioni sensibili Se uno strumento può apportare modifiche irreversibili, aggiungere l'approvazione dello strumento per mantenere un essere umano nel ciclo.

Menzione speciale: Strumento interprete del codice

Come descritto in LLM Fundamentals, gli LLM possono generare errori in calcoli precisi e logica formale. Ciò è dovuto al fatto che i LLM generano risposte un token alla volta basandosi sulla ricerca di modelli — non eseguono realmente calcoli. Un LLM a cui è stato chiesto di moltiplicare due numeri grandi non esegue l'aritmetica; prevede come appare la risposta in base ai dati di addestramento. Questo funziona spesso sorprendentemente, ma fallisce in modo imprevedibile nei casi limite.

L'interprete del codice risolve questo problema consentendo all'agente di scrivere ed eseguire codice in un ambiente in modalità sandbox. Invece di indovinare la risposta, il modello scrive uno script Python che lo calcola esattamente, lo esegue e usa il risultato verificato nella risposta.

Annotazioni

Il modello può scrivere uno script leggermente diverso ogni volta che viene richiesto di risolvere lo stesso problema, ma i risultati devono essere principalmente coerenti.

Avvertimento

L'interprete del codice non è un sostituto per un attento ragionamento da parte umana. Controllare sempre il lavoro dell'agente e verificare i risultati in modo indipendente quando necessario.

Fornisci al tuo agente l'interprete del codice quando è necessario:

  • Eseguire calcoli precisi , ovvero modellazione finanziaria, analisi statistica, conversioni di unità, in cui una "migliore ipotesi" approssimativa non è accettabile.
  • Trasforma o analizza i dati — analizza file CSV, aggrega righe, genera grafici o rimodella i dati strutturati.
  • Elaborare i file : leggere i documenti caricati, estrarre contenuto, convertire i formati o generare nuovi file.
  • Convalidare il proprio ragionamento : scrivere codice di test per verificare un'attestazione logica prima di presentarla all'utente.

Suggerimento

L'interprete del codice può essere uno strumento ospitato dal provider: il codice viene eseguito nell'infrastruttura del provider in una sandbox, non nell'ambiente in uso. In questo modo è possibile usare senza preoccuparsi di codice arbitrario in esecuzione nei server. Per informazioni dettagliate sull'installazione, vedere le informazioni di riferimento sull'interprete del codice .

Passaggi successivi

Una volta che l'agente ha strumenti, il passaggio successivo consiste nell'apprendere le competenze , ovvero pacchetti portabili di istruzioni, materiale di riferimento e script che forniscono agli agenti competenze sul dominio che possono caricare su richiesta.

Aggiungere competenze

Approfondimento:

  • Last updated on