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 si verificano problemi, vedere la sezione Risoluzione dei problemi .

Prerequisiti

• Il blueprint dell'agente è configurato correttamente come descritto nella fase di configurazione del blueprint dell'agente.
• L'applicazione Agent è stata pubblicata correttamente come descritto in Pubblicare l'agente nell'interfaccia di amministrazione Microsoft.

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

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

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.

   Note

   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. Impostare tipo di agente su basato su API

   2. Impostare URL di notifica per l'endpoint di messaggistica dell'agente. Trova il messagingEndpoint valore in a365.generated.config.json.

   3. Seleziona Salva.

   

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

Altre informazioni sui progetti di identità dell'agente e sulla configurazione del portale per 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 aver distribuito, pubblicato e configurato il progetto agente e creato un utente agente, testare l'utente dell'agente direttamente in Microsoft Teams:

Inizia i test

1. Cerca il tuo nuovo utente agente in Teams.

   Note

   Il processo di creazione dell'utente dell'agente è asincrono. L'utente dell'agente può richiedere da alcuni minuti a diverse ore per diventare ricercabile dopo la sua 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.

Lista di controllo per la verifica

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 mostra: Basato sull'API✅URL di notifica corrisponde all'endpoint di messaggistica dell'agente ✅ Mostra messaggio salvato correttamente

Verifica che l'agente appaia in Teams

1. Aprire > Teams

2. Cerca il nome del tuo agente

   ✅ Agent viene visualizzato nei risultati ✅ della ricerca Mostra l'icona e la descrizione dell'agente

Verifica di poter creare un instance agent per i team

Seleziona il tuo agente nelle app Teams

✅ Il pulsante Richiedi/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 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 pertinente

Verifica che l'agente possa eseguire azioni

Se si configurano gli strumenti, testare la funzionalità degli strumenti. Ad esempio, se si aggiunge il server Mail MCP, inviare un messaggio di posta elettronica di prova a se stessi.

L'agente dovrebbe:

✅ Confermare la richiesta ✅ Eseguire la chiamata ✅ allo strumento Conferma completamento

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 verificare le operazioni dell'agente, controllare i log dell'applicazione usando il comando az webapp log tail .

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

Cosa cercare nei log:

✅ Richieste in ingresso da Teams ✅ Autenticazione riuscita ✅ Esecuzione delle chiamate dello strumento ✅ Risposte inviate ❌ Messaggi di errore o eccezioni

Verifica l'osservabilità nel centro amministrativo

Dopo che il tuo agente inizia a lavorare:

1. Passare 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 registrato e pronto per l'azienda dove gli utenti possono creare istanze di agenti 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 tuo codice agente con la community open source qui!
• Node.js SDK: SDK di Agent 365 in Node.js.
• Python SDK: l'SDK di Agent 365 in Python.
• .NET SDK: Agent 365 SDK in C# (.NET).
• Interfaccia della riga di comando di Agent 365 DevTools: CLI per supportare l'intero ciclo di sviluppo di Agent 365.

Troubleshooting

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

L'agente non appare in Teams

Sintomo: L'agente viene visualizzato nell'interfaccia di amministrazione, ma non è possibile trovarlo nelle app di Teams.

Causa principale: Configurazione mancante del Portale Sviluppatori.

Soluzione:

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

2. Configura nel Portale Sviluppatori:

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

   2. Impostare tipo di agente su basato su API

   3. Impostare URL di notifica per l'endpoint di messaggistica dell'agente. Trova il messagingEndpoint valore in a365.generated.config.json.

   4. Seleziona Salva.

3. Attendere 5-10 minuti per la propagazione.

Verifica:

• Apri Teams > Apps > e cerca l'agente.
• L'agente viene visualizzato ed è disponibile per l'aggiunta.

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

Sintomo: L'agente viene visualizzato in Teams, ma non è possibile aggiungere o creare un'istanza; Il pulsante Richiedi istanza non funziona.

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

Soluzione: Contattare l'amministratore tenant per verificare che Microsoft Agent 365 Frontier sia abilitato per il tenant.

Altre informazioni 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: Si crea un'istanza dell'agente, ma non risponde ai messaggi. Non vengono visualizzati log 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: Iniziare a usare il portale di Azure o l'interfaccia della riga di comando.
• Token scaduto: Aggiornare i token nelle variabili di ambiente dell'app Web.
• Variabili di ambiente mancanti: Controllare Le impostazioni dell'app nel portale di Azure.
• Problemi del server MCP: Verificare il principale del servizio e le autorizzazioni.
• Errori di codice: Controllare i log applicazioni per individuare le eccezioni.

Verifica

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

Potresti anche provare:

• Risolvere i problemi di distribuzione di un agente in Amazon Web Services.
• Risolvere i problemi di distribuzione di un agente in 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.

È anche possibile provare questi passaggi:

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

Fallimento della cessione della licenza

Sintomo: Non è possibile assegnare una licenza a un utente dell'agente. Nell'interfaccia di amministrazione vengono visualizzati errori di licenza.

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 le>di fatturazione> dell'interfaccia di amministrazione di Microsoft 365.
   • Verificare che Microsoft Agent 365 Frontier sia abilitato per il tenant.

2. Assegnare manualmente la licenza:

   • Passare all'interfaccia > di amministrazione di Microsoft 365 Utenti.
   • Trova l'utente agente.
   • Assegnare una 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

Verificare che il profilo utente nell'interfaccia di amministrazione mostri le licenze assegnate.