Nota
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare ad accedere o modificare le directory.
L'accesso a questa pagina richiede l'autorizzazione. È possibile provare a modificare le directory.
Gli agenti dichiarativi personalizzano Microsoft 365 Copilot per soddisfare le esigenze specifiche di un'organizzazione. Puoi aggiungere azioni personalizzate tramite plug-in API. Per gli scenari pro-code supportati, si consiglia Work IQ Dev Tools . Queste integrazioni consentono al tuo agente di interrogare e interagire con i dati di un'organizzazione tramite API; non sono i file di istruzioni riutilizzabili descritti in Abilità come funzionalità del plug-in.
Questo articolo descrive l'architettura degli agenti e fornisce le procedure consigliate per la scrittura di istruzioni per gli agenti dichiarativi che includono plug-in API.
Componenti principali degli agenti dichiarativi con plug-in API
Gli agenti dichiarativi che chiamano i plug-in API includono diversi componenti che garantiscono un'integrazione e funzionalità efficaci. La comprensione di questa architettura ti aiuterà a progettare il tuo agente in modo efficace. L'architettura include i componenti seguenti:
- Manifesto dell'applicazione : descrive come è configurata l'app e fa riferimento al manifesto dell'agente dichiarativo.
- Manifesto dichiarativo dell'agente : definisce la configurazione dell'agente, incluse istruzioni, funzionalità, spunti di conversazione e azioni. Fa riferimento al manifesto del plug-in.
- Manifesto del plug-in : descrive la configurazione del plug-in, incluse le funzioni disponibili e un riferimento alla specifica OpenAPI.
- Specifica OpenAPI - Fornisce definizioni dettagliate degli endpoint API, inclusi percorsi, parametri, formati di richiesta e risposta e autenticazione.
Insieme, questi file definiscono il comportamento dell'agente e il modo in cui interagisce con l'API sottostante.
Per ulteriori informazioni sui plug-in API, consulta:
- Plug-in MCP e API per agenti dichiarativi
- Come rendere efficace un documento OpenAPI nell'estendere le funzionalità di Copilot
Mapping delle funzioni nel manifesto del plug-in
Nel manifesto del plug-in, ogni funzione deve eseguire il mapping a un operationId corrispondente nella specifica OpenAPI. In questo modo, quando l'agente richiama una funzione, ad esempio createTask, l'agente sappia quale endpoint API chiamare.
Gli esempi seguenti mostrano il mapping nel manifesto del plug-in e la funzione mappata nella specifica OpenAPI.
"functions": [
{
"name": "createTask",
"description": "Creates a new task in the specified task list."
}
]
paths:
/me/todo/lists/{listId}/tasks:
post:
operationId: createTask
summary: Create a new task
description: Creates a new task in the specified task list.
parameters:
Procedure consigliate per le istruzioni dell'agente
Scrivere istruzioni efficaci è essenziale per garantire che gli agenti dichiarativi con plug-in API abbiano successo. Per ottimizzare l'agente, applica il mapping delle funzioni corretto, usa il concatenamento per consentire interazioni più ricche e testa e perfeziona iterativamente il comportamento dell'agente.
Applica le seguenti best practice quando scrivi istruzioni per agenti dichiarativi con plug-in API:
- Evitare istruzioni ambigue o negative. Istruzioni contrastanti o negative possono introdurre ambiguità e confondere il modello. Concentrati sulla definizione di casi d'uso validi con esempi positivi. Se è importante distinguere tra query valide e non valide, fornire criteri ed esempi chiari che definiscano la risposta dell'agente prevista per ognuna.
- Esempi d'uso Fornisci esempi chiari per guidare il comportamento dell'agente. Ad esempio:
Input utente: Che tempo fa a Praga? Chiamata dell'agente: getWeather(location="Prague") Input dell'utente: "Domani ho bisogno di un ombrello?" Chiamata dell'agente: getWeather(location=user_location, forecast="tomorrow")
Rivedi e testa le istruzioni. Testare le istruzioni in vari scenari per verificare che l'agente effettui le chiamate di funzione corrette. Se durante il test si rileva che l'agente richiama le funzioni in modo imprevisto, rivedere la descrizione della funzione nella specifica OpenAPI e chiarire le istruzioni dell'agente per migliorare la mappatura delle intenzioni.
Istruzioni di progettazione per conversazioni a più turni. Quando integri i plug-in API, progetta le istruzioni affinché l'agente gestisca conversazioni a più turni.
Ad esempio, se la funzione richiede più parametri, oltre a definire i parametri richiesti nella specifica OpenAPI, indicare all'agente di raccogliere tutti i parametri prima di effettuare la chiamata API. Ciò garantisce che l'agente raccolga tutte le informazioni necessarie in una sequenza logica.
L'esempio seguente mostra come indicare a un agente meteo conversazioni a più turni e il flusso dell'agente che ne deriva.
| Istruzioni per l'agente | Flusso agente |
|---|---|
| Se l'utente chiede informazioni sul tempo: - Chiedere all'utente la posizione. - Chiedi all'utente il giorno delle previsioni. - Chiedere all'utente il sistema dell'unità. - Chiama getWeather solo quando raccogli tutti i valori. |
Utente: "Che tempo fa?" Agente: "Qual è la tua posizione?" Utente: "Londra" Agente: "Preferisci le informazioni meteorologiche in unità metriche o imperiali?" Utente: "Metrica" Agente: "Hai bisogno del tempo per oggi o delle previsioni per domani?" Utente: "Oggi" Agente: "Controllerò il meteo di Londra per oggi" Chiamate dell'agente: getWeather(location="London", forecast="today", system="Metric") |
Per le procedure consigliate generali per le istruzioni dell'agente, vedere Scrivere istruzioni efficaci.
Concatenamento di chiamate di funzione nei plug-in API
Il concatenamento delle chiamate di funzione consente agli agenti dichiarativi di combinare più azioni API in un unico flusso senza soluzione di continuità. Le sezioni seguenti descrivono i modelli comuni e come scrivere istruzioni per ognuno di essi.
Concatenamento di chiamate di funzione con output come parametro di input
Utilizzare il risultato di una chiamata API come input per un'altra. Ciò è utile quando il risultato della prima funzione è necessario per eseguire la seconda funzione. Questo può funzionare tra i plug-in.
Nell'esempio seguente, un agente dichiarativo con API Meteo e API To-do crea un'attività To-Do con i dati delle previsioni meteo.
| Istruzioni per l'agente | Flusso agente |
|---|---|
| Per visualizzare il meteo, usa sempre l'azione getWeather , quindi crea un'attività con il titolo "temperatura in" e aggiungi la posizione e la temperatura menzionate nel meteo al titolo dell'attività. |
Utente: "Previsioni meteo a Praga" Agente: chiama getWeather (location="Prague", forecast="today") Agente: usa i dati della prima chiamata per creare un'attività To-Do createTask (title ="{weather output}") |
Concatenamento basato sulla cronologia delle conversazioni all'interno di un agente
Quando si usa il concatenamento in base alla cronologia delle conversazioni, l'agente usa le risposte precedenti per gestire le azioni di completamento. Questo approccio usa la cronologia delle conversazioni per mantenere il contesto.
Nell'esempio seguente, un agente elimina un'attività per nome.
| Istruzioni per l'agente | Flusso agente |
|---|---|
| 1. Quando l'utente chiede di elencare tutte le cose da fare, chiama getTasks per recuperare l'elenco delle cose da fare con titolo e ID. 2. Dopo aver elencato le cose da fare, se l'utente chiede di eliminare un'attività, usare l'ID della risposta per chiamare deleteTask. |
Utente: "Mostra tutte le cose da fare nella cartella Attività?" Agente: alls getTasks (folderId="Tasks") e visualizza tutte le attività con ID. Utente: "Delete TaskMaster Pro to-do" Agente: utilizza le informazioni della cronologia delle conversazioni per trovare l'ID per l'attività ed elimina l'attività chiamando deleteTask. |
Concatenamento con conoscenza di SharePoint
Il concatenamento delle chiamate API consente a un agente di combinare fonti di conoscenza e azioni per progettare flussi di lavoro più complessi.
Nell'esempio seguente un agente recupera i dati sullo stato del progetto da SharePoint e crea le attività corrispondenti in Microsoft To-Do per la verifica.
| Istruzioni per l'agente | Flusso agente |
|---|---|
| - Per ottenere gli stati del progetto, utilizza ProjectDeadlines, conoscenza di SharePoint. - Crea sempre un elenco attività per ogni progetto utilizzando l'aggiornamento dello stato per il titolo. |
Utente: "Potete fornire un aggiornamento sullo stato di tutti i progetti?" Agente: Recupera i dati sullo stato del progetto da SharePoint e quindi usa createTask per generare un'attività Da fare per ogni progetto. |
Concatenamento con interprete di codice
È anche possibile concatenare chiamate API e integrare funzionalità aggiuntive, come un interprete di codice. Ciò consente a un agente di elaborare dinamicamente gli output dell'API per abilitare flussi di lavoro più avanzati.
Nell'esempio seguente, un agente crea un grafico basato sui dati delle attività To-Do.
| Istruzioni per l'agente | Flusso agente |
|---|---|
| Quando l'utente chiede di elencare tutte le cose da fare, chiama getTasks per recuperare l'elenco delle cose da fare con titolo e ID, traccia anche il grafico per l'output. |
Utente: "Recupera tutte le attività in Tasks" Agent: chiama getTasks (folderId="Tasks") e visualizza tutte le attività con ID. Agente: Chiama l'interprete del codice per avviare la generazione del grafico in base all'output della prima chiamata. |
Anche questo esempio esegue più azioni contemporaneamente. Ciò è utile avviando una serie di azioni correlate che non richiedono più input dell'utente.
Quando l'interprete del codice genera un file (ad esempio un'immagine di un grafico o un foglio di calcolo), Copilot presenta automaticamente un collegamento per il download nella risposta, consentendo agli utenti di salvare il file in locale. Per ulteriori informazioni, consulta Generare file scaricabili.