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.
I plug-in MCP e API sono azioni personalizzate che consentono agli agenti dichiarativi in Microsoft 365 Copilot di interagire con server MCP (Model Context Protocol) o API REST con una descrizione OpenAPI. Utilizzando uno di questi plug-in, gli utenti possono chiedere a un agente dichiarativo di interrogare informazioni su un server MCP o un'API REST e, se supportato, creare, aggiornare ed eliminare dati e oggetti tramite richieste in linguaggio naturale.
Questo articolo usa il plug-in per l'azione tecnica personalizzata MCP o API utilizzata da un agente dichiarativo. Per il prodotto, il pacchetto, il registro di sistema e il ciclo di vita del plug-in rivolto al cliente, vedere Plug-in per Microsoft 365 Copilot.
Durante la compilazione o il riutilizzo, consultare questo articolo per scegliere un'azione MCP o API e comprendere come viene richiamata dall'agente di orchestrazione. Concludi con il modello di azione tecnica e una procedura di prodotto per implementarlo. L'azione risultante è una dipendenza dell'agente, non una promessa separata di distribuzione pubblica.
Importante
I plug-in MCP e API forniscono azioni all'interno di agenti dichiarativi. Non sono pacchetti di plugin installabili autonomamente: solo l'agente contenitore può accedere alle loro funzioni e ai loro strumenti. Per informazioni sulla relazione tra pacchetto e manifesto dell'azione, vedere Plug-in e azioni dichiarative dell'agente.
Un plug-in API o MCP usa un manifesto del plug-in che Copilot legge per ottenere informazioni sul server API o MCP disponibile per l'agente. Copilot può quindi decidere quando l'agente deve usare tale integrazione per rispondere a una richiesta. Per ulteriori informazioni su questo manifesto, vedere Schema del manifesto del plug-in API e MCP. Il pacchetto installabile usa un manifesto dell'app Microsoft 365 separato.
Come Copilot scopre gli strumenti del server MCP
Per i plug-in basati su un server MCP, Copilot risolve gli strumenti del plug-in in modo dinamico in fase di esecuzione per impostazione predefinita, direttamente dal server MCP. Il rilevamento dinamico degli utensili consente di ottenere gli strumenti più recenti esposti dal server MCP senza attendere che l'agente venga riconfezionato e ripubblicato. Durante la creazione dell'agente, uno sviluppatore può invece aggiungere un set fisso di strumenti nel manifesto del plug-in. I plug-in API REST usano sempre gli strumenti definiti nel manifesto del plug-in. Per ulteriori informazioni, vedere Creare plug-in da un server MCP per Microsoft 365 Copilot e Individuazione dinamica degli strumenti per plug-in MCP in Microsoft 365 Copilot.
Questa impostazione predefinita si applica ai plug-in MCP usati come azioni dell'agente dichiarativo. Per un plug-in che fa riferimento a un server MCP remoto nel agentConnectors manifesto dell'app Microsoft 365, l'individuazione dinamica degli strumenti richiede il manifesto dell'app versione 1.29 o successiva e un host che lo consenta. Per ulteriori informazioni, vedere Configurare server MCP remoti per i plug-in di Microsoft 365 Copilot.
Esempio di plug-in
Considera un server MCP per budget che consenta di eseguire query e creare budget, addebitare spese o aggiungere fondi a budget esistenti. La richiesta "Quanto rimane nel budget di viaggio di Contoso" potrebbe attivare un plug-in per il budget, richiamando lo get-budgets strumento.
POST /mcp
Content-Type: application/json
{
"method": "tools/call",
"params": {
"name": "get-budgets",
"arguments": {
"budgetName": "contoso travel"
}
}
}
Copilot usa la risposta del risultato dello strumento per generare la risposta: "Il budget di viaggio di Contoso prevede attualmente $ 5.000 di fondi disponibili. Se hai bisogno di allocare fondi a categorie specifiche o tenere traccia delle spese, posso aiutarti anche in questo. Fammi solo sapere come posso aiutarti!"
Il prompt "Addebita $ 500 al budget di viaggio di Contoso per il biglietto aereo di Megan" può essere tradotto nella seguente chiamata allo strumento MCP.
POST /mcp
Content-Type: application/json
{
"method": "tools/call",
"params": {
"name": "charge-budget",
"arguments": {
"budgetName": "contoso travel",
"amount": 500,
"description": "Megan's airline ticket"
}
}
}
Copilot risponde all'utente usando le informazioni restituite: "L'addebito di $ 500 per il biglietto aereo di Megan è stato elaborato correttamente. Il budget di viaggio di Contoso prevede ora 4.500 dollari di fondi disponibili. Se hai bisogno di effettuare altre transazioni o hai bisogno di ulteriore assistenza con il tuo budget, per favore fammelo sapere!"
Come funzionano i plugin
L'utente chiede all'agente "Quanto rimane nel budget per la ristrutturazione della hall del Fourth Coffee?"
Per un plug-in MCP che utilizza il rilevamento dinamico degli strumenti, l'agente recupera le definizioni degli strumenti correnti dal server MCP del plug-in in fase di esecuzione e convalida eventuali strumenti nuovi o modificati prima di utilizzarli. Per un plug-in con un set di strumenti bloccato o per un plug-in API REST, l'agente usa invece gli strumenti definiti nel manifesto del plug-in.
L'agente identifica un plug-in relativo al budget dai plug-in disponibili che dispone di uno strumento server MCP o di un'API
GetBudgetper ottenere i dettagli del budget. Mappa parti della domanda dell'utente ai parametri della funzione:budgetName="".L'agente chiede all'utente di consentirgli di inviare
Fourth Coffee lobby renovational plug-in.L'utente sceglie di consentire la condivisione dei dati con il plug-in una sola volta o sceglie di consentire sempre la condivisione dei dati per questa funzione.
Se il server MCP o l'API del plug-in richiede l'autenticazione, il plug-in richiede un token o una chiave API dall'archivio token.
L'archivio token restituisce un token o una chiave. Se necessario, l'archivio token fa sì che l'agente richieda all'utente di eseguire l'accesso.
L'agente invia una richiesta al server o all'API MCP del plug-in, ospitato all'esterno di Microsoft 365.
Il server o l'API MCP restituisce una risposta.
{ "name": "Fourth Coffee lobby renovation", "availableFunds": 5000.00 }L'agente genera una risposta in base alla risposta del server MCP o dell'API.
L'agente invia la risposta: "I fondi disponibili rimasti nel budget per la ristrutturazione della hall del Fourth Coffee sono di $ 5,000".
Conferma delle azioni
Copilot chiede all'utente prima di inviare per la prima volta qualsiasi dato a un plug-in.
Dopo che l'utente conferma la connessione, gli strumenti del server MCP e le API che recuperano solo i dati non richiedono conferma, mentre gli strumenti e le API che modificano i dati sì. Gli sviluppatori di plugin possono sovrascrivere queste impostazioni predefinite. Per informazioni dettagliate, vedere Richieste di conferma per i plug-in MCP e API per Microsoft 365 Copilot.
Personalizzazione della presentazione delle risposte
Copilot genera risposte conversazionali usando i dati del server MCP o le risposte API. I plug-in possono personalizzare il modo in cui i dati vengono presentati e il meccanismo dipende dal tipo di plug-in.
I plug-in MCP possono fornire risposte interattive avanzate utilizzando app MCP , ovvero widget dell'interfaccia utente che il server MCP restituisce insieme al risultato dello strumento in fase di esecuzione. Poiché il widget viene fornito con la risposta dello strumento anziché definito nel manifesto, le app MCP funzionano sia che il plug-in utilizzi un set di strumenti appuntato o un rilevamento dinamico degli strumenti.
I plug-in API possono fornire modelli di schede adattive nel manifesto del plug-in per visualizzare i dati in modo strutturato. Poiché i modelli sono definiti in base alle operazioni dichiarate nel manifesto, questo approccio si applica ai plug-in API e ai plug-in MCP che usano un set di strumenti bloccati.
Per le citazioni collegate all'origine su qualsiasi tipo di plug-in, Copilot usa la semantica della risposta e può dedurre automaticamente i metadati di citazione dalla risposta dello strumento o dell'API. L'inferenza automatica è particolarmente utile per i plug-in MCP che utilizzano il rilevamento dinamico degli strumenti, in cui gli strumenti vengono risolti in fase di esecuzione e non esiste alcuna definizione di strumento manifesto da configurare. Per altre informazioni, vedere Mostrare le citazioni con la semantica della risposta.
Gestione degli URL nelle risposte alle azioni
L'esperienza di chat di Microsoft 365 Copilot potrebbe restituire gli URL restituiti come parte delle risposte all'azione, da plug-in MCP, plug-in API, connettori o flussi, come collegamenti selezionabili. Il runtime di Copilot controlla questo comportamento e non lo valuta rispetto ad alcun dominio dichiarato dal plug-in (ad esempio la servers sezione della descrizione OpenAPI di un plug-in API).
Le regole di sicurezza, attendibilità e criteri della piattaforma regolano il comportamento di rendering degli URL per le risposte alle azioni e potrebbero cambiare nel tempo. Non fare affidamento sugli URL cliccabili nelle risposte alle azioni per scenari critici per la produzione.
Aiutare l'agente di orchestrazione di Copilot a scegliere le azioni dell'agente
Descrivere accuratamente l'integrazione API o MCP, le relative funzioni o strumenti e i relativi input in modo che l'agente di orchestrazione possa selezionare l'azione giusta per la richiesta dell'utente. Queste descrizioni riguardano le azioni dell'agente, non il nome o la descrizione del negozio del pacchetto di plug-in esterno.
| Integrazione delle azioni | Dove descriverlo | Altre informazioni |
|---|---|---|
| Plug-in API | Estensione manifesto e funzionamento OpenAPI e descrizioni dei parametri | Creare descrizioni OpenAPI efficaci |
| Plug-in MCP | Descrizioni di manifesti di plug-in e strumenti MCP; Le definizioni degli strumenti provengono dal server in fase di esecuzione o sono aggiunte nel manifesto | Rilevamento dinamico degli utensili e utensili bloccati |
Le funzioni e gli strumenti MCP non sono gli stessi dei file di istruzioni riutilizzabili descritti in Abilità come funzionalità del plug-in.
Creare un agente dichiarativo con azioni API o MCP
Per lo sviluppo professionale, inizia con gli strumenti di sviluppo di Work IQ. Scegli prima un ambiente documentato, quindi aggiungi uno strumento nell'elenco seguente quando hai bisogno delle funzionalità di generazione di progetti o di integrazione:
-
Work IQ Dev Tools è lo strumento consigliato. Usare
wiqd agent add actionper aggiungere un'azione OpenAPI o MCP remota supportata a un progetto agente dichiarativo. - Le procedure dettagliate basate su Toolkit esistenti rimangono disponibili per un server MCP, una descrizione OpenAPI o una nuova API REST. Seguire queste procedure quando si lavora con un progetto Toolkit.
- Kiota può generare un manifest di plugin API da una descrizione OpenAPI esistente.
Il manifesto del plug-in API o MCP configura l'integrazione dell'azione dell'agente. Creare un pacchetto e distribuire l'agente contenitore tramite la route app-pacchetto supportata. Il manifesto dell'azione non è un pacchetto di plug-in installabile in modo indipendente.
Suggerimento
Work IQ Dev Tools è disponibile a livello generale.
wiqd agent add action Aggiunge un'azione a un progetto agente dichiarativo ed wiqd agent validate --mode source esegue controlli offline sull'origine dell'agente salvata. Un controllo dell'origine superato non stabilisce la raggiungibilità dell'endpoint runtime o OpenAPI, la correttezza dell'autenticazione o l'accettazione del pacchetto finale. Se si omette --mode, il valore predefinito per la convalida è package, che carica una copia di un file ZIP esistente e potrebbe richiedere l'accesso. Per le modalità di convalida e il coverage, vedere la guida di riferimento per i comandi WIQD e Validation and MVL.
Limitazioni
Questi limiti riguardano i plug-in API e MCP usati come azioni dell'agente dichiarativo, non il numero di competenze, agenti o connettori in un pacchetto di plug-in installabile.
Quando un agente dichiarativo include fino a cinque plug-in definiti nel manifesto dell'agente dichiarativo, l'agente inserisce sempre i plug-in nel prompt. Quando l'agente include più di cinque plug-in, usa la corrispondenza semantica. La corrispondenza semantica si basa sulla descrizione del plug-in, non su una qualsiasi delle singole funzioni o strumenti all'interno del plug-in stesso.
Un plugin può includere un numero illimitato di funzioni o strumenti MCP. Vengono restituiti tutte le funzioni o gli strumenti di un plug-in corrispondenti, anche se ne viene trovato uno solo. Per un plug-in MCP che utilizza il rilevamento dinamico degli strumenti, gli strumenti risolti dal server MCP in fase di esecuzione vengono conteggiati per questo totale. A causa dei limiti della finestra dei token, la qualità delle risposte potrebbe peggiorare se vengono incluse più di 10 funzioni o strumenti.
La finestra del token per gli input e gli output di un plug-in tronca il contenuto di grandi dimensioni. Il limite funzionale è soggetto a modifiche man mano che i modelli migliorano e dipende da qualsiasi sovraccarico del sistema. Ottimizzare per token di piccole dimensioni o optare per opzioni di estendibilità che consentono lo streaming di contenuti di grandi dimensioni, se necessario.
Passaggio successivo
Implementare l'azione MCP o l'azione API selezionata. Dopo che i componenti funzionano singolarmente, immettere Package & testare con Integra e testare i componenti.
Contenuti correlati
- Creare plug-in da un server MCP per Microsoft 365 Copilot
- Aggiungere app MCP agli agenti dichiarativi in Microsoft 365 Copilot
- Individuazione dinamica degli strumenti per i plug-in MCP in Microsoft 365 Copilot
- Crea plug-in API da un'API esistente per Microsoft 365 Copilot
- Crea plug-in API con una nuova API per Microsoft 365 Copilot
- Schema del manifesto del plug-in API e MCP per Microsoft 365 Copilot
- Scrivere istruzioni efficaci per gli agenti dichiarativi con i plug-in API