Creare istanze dell'agente

Dopo aver pubblicato il tuo agente e averlo reso disponibile nell'interfaccia di amministrazione di 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 passaggi principali.

1. Configurare l'agente nel portale per sviluppatori di Teams
2. Creare istanza dell'agente
3. Testare l'agente distribuito

Se riscontri problemi, consulta la sezione Risoluzione dei problemi.

Prerequisiti

• Progetto dell'agente correttamente configurato come descritto in passaggio di installazione dell'agente.
• L'applicazione dell'agente è stata pubblicata correttamente come descritto in Pubblicare l'agente dell'interfaccia di amministrazione di Microsoft.

1. Configura l'agente nel portale per sviluppatori di Teams

Dopo la pubblicazione, configura il blueprint dell'agente nel portale per sviluppatori di Teams per collegare il tuo agente all'infrastruttura di messaggistica di Microsoft 365. Senza questa configurazione, l'agente non riceve messaggi da Teams, e-mail o altri servizi Microsoft 365.

1. Recuperare l'ID blueprint

   Apri a365.generated.config.json nella tua directory di lavoro e copia il valore agentBlueprintId.

2. Accedere al portale per gli sviluppatori

   Apri il Web browser e accedi alla pagina di configurazione:

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

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

   Nota

   Se non hai accesso al portale per sviluppatori, contatta l'amministratore del tenant per concederti l'accesso o completare questa configurazione per te.

3. Configurare l'agente

   Nel portale per sviluppatori:

   1. Imposta Tipo di Agente su Basato su API

   2. Imposta URL di notifica sull'endpoint di messaggistica del tuo agente. Trova il valore messagingEndpoint in a365.generated.config.json.

   3. Seleziona Salva.

   

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

Scopri di più sui blueprint di identità agente e sulla configurazione del portale per sviluppatori.

2. Crea l'istanza dell'agente

Ora puoi richiedere un'istanza del progetto dell'agente da Teams. Altre informazioni su come Individuare, creare ed eseguire l'onboarding di un agente.

Quando richiedi un'istanza agente, Teams invia la richiesta all'amministratore del tenant per l'approvazione. Gli amministratori possono esaminare e approvare le richieste dalla pagina Interfaccia di amministrazione di Microsoft - Agenti richiesti.

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

3. Testare l'agente distribuito

Dopo aver creato un'istanza agente, testala in Microsoft 365 per assicurarti che funzioni correttamente in produzione.

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

Visualizzare l'agente distribuito nell'interfaccia di amministrazione

Dopo la pubblicazione, l'agente viene visualizzato nell'interfaccia di amministrazione di Microsoft per l'assunzione. La propagazione potrebbe richiedere del tempo.

Accedi all'interfaccia di amministrazione di Microsoft 365 - Agenti per:

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

Testare l'agente in Teams

Dopo aver distribuito, pubblicato e configurato il blueprint dell'agente e creato un utente agente, testa l'utente agente direttamente in Microsoft Teams:

Avvia test

1. Cerca il tuo nuovo utente agente in Teams.

   Nota

   Il processo di creazione dell'utente agente è asincrono. Potrebbero volerci da pochi minuti ad alcune ore prima che l'utente agente sia visibile nella ricerca dopo la sua creazione.

2. Avvia una nuova chat con l'istanza dell'agente appena creata.

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

Messaggio di test di esempio

Se hai configurato l'agente con la posta elettronica, invia questo messaggio per verificare la funzionalità di posta elettronica. Aggiorna il valore dell'indirizzo e-mail recipient@contoso.com del destinatario.

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 il messaggio e-mail richiedere più conferma.

Elenco di controllo di verifica

Dopo aver creato l'istanza dell'agente, verifica che funzioni correttamente in Teams.

✅ Configurazione del portale per sviluppatori salvata
✅ L'agente appare nella ricerca delle app di Teams
✅ Puoi creare l'agente dell'istanza in Teams
✅ Istanza dell'agente creata
✅ L'utente dell'agente appare nell'organizzazione
✅ L'agente risponde ai messaggi
✅ L'agente può eseguire azioni
✅ I log delle applicazioni non mostrano errori
✅ Osservabilità operativa nell'interfaccia di amministrazione

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

Verificare che la configurazione del portale per sviluppatori sia stata salvata

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

✅ Tipo di agente mostra: Basato su API✅URL di notifica corrisponde agli endpoint di messaggistica dell'agente✅ Mostra il messaggio Salvataggio completato

Verifica che l'agente appaia in Teams

1. Apri >App Teams

2. Cerca l'agente in base al nome

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

Verifica di poter creare un'istanza agente in Teams

Seleziona il tuo agente nelle app Teams

✅ Il pulsante Richiedi Istanza/Crea Istanza è abilitato✅. Puoi richiedere un'istanza senza errori

Verifica l'istanza dell'agente creata

Dopo aver selezionato Richiedi Istanza:

✅ Richiesta inviata con successo all'amministratore

Verifica che l'utente agente compaia nell'organizzazione

Nell'interfaccia di amministrazione di Microsoft 365:

1. Vai a: https://admin.cloud.microsoft/#/agents/all
2. Accedi alla scheda Richieste di tutti gli agenti

✅ La richiesta di istanza dell'agente è elencata con lo stato 'in attesa di revisione' ✅ L'amministratore può approvare l'istanza dell'agente per l'uso ✅ L'utente può creare un'istanza da Teams e assegnarle 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 se l'agente può eseguire azioni

Se configuri gli strumenti, testa la loro funzionalità. Ad esempio, se aggiungi il server Mail MCP, invia una mail di prova a te stesso.

L'agente dovrebbe:

✅ Accettare la richiesta ✅ Eseguire la chiamata dello strumento ✅ Confermare il completamento con successo

Dovresti verificare che l'email sia arrivata nella tua posta in arrivo.

Verificare la funzionalità

La seguente checklist offre un approccio sistematico per testare il tuo agente:

Funzionalità di base:

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

Funzionalità degli strumenti:

Dipende dalla configurazione del server MCP

✅ Può inviare email. ✅ Può accedere al calendario. ✅ Può eseguire ricerche nei documenti. ✅ Può eseguire azioni configurate.

Gestione errori:

✅Gestisce correttamente le richieste non valide. ✅ Fornisce messaggi di errore utili. ✅ Non si arresta a fronte di input imprevisti.

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 dell'applicazione utilizzando il comando az webapp log tail.

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

Elementi da verificare nei log:

✅ Richieste in arrivo da Teams ✅ Autenticazione completata con successo ✅ Esecuzione delle chiamate agli strumenti ✅ Risposte inviate ❌ Messaggi di errore o eccezioni

Verifica l'osservabilità nell'interfaccia di amministrazione

Dopo l'avvio dell'agente:

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

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

   Dovrebbe essere visualizzato:

   ✅ 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 tuo team in Microsoft 365. Quello che è iniziato come codice locale è ora un assistente registrato e pronto per l'azienda dove gli utenti possono creare istanze di agente in tutta la tua organizzazione.

Il ciclo di vita di sviluppo dell'agente è completo, ma l'impatto è appena iniziato. Gran parte di ciò che hai creato durante il ciclo di sviluppo di Agent 365 è open source e accoglie contributi dalla comunità open source. Segnala bug, suggerimenti di nuove funzionalità e pull request:

• Esempi di Agent 365: Hai alcuni modelli di agenti interessanti e divertenti? Condividi il codice del tuo agente con la comunità open source qui!
• Node.js SDK: l'SDK di Agent 365 in Node.js.
• SDK Python: l'SDK Agent 365 in Python.
• .NET SDK: l'SDK Agent 365 in C# (.NET).
• CLI di Agent 365 DevTools: una CLI per supportarti lungo l'intero 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 nell'interfaccia di amministrazione ma non lo trovi nelle app di Teams.

Causa principale: configurazione del portale per sviluppatori mancante.

Soluzione:

1. Ottenere l'ID progetto da a365.generated.config.json: cerca agentBlueprintId.

2. Configura nel portale per sviluppatori:

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

   2. Imposta Tipo di Agente su Basato su API

   3. Imposta URL di notifica sull'endpoint di messaggistica del tuo agente. Trova il valore messagingEndpoint in a365.generated.config.json.

   4. Seleziona Salva.

3. Attendere 5-10 minuti per la propagazione.

Verifica:

• Apri Teams > Apps > cerca l'agente.
• L'agente appare ed è disponibile per essere aggiunto.

Impossibile creare un'istanza dell'agente in Teams

Sintomo: l'agente appare in Teams ma non puoi aggiungere o creare un'istanza; il pulsante Richiedi istanza 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.

Altre informazioni su Frontier.

Verifica:

Le funzionalità Frontier sono disponibili all'interno di Microsoft 365 Copilot e di Microsoft 365 Apps una volta che la licenza e le impostazioni amministrative lo consentono.

L'agente non risponde ai messaggi

Sintomo: crei un'istanza di agente ma non risponde ai messaggi. Non sono presenti log nell'applicazione.

Causa principale: diverse possibili cause: problemi con l'endpoint di messaggistica, problemi di autenticazione o errori di configurazione.

Risoluzione dei problemi di base

1. Verifica che l'app Web sia in esecuzione:

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

2. Verifica 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 dell'applicazione:

   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:

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

2. Strumento di verifica/Configurazione MCP:

   • Verifica che i server MCP siano configurati.
   • Verifica che le autorizzazioni siano concesse.

3. Testa in locale:

   • 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 errato: aggiorna nel portale di Azure e nel portale per sviluppatori.
• App web interrotta: avviala usando portale di Azure o l'interfaccia della riga di comando.
• Token scaduto: aggiorna i token nelle variabili di ambiente della Web App.
• Variabili di ambiente mancanti: controlla le impostazioni dell'app nel portale di Azure.
• Problemi con il server MCP: verifica l'entità servizio e le autorizzazioni.
• Errori di codice: controlla i log delle applicazioni per eventuali eccezioni.

Verifica

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

Potresti anche provare:

• Risoluzione dei problemi relativi alla distribuzione di un agente su Amazon Web Services.
• Risoluzione dei problemi relativi alla distribuzione 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: autorizzazioni mancanti del server MCP, entità servizio non configurata, problemi di connettività di rete o configurazione errata degli strumenti.

Soluzioni

Prova le seguenti soluzioni quando le chiamate agli strumenti falliscono:

• Verifica le autorizzazioni nell’interfaccia di amministrazione

  Rivedi e approva le autorizzazioni richieste del server MCP:

  • Vai a: https://admin.cloud.microsoft/#/agents/all
  • Seleziona il tuo agente > Autorizzazioni
  • Assicurati che l'elenco includa e approvi i server MCP richiesti

• Verifica l'entità servizio

  Esegui lo script di setup una tantum 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 dell'endpoint MCP

  Assicurati di utilizzare l'endpoint MCP di produzione:

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

• Verifica l'identità gestita

  Verifica che l'identità gestita sia abilitata nell'app Web:

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

Verifica

Testa le chiamate agli strumenti tramite Teams e verifica nei log l'esecuzione corretta.

Potresti anche provare questi passaggi:

• Strumenti per la risoluzione dei problemi
• Risoluzione dei problemi nel server di strumenti fittizi

Problemi di assegnazione della licenza

Sintomo: non puoi assegnare una licenza a un utente agente. Vedi errori di licenza nell’interfaccia di amministrazione.

Causa principale: licenze insufficienti, tipo di licenza non corretto o problema di autorizzazioni.

Soluzioni

Prova le seguenti soluzioni quando l'assegnazione della licenza fallisce:

1. Verifica che le licenze siano disponibili:

   • Controlla l'interfaccia di amministrazione di Microsoft 365 >Fatturazione>Licenze.
   • Verifica che Microsoft Agent 365 Frontier sia abilitato per il tenant.

2. Assegna manualmente la licenza:

   • Accedi all'interfaccia di amministrazione di Microsoft 365 >Utenti.
   • Trova l'utente dell'agente.
   • Assegna 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 che il profilo utente nell’interfaccia di amministrazione mostri le licenze assegnate.