Crea istanze di agente

Dopo aver pubblicato il tuo agente e renderlo disponibile nel centro amministrativo Microsoft, puoi creare istanze di agente e utenti agenti. Queste istanze e utenti utilizzano il blueprint dell'agente e il codice dell'agente che hai creato.

Questo articolo suddivide il processo in tre fasi principali:

1. Configura l'agente nel portale sviluppatori di Teams
2. Crea istanza di agente
3. Testa il tuo agente schierato

Se hai delle difficoltà, consulta la sezione Risoluzione dei problemi .

Prerequisiti

• Blueprint dell'agente configurato correttamente secondo il passaggio di configurazione del blueprint dell'agente.
• L'applicazione dell'agente è stata pubblicata correttamente secondo Pubblica agente nel Microsoft admin center.

1. Configura l'agente nel portale sviluppatori di Teams

Dopo la pubblicazione, configurare il progetto agente nel portale per sviluppatori di Teams per connettere l'agente all'infrastruttura di messaggistica Microsoft 365. Senza questa configurazione, l'agente non riceve messaggi da Teams, posta elettronica o altri servizi di Microsoft 365.

1. Ottieni il tuo ID del progetto

   Esegui il comando a365 config display -g per visualizzare la tua configurazione:

   a365 config display -g
   

   Copiare il valore agentBlueprintId dall'output.

2. Naviga al Portale Sviluppatori

   Apri il browser e vai alla pagina di configurazione:

   https://dev.teams.microsoft.com/tools/agent-blueprint/<your-blueprint-id>/configuration
   

   Sostituisci <your-blueprint-id> con il agentBlueprintId valore che hai copiato.

   Annotazioni

   Se non hai accesso al Portale degli Sviluppatori, contatta l'amministratore del tuo tenant per concederti l'accesso o completare questa configurazione per tuo conto.

3. Configura l'agente

   Nel portale sviluppatori:

   1. Imposta il tipo di agente su Bot Based
   2. Imposta l'ID del bot al tuo agentBlueprintId valore
   3. Seleziona Salva

   

Serve questa configurazione prima di poter creare istanze di agente in Teams.

Scopri di più sui Blueprint dell'Identità dell'Agente e sulla configurazione del Portale Sviluppatori.

2. Crea un'istanza di agente

Ora puoi richiedere un'istanza del blueprint del tuo agente da Teams. Scopri di più su come scoprire, creare e integrare un agente.

Quando richiedi un'istanza agente, Teams invia la richiesta all'amministratore tenant per l'approvazione. Gli amministratori possono esaminare e approvare le richieste dal centro amministrativi Microsoft - pagina Agenti richiesti .

Dopo che l'amministratore ha approvato la tua richiesta, Teams crea la tua istanza agente e la rende disponibile in Teams.

3. Testa il tuo agente schierato

Dopo aver creato un'istanza dell'agente, testarla in Microsoft 365 per assicurarsi che funzioni correttamente nell'ambiente di produzione.

Dopo la distribuzione e con le notifiche degli agenti abilitate in Agent 365 SDK, l'agente si integra con i servizi di Microsoft 365. Funziona con Teams per chat, canali e riunioni; con posta elettronica e calendario per l'invio, la ricezione e la pianificazione; e con SharePoint e OneDrive per l'accesso ai documenti e la condivisione di file. Supporta inoltre funzionalità di collaborazione come la presenza organizzativa, le attività del Planner e i commenti ai documenti.

Visualizza l'agente distribuito nel centro amministrativo

Dopo aver pubblicato il tuo agente, appare nel centro amministrazione Microsoft per l'assunzione. Potrebbe volerci un po' di tempo per propagarsi.

Passare all'interfaccia di amministrazione di Microsoft 365 - Agenti a:

• Visualizza l'agente pubblicato
• Gestire le impostazioni dell'agente
• Monitorare l'utilizzo dell'agente
• Configura autorizzazioni

Testare l'agente in Teams

Dopo la distribuzione, la pubblicazione e la configurazione del modello di agente e la creazione di un utente agente, testare l'utente agente direttamente in Microsoft Teams:

Inizia i test

1. Cerca il tuo nuovo utente agente in Teams

   Annotazioni

   Il processo di creazione dell'utente agente è asincrono e può richiedere da pochi minuti a qualche ora perché l'utente agente diventi ricercabile dopo la creazione.

2. Avvia una nuova chat con la tua nuova istanza di agente creata.

3. Invia messaggi di test per verificare la funzionalità dell'agente.

Esempio di messaggio di test

Se hai configurato l'agente con Email, invia questo messaggio per testare la funzionalità email. Aggiorna il valore dell'email destinataria recipient@contoso.com .

Send an email to <recipient@contoso.com> with subject "Hello from Teams" and message "This is a test message from my agent!"

L'agente elabora la richiesta e invia l'email senza richiedere ulteriori conferme.

Elenco di controllo di convalida

Dopo aver creato la tua istanza per agente, verifica che funzioni correttamente in Teams.

✅ Configurazione del portale sviluppatori salvata
✅ L'agente appare nella ricerca delle app di Teams
✅ Puoi creare un instance agent per i team
✅ Istanza dell'agente creata
✅ L'agente utente appare nell'organizzazione
✅ L'agente risponde ai messaggi
✅ L'agente può eseguire azioni
✅ I log applicazioni non mostrano errori
✅ Osservabilità lavorando in un centro amministrativo

Se la tua istanza di agente non funziona come previsto, consulta la sezione Risoluzione dei problemi per soluzioni dettagliate ai problemi comuni.

Verifica che la configurazione del portale degli sviluppatori sia salvata

Passare a: https://dev.teams.microsoft.com/tools/agent-blueprint/<your-blueprint-id>/configuration

✅ Tipo di agente : Basato su bot
✅ L'ID del bot corrisponde al tuo agentBlueprintId
✅Mostra il messaggio Salvata con successo

Verifica che l'agente appaia in Teams

1. Aprire > Teams

2. Cerca il nome del tuo agente

   ✅ L'agente appare nei risultati di ricerca
   ✅ Mostra l'icona e la descrizione del tuo agente

Verifica di poter creare un instance agent per i team

Seleziona il tuo agente nelle app Teams

✅ Il pulsante Richiedi Istanza/Crea Istanza è abilitato
✅ È possibile richiedere l'istanza senza errori

Verifica l'istanza dell'agente creata

Dopo aver selezionato l'Istanza di richiesta:

✅ Richiesta inviata con successo all'amministrazione

Verifica che l'agente utente compaia nell'organizzazione

Nell'interfaccia di amministrazione di Microsoft 365:

1. Passa a: https://admin.cloud.microsoft/#/agents/all
2. Naviga nella scheda Richieste di tutti gli agenti

✅ La richiesta di istanza del tuo agente è contrassegnata come in attesa di revisione
✅ L'amministratore può approvare l'istanza dell'agente per l'utilizzo
✅ L'utente può quindi creare un'istanza da Teams e darle un nome.

Verifica che l'agente risponda ai messaggi

Nella chat di Teams con il tuo agente - Invia un messaggio di test: Hello!

✅ L'agente mostra l'indicatore di digitazione
✅ L'agente risponde entro pochi secondi
✅ La risposta è coerente e rilevante

Verifica che l'agente possa eseguire azioni

Se gli strumenti sono configurati, testa la funzionalità degli strumenti. Ad esempio, se hai aggiunto il server Mail MCP, invia una mail di prova a te stesso.

L'agente dovrebbe:

✅ Conferma la richiesta
✅ Esegui la chiamata dello strumento
✅ Conferma il completamento con successo

Dovresti verificare che l'email arrivi nella tua casella di posta.

Verificare la funzionalità

La seguente checklist fornisce un approccio sistematico di test per il tuo agente:

Funzionalità di base:

✅ L'agente risponde a semplici saluti.
✅ L'agente gestisce conversazioni a più passi.
✅ L'agente fornisce risposte pertinenti.

Funzionalità degli strumenti:

Dipende dalla configurazione del server MCP

✅ Può inviare email.
✅ Può accedere al calendario.
✅ Puoi cercare documenti.
✅ Può eseguire azioni configurate.

Gestione degli errori:

✅ Gestisce con grazia le richieste non valide.
✅ Fornisce messaggi di errore utili.
✅ Non si blocca su input inaspettati.

Prestazioni:

✅ Risponde entro pochi secondi.
✅ Nessun errore di timeout.
✅ Tempi di risposta costanti.

Verifica i log delle applicazioni

Per vedere cosa sta facendo il tuo agente, controlla i log delle applicazioni usando il comando log tail di AZ WebApp .

# Real-time logs from Azure
az webapp log tail --name <your-web-app> --resource-group <your-resource-group>

Cosa cercare nei log:

✅ Richieste in arrivo da Teams
✅ Autenticazione riuscita
✅ Chiamate di strumenti in esecuzione
✅ Risposte inviate
❌ Messaggi di errore o eccezioni

Verifica l'osservabilità nel centro amministrativo

Dopo che il tuo agente inizia a lavorare:

1. Passa a: https://admin.cloud.microsoft/#/agents/all

2. Seleziona il tuo agente e apri la scheda Attività .

   Dovresti vedere:

   ✅ Sessioni in programma.
   ✅ Ogni sessione mostra trigger e azioni.
   ✅ Le chiamate agli strumenti vengono registrate con timestamp.

Passaggi successivi

L'agente è ora disponibile nel cloud e pronto a collaborare con il team in Microsoft 365. Quello che è iniziato come codice locale è ora un assistente rilevabile e pronto per l'impresa dove gli utenti possono creare istanze di agente in tutta l'organizzazione.

Il ciclo di sviluppo del tuo agente è completo, ma il suo impatto è appena iniziato. Gran parte di ciò che è stato creato nel ciclo di vita degli sviluppatori dell'agente 365 è open source e accoglie i contributi della community. Segnala bug, richieste di funzionalità e pull request:

• Esempi di agenti 365: Hai qualche esempio di agente interessante e divertente? Condividi il codice dell'agente con la community open source qui!
• Node.js SDK: L'SDK dell'Agente 365 in Node.js
• Python SDK: Sdk di Agent 365 in Python
• .NET SDK: Agent 365 SDK in C# (.NET)
• Agent 365 DevTools CLI: Una CLI per aiutarti durante tutto il ciclo di sviluppo di Agent 365

Risoluzione dei problemi

Questa sezione contiene problemi comuni durante la creazione e il test di istanze di agenti.

L'agente non appare in Teams

Sintomo: L'agente appare nel centro amministrativo ma non riesco a trovarlo nelle app di Teams.

Causa principale: Configurazione mancante del Portale Sviluppatori.

Soluzione:

1. Ottieni il tuo ID del progetto:

   a365 config display -g
   # Copy the agentBlueprintId value
   

2. Configura nel Portale Sviluppatori:

   1. Passa a: https://dev.teams.microsoft.com/tools/agent-blueprint/<your-blueprint-id>/configuration
   2. Imposta il tipo di agente su Bot Based
   3. Imposta l'ID del bot su agentBlueprintId
   4. Seleziona Salva

3. Aspetta 5-10 minuti per la propagazione.

Verifica:

• Apri App di Teams >> Cerca il tuo agente
• Agente appare ed è disponibile per aggiungere

Non si può creare un'istanza di agente in Teams

Sintomo: L'agente appare in Teams ma non può aggiungere o creare un'istanza; Il pulsante Request Instance non funziona.

Causa principale: Microsoft Agent 365 Frontier non è abilitato per il tenant.

Soluzione: Contatta l'amministratore del tuo tenant per verificare che Microsoft Agent 365 Frontier sia abilitato per il tenant

Scopri di più su Frontier

Verifica:

Le funzionalità di frontiera vengono visualizzate all'interno di Microsoft 365 Copilot e Microsoft 365 app una volta consentite le impostazioni di licenza e amministratore.

Agente che non risponde ai messaggi

Sintomo: Ho creato un'istanza dell'agente ma non risponde ai messaggi; Nessun registro nell'applicazione.

Causa principale: Molteplici possibili cause: problemi di endpoint di messaggistica, problemi di autenticazione o errori di configurazione.

Risoluzione dei problemi di base

1. Verifica che l'app web sia in funzione:

   az webapp show --name <your-app-name> --resource-group <your-resource-group> --query state
   # Should be: "Running"
   

2. Controlla l'endpoint della messaggistica:

   • Dovrebbe essere: https://<your-app-root-url>/api/messages
   • Verificalo in a365.config.json e a365.generated.config.json

3. Testa direttamente l'endpoint:

   curl https://<your-app-root-url>/api/messages
   # Should not return 404
   

4. Controlla i registri delle applicazioni:

   az webapp log tail --name <your-app-name> --resource-group <your-resource-group>
   # Look for incoming requests and errors
   

Diagnostica avanzata

1. Verifica l'autenticazione:

   • Controlla se i token sono scaduti. Rinnovali se necessario.
   • Verifica le credenziali nella configurazione dell'app Web.

2. Controlla configurazione strumento/MCP:

   • Verifica che i server MCP siano configurati.
   • Controlla che i permessi siano stati concessi.

3. Testare localmente:

   • Esegui l'agente localmente con la stessa configurazione.
   • Prova con Agents Playground.
   • Funziona localmente ma non nel cloud, problema di distribuzione.

soluzioni comuni

• Endpoint di messaggistica non corretto: Aggiornamento nel portale di Azure e nel portale per sviluppatori
• App Web arrestata: Avviala utilizzando il portale di Azure o l'interfaccia della riga di comando (CLI)
• Token scaduto: Aggiorna i token nelle variabili di ambiente di Web App
• Variabili d'ambiente mancanti: Verifica Impostazioni dell'App nel portale di Azure
• Problemi con il server MCP: Verifica il principale del servizio e i permessi
• Errori di codice: Controlla i log delle applicazioni per eccezioni

Verifica

Invia un messaggio al tuo agente in Teams e controlla i log delle applicazioni per le richieste in arrivo.

Potresti anche provare:

• Risoluzione dei problemi nel disseguire un agente su Amazon Web Services
• Risoluzione dei problemi nel dispiegamento di un agente su Google Cloud Platform

Chiamate di strumenti che falliscono

Sintomo: L'agente risponde ai messaggi ma le chiamate agli strumenti falliscono. Visualizzi errori relativi a permesso negato o timeout.

Causa principale: Permessi mancanti del server MCP, principale di servizio non configurato, problemi di connettività di rete o configurazione errata degli strumenti.

Soluzioni

Prova le seguenti soluzioni quando le chiamate agli strumenti falliscono:

• Verifica i permessi nel centro amministrativo

  Rivedi e approva i permessi richiesti del server MCP:

  • Passa a: https://admin.cloud.microsoft/#/agents/all
  • Seleziona il tuo agente > Permessi
  • Assicurati che la lista includa e approvi i server MCP richiesti

• Verifica il service principal

  Esegui lo script di configurazione una sola volta se non l'hai eseguito prima:

  # Download and run:
  # https://github.com/microsoft/Agent365-devTools/blob/main/scripts/cli/Auth/New-Agent365ToolsServicePrincipalProdPublic.ps1
  

• Verifica la configurazione degli endpoint MCP

  Assicurati di utilizzare l'endpoint MCP di produzione:

  # Should be production endpoint, not mock
  MCP_PLATFORM_ENDPOINT=https://agent365.svc.cloud.microsoft
  

• Controlla identità gestita

  Verifica che l'identità gestita sia abilitata sulla tua Web App:

  # Verify managed identity is enabled
  az webapp identity show --name <your-app-name> --resource-group <your-resource-group>
  

Verifica

Testare le chiamate degli strumenti tramite Teams e controllare i log per verificare il successo dell'esecuzione.

Potresti anche voler provare questi passaggi:

• Risoluzione dei problemi degli strumenti
• Risoluzione dei problemi sul server di strumenti di simulazione

Fallimento della cessione della licenza

Sintomo: Non si può assegnare la licenza all'utente agente; Errori di licenza nel Centro Amministratore.

Causa principale: Licenze insufficienti disponibili, tipo di licenza errato o problema di permessi.

Soluzioni

Prova le seguenti soluzioni quando la cessione della licenza fallisce:

1. Verifica che le licenze siano disponibili:

   • Controllare il centro di amministrazione di Microsoft 365 >Fatturazione>Licenze
   • Assicurati che Microsoft Agent 365 Frontier sia abilitato per il tenant

2. Assegnare manualmente la licenza:

   • Passare all'interfaccia di amministrazione Microsoft 365 >Utenti
   • Trova l'utente agente
   • Assegnare la licenza appropriata

3. Licenze richieste per la piena funzionalità:

   • Microsoft 365 E5 (o equivalente)
   • Teams Enterprise
   • Microsoft 365 Copilot (per le funzionalità di Copilot)

Verifica

Controlla il profilo utente nel centro amministrativo e mostra le licenze assegnate.