Aggiungere strumenti agli agenti personalizzati

Note

Questo articolo descrive le caratteristiche utilizzate negli agenti o nei flussi di agenti alimentati dall'imbracatura standard.

Gli strumenti sono mattoni fondamentali che permettono al tuo agente di interagire con sistemi esterni. Gli strumenti ampliano ciò che il tuo agente può fare, e il tuo agente può eseguire varie azioni in risposta a richieste degli utenti o trigger autonomi. Ogni strumento rappresenta una funzionalità specifica che l'agente può eseguire. Ad esempio, puoi dotare il tuo agente di strumenti che svolgono compiti come:

• Invia email usando il connettore Office 365 Outlook
• Controllare le condizioni meteorologiche e le previsioni correnti
• Leggere e scrivere dati da Dataverse
• Leggere e pubblicare messaggi in Teams

Meccanismi per aggiungere strumenti agli agenti

È possibile estendere le funzionalità dell'agente personalizzato aggiungendo uno o più strumenti. L'agente può usare gli strumenti per rispondere automaticamente agli utenti, usando l'orchestrazione generativa. Puoi anche chiamare strumenti esplicitamente dall'interno di un argomento.

Utilizzando l'orchestrazione generativa (attiva di default), il tuo agente può selezionare automaticamente lo strumento o l'argomento più appropriato, oppure cercare tra conoscenze per rispondere a un utente. Questa modalità di orchestrazione crea un'esperienza di conversazione più dinamica e intelligente.

Nella modalità classica (con l'orchestrazione generativa disattivata), un agente può usare solo gli argomenti per rispondere all'utente. Tuttavia, è comunque possibile progettare l'agente in modo che chiami gli strumenti in modo esplicito dall'interno degli argomenti.

Puoi utilizzare i seguenti meccanismi per aggiungere strumenti al tuo agente:

• Connettore: Connettiti a API e servizi proprietari utilizzando Power Platform Connectors per prelevare dati o eseguire azioni.
  • Connettore predefinito: scegli tra una selezione di connessioni predefinite su migliaia di API popolari di Microsoft e servizi diversi da Microsoft.
  • Connettore personalizzato: Definisci una connessione a un servizio o sistema personalizzato per abilitare opzioni di strumenti personalizzati utilizzando i Power Platform Connectors. Il connettore necessita delle autorizzazioni di visualizzazione e condivisione per l'organizzazione affinché l'agente usi il connettore.
• Flusso dell'agente: definisci un flusso dell'agente, incluse una o più azioni da eseguire.
• Prompt: prompt basato su modello a turno singolo che può fare riferimento alle informazioni fornite e generare codice per analizzare i dati.
• API REST: definisci una connessione a un'API REST e seleziona uno o più endpoint e metodi API da aggiungere come strumenti.
• Protocollo di contesto del modello: connettiti a un server MCP per accedere a strumenti e risorse.
• Utilizzo del computer: consente all'agente di interagire con qualsiasi sistema con un'interfaccia utente grafica, per siti Web e app desktop, selezionando pulsanti, scegliendo menu e immettendo testo nei campi sullo schermo.

Puoi anche utilizzare i seguenti meccanismi per aggiungere comportamenti simili a uno strumento al tuo agente:

• Skill di Azure servizio Bot: Contenitore per un insieme di strumenti correlati messi a disposizione tramite Azure servizio Bot.
• Strumenti del client: Inviare un evento di attività al client affinché il client esegua un'azione e restituisca una risposta.

Note

Le competenze nel contesto degli agenti alimentati dall'imbracatura standard non sono le stesse di quelle usate negli agenti di codifica. Puoi aggiungere competenze di coding agent solo agli agenti alimentati dall'harness GitHub Copilot.

Creare e aggiungere un nuovo strumento a livello di agente

La creazione di nuovi strumenti direttamente all'interno di Copilot Studio semplifica il processo di sviluppo e garantisce una corretta integrazione con l'agente. Gli strumenti integrati in un agente sono disponibili per una orchestrazione automatica nel corso delle conversazioni dell'agente.

1. Apri il tuo agente scegliendo Agenti nel riquadro di navigazione a sinistra e selezionando il tuo agente dall'elenco.

2. Passare alla pagina Strumenti per l'agente.

3. Selezionare Aggiungi uno strumento.

4. Nel pannello Aggiungi strumento , seleziona Nuovo strumento.

5. Seleziona il tipo di strumento da aggiungere dall'elenco visualizzato:

   • Prompt
   • Flusso dell'agente
   • Utilizzo del computer
   • Connettore personalizzato
   • Protocollo di contesto per i modelli
   • REST API (Interfaccia di Programmazione delle Applicazioni REST)

   

   Note

   Se la tua organizzazione ha bloccato uno strumento a causa delle politiche sui dati, non puoi selezionarlo. Scopri di più in Strumenti bloccati dalle politiche della tua organizzazione.

6. Esegui i passaggi di configurazione specifici per il tipo di strumento selezionato. Ad esempio, se si seleziona Prompt, è necessario seguire questa procedura:

   • Definire il modello di prompt e le istruzioni
   • Specificare i parametri di input
   • Configurare le origini di conoscenza
   • Impostare il formato di risposta e i vincoli

7. Seleziona Salva o Pubblica, in base alle esigenze, per creare il nuovo strumento.

8. Selezionare Aggiungi e configura. Lo strumento viene aggiunto al software agente. Viene visualizzata la pagina di configurazione per lo strumento. È possibile visualizzare e apportare modifiche alla configurazione dello strumento qui.

È possibile visualizzare il nuovo strumento nella pagina Strumenti per l'agente.

Strumenti bloccati dalle politiche della tua organizzazione

La tua organizzazione può utilizzare le politiche di governance per limitare quali strumenti e connettori sono disponibili in Copilot Studio.

Quando una policy dati blocca uno strumento, lo strumento appare disabilitato nel pannello Aggiungi strumento e non puoi selezionarlo. Seleziona accanto allo strumento disabilitato per vedere perché lo strumento non è disponibile.

Il messaggio identifica la restrizione politica che impedisce l'utilizzo dello strumento. Se hai bisogno di accesso a uno strumento bloccato, contatta il tuo amministratore.

Per altre informazioni, vedere Configurare i criteri dati per gli agenti.

Visualizzare e apportare modifiche alla configurazione dello strumento

Puoi visualizzare e modificare la configurazione del tuo strumento in qualsiasi momento. Vai alla pagina Strumenti del tuo agente e seleziona lo strumento dalla lista degli strumenti.

Si apre la pagina di configurazione per lo strumento. I dettagli vengono visualizzati in tre sezioni:

• dettagli
• Ingressi
• Completamento

Per i server MCP connessi come strumenti dell'agente, la pagina di configurazione è diversa da altri tipi di strumenti. La sezione Dettagli è simile, ma invece di Input e Completamento, sono disponibili le sezioni Strumenti e Risorse con informazioni su strumenti e risorse disponibili per il server MCP. Per altre informazioni, vedi Visualizzare strumenti e risorse in un server MCP esistente.

dettagli

Usa la sezione Dettagli per configurare i dati base del tuo strumento.

Visualizza e aggiorna le seguenti informazioni:

• Nome: nome dello strumento. Questo nome viene visualizzato nell'elenco degli strumenti per l'agente. Scegli un nome che indichi chiaramente la funzione dello strumento.

• Descrizione: descrizione dello strumento. L'orchestrazione generativa si basa su questa descrizione per determinare quando l'agente deve usare lo strumento. Scrivi descrizioni chiare e specifiche, incluse le operazioni che lo strumento esegue e quando deve essere usato.

• Ulteriori dettagli:

  • Permettere all'agente di decidere dinamicamente quando utilizzare lo strumento: quando selezioni questa opzione, l'agente può usare l'orchestrazione generativa per determinare quando utilizzare lo strumento. Se non selezioni questa opzione, l'agente usa lo strumento solo quando viene chiamato esplicitamente da un argomento. Per impostazione predefinita, questa opzione viene selezionata quando è abilitata l'orchestrazione generativa.
  • Chiedere all'utente finale prima di eseguire: nell'esperienza di chat dell'utente finale chiedere conferma all'agente prima di eseguire lo strumento. Questa opzione è impostata su No per impostazione predefinita.
  • Autenticazione: seleziona se usare le credenziali dell'utente (Utente finale) o dell'autore (Fornite dall'autore) per lo strumento. Per impostazione predefinita, viene applicata l'autenticazione utente.
  • Descrizione: Opzionalmente, aggiungi una descrizione dello strumento che l'agente mostra all'utente quando vuole eseguire lo strumento. Questa descrizione consente all'utente di sapere per cosa viene richiesta l'autenticazione.

Ingressi

Visualizza e configura gli input per il tuo strumento. Usa gli input per raccogliere informazioni dall'utente e compilare gli input richiesti per lo strumento. Le informazioni sono visualizzate come una tabella, con una riga per ogni input.

Per impostazione predefinita, il valore fill using column per ogni input è impostato su Riempimento dinamico con intelligenza artificiale. L'agente tenta di estrarre il valore dal contesto disponibile, ad esempio dal messaggio dell'utente. Se l'agente non trova un valore appropriato, genera una domanda da porre all'utente per un valore. Selezionare Personalizza per accedere ad altre personalizzazioni con granularità fine per la raccolta di input e la compilazione:

• Nome visualizzato e Descrizione: Come appare l'input all'utente.
• Identificare come: come viene interpretata la risposta dell'utente, ad esempio come stringa di testo o mappata a un'entità predefinita.
• Logica di ripetizione dei tentativi: se l'agente non identifica un'entità nell'istruzione dell'utente, può porre nuovamente la domanda.
• Convalida dell'input: configurare un comportamento di convalida aggiuntivo per l'input dell'utente oltre l'impostazione predefinita per il tipo di entità.

È anche possibile scegliere di eseguire l'override di un input con un valore esplicito anziché consentire all'agente di estrarlo. Per impostare un'override, imposta Compila usando su Valore personalizzato e immetti un valore, seleziona una variabile o usa una formula Power Fx. Se sovrascrivi un input, l'agente non chiede un valore all'utente.

Note

Dopo aver aggiornato un'azione del connettore, il tipo di uscita può rimanere irrisolto finché non si inseriscono tutti gli ingressi necessari del connettore. Inserisci i valori richiesti, salva l'argomento e poi controlla di nuovo le variabili di output.

Completamento

Seleziona cosa vuoi che accada quando lo strumento termina di funzionare.

Puoi consentire all'agente di generare automaticamente una risposta contestuale per un utente, in base alla query e al risultato dello strumento.

In alternativa, puoi scegliere di creare una risposta formattata specifica che lo strumento restituisca. Usa il selezionatore variabile per inserire riferimenti alle variabili di output dallo strumento. È anche possibile usare le formule di Power Fx per formattare la risposta.

Sotto Dopo l'esecuzione, seleziona come lo strumento dovrebbe rispondere all'utente dopo l'esecuzione:

• Non rispondere (impostazione predefinita): l'agente incorpora l'output dello strumento nella risposta.
• Scrivi la risposta con l'IA generativa: l'IA crea una risposta contestuale usando gli output degli strumenti.
• Invia una risposta specifica: Crea una risposta modello con inserimento variabile.
• Invia una carta adattiva: crea risposte ricche e interattive con pulsanti e azioni.

Configura quali variabili di output rendere disponibili all'agente e ad altri strumenti.

Selezione degli strumenti e raccolta di input

Quando si definisce uno strumento in Copilot Studio, si forniscono anche informazioni che ne descrivono lo scopo. Queste informazioni aiutano l'agente a capire quando utilizzare lo strumento. La descrizione dello strumento consente anche all'agente di orchestrazione di usare l'IA generativa per generare domande, in base alle esigenze, per raccogliere gli input. L'agente può usare le domande per raccogliere informazioni per riempire gli input necessari per usare lo strumento. Di conseguenza, non è necessario creare manualmente i nodi domanda per raccogliere tutti gli input necessari, ad esempio gli input in un flusso. L'agente di orchestrazione gestisce automaticamente la raccolta di input in fase di esecuzione.

L'agente considera diversi fattori per determinare la selezione degli strumenti:

• Nome e descrizione dello strumento
• Il contesto della conversazione corrente
• Finalità dell'utente derivata dal messaggio
• Input e output disponibili
• Utilizzo precedente dello strumento nella conversazione

Quando si utilizza la modalità generativa, di default, gli strumenti restituiscono le loro informazioni all'agente. Con la risposta dello strumento, l'agente può generare una risposta contestuale alla query dell'utente. In alternativa, puoi impostare uno strumento in modo che risponda sempre immediatamente, generando un messaggio o creando un messaggio esplicito.

Tip

Quando usi le domande generate da uno strumento, informa i tuoi utenti che l'intelligenza artificiale ha generato parte della conversazione.

Ad esempio, aggiungere un messaggio aggiuntivo nell'argomento sistema Avvio conversazione . Questo argomento determina il messaggio mostrato ai tuoi utenti quando inizia una nuova conversazione.

Chiamare uno strumento esistente dall'interno di un argomento

È possibile chiamare uno strumento in modo esplicito dall'interno di un argomento. A seconda del tuo caso d'uso, potresti usare il tuo strumento come parte di un argomento più ampio che utilizza più nodi. Oppure, come nell'esempio seguente, aggiungere un nodo di azione singola (strumento) a un argomento potrebbe essere tutto ciò di cui hai bisogno.

Per chiamare uno strumento dall'interno di un argomento:

1. In Copilot Studio passare alla pagina Topics per l'agente da modificare.

2. Crea un nuovo argomento e dagli un nome, come Get Weather.

3. Aggiungi frasi di attivazione appropriate. Per continuare con lo stesso esempio meteo del passaggio precedente, le frasi trigger possono includere:

   • pioverà?
   • le previsioni di oggi
   • ottenere il meteo
   • che tempo fa

4. Selezionare Aggiungi nodo (+) e quindi aggiungi uno strumento.

5. Seleziona lo strumento dagli strumenti disponibili. Tre schede mostrano diversi tipi di strumenti:

   • Strumenti di base
   • Connettore
   • Tool

   Il nodo Azione viene ora aggiunto all'argomento.

6. Seleziona Salva.

Informazioni sul connettore MCP

Per il connettore MCP, puoi visualizzare i nomi e le descrizioni degli strumenti e delle risorse MCP che il connettore MCP mette a disposizione. Le informazioni sugli strumenti e le risorse compaiono in una tabella, con una riga per ogni strumento.

Considerazioni sull'autenticazione per gli strumenti

Alcuni strumenti richiedono l'autenticazione per funzionare correttamente, come Dynamic Prompt o altri strumenti che chiamano un'API Dataverse. La configurazione di autenticazione corretta garantisce la sicurezza mantenendo un'esperienza utente senza problemi.

L'agente esegue strumenti nel suo runtime nel contesto utente. Non puoi eseguire strumenti a meno che l'autenticazione non sia abilitata. L'agente supporta due tipi di metodi di autenticazione:

• Credenziali dell'utente finale: L'agente utilizza le credenziali dell'utente per autenticarsi con il servizio. Questo metodo garantisce agli utenti di accedere solo ai dati che sono autorizzati a visualizzare.
• Credenziali fornite dall'autore: l'agente usa le credenziali dell'autore per l'autenticazione con il servizio. Utilizza questa modalità di autenticazione per le risorse condivise o quando gli utenti non devono avere accesso individuale.

Testa lo strumento

Utilizzando l'orchestrazione generativa, l'orchestratore seleziona il tuo strumento quando lo ritiene rilevante per una query dell'utente.

In alternativa, è possibile chiamare uno strumento esistente dall'interno di un argomento.

Attivare o disattivare uno strumento nell'agente

Puoi attivare o disattivare uno strumento per l'agente dalla pagina di configurazione dello strumento. La disattivazione di uno strumento impedisce all'agente di usare lo strumento, ma lo strumento è ancora connesso all'agente e può essere riattivato in un secondo momento. Quando aggiungi uno strumento a un agente, lo strumento viene attivato di default.

Per disattivare uno strumento in un agente:

1. Vai all'agente e seleziona la pagina Strumenti per l'agente.
2. Seleziona lo strumento per passare alla pagina di configurazione dello strumento.
3. In cima alla pagina di configurazione, disattiva lo strumento usando l'opzione Abilitato .
4. Selezionare Salva per applicare la modifica.

Lo strumento viene ancora visualizzato nell'elenco degli strumenti dell'agente, ma non è più attivato.

Eliminare uno strumento dall'agente

La disattivazione di uno strumento impedisce l'uso dello strumento, ma offre anche la flessibilità necessaria per riattivarlo in un secondo momento. È possibile anche rimuovere in modo definitivo uno strumento dall'agente. Per eliminare uno strumento dall'agente:

1. Vai all'agente e seleziona la pagina Strumenti per l'agente.
2. Trova lo strumento nell'elenco degli strumenti e passa il puntatore del mouse sul nome dello strumento. Seleziona i tre puntini (...).
3. Seleziona Elimina. Viene visualizzata una nuova finestra di conferma.
4. Seleziona Elimina per rimuovere lo strumento.

Lo strumento scompare dall'elenco degli strumenti dell'agente.

Note

Puoi eliminare gli strumenti solo dalla pagina degli strumenti dell'agente. Non è possibile eliminare gli strumenti dalla pagina principale Copilot Studio Tools.

Limitazioni sugli strumenti negli agenti

• Quando si usa l'orchestrazione generativa, l'orchestratore supporta fino a 128 strumenti per agente. Per ottenere le migliori prestazioni e risultati, limita il numero di strumenti nel tuo agente a 25-30.
• Quando si utilizza l'orchestrazione multi-agente con agenti figli, ogni agente figlio ha la propria orchestrazione e può gestire un proprio insieme di fino a 128 strumenti.