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 del Blueprint dell'agente.
• L'applicazione dell'agente è stata pubblicata correttamente secondo Publish agent al centro amministrativo Microsoft.

1. Configura l'agente nel portale sviluppatori di Teams

Dopo la pubblicazione, configura il blueprint dell'agente nel Portale Sviluppatori di Teams per collegare il tuo agente all'infrastruttura di messaggistica di Microsoft 365. Senza questa configurazione, il tuo agente non riceve messaggi da Teams, email o altri servizi Microsoft 365.

1. Ottieni il tuo ID del progetto

   Esegui il comando di visualizzazione -g configurazione a365 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 basato su bot
   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 agente, testala in Microsoft 365 per assicurarti che funzioni correttamente in produzione.

Dopo il deployment, e con le notifiche degli agenti attivate 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.

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.

Vai al centro amministrativo 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 tuo project agente, e creato un utente agente, testa direttamente l'utente agente 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 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'utente agente 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

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

Verifica l'agente appare in Teams

1. Open Teams >Apps

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
✅ Può 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 l'utente agente che appare nell'organizzazione

Nel centro 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 è indicata con lo stato 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

Il tuo agente è ora live nel cloud e pronto a lavorare insieme al tuo team su 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 hai costruito nel ciclo di vita dello sviluppatore dell'agent 365 è open source e accoglie i contributi della community. Segnala bug, richieste di funzionalità e pull request:

• Campioni Agent 365: Hai qualche agente campione interessante e divertente? Condividi qui il tuo codice di agente con la community open source!
• Node.js SDK: L'SDK dell'Agente 365 in Node.js
• SDK Python: L'SDK Agent 365 in Python
• .NET SDK: L'SDK Agent 365 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 basato su bot
   3. Imposta l'ID del bot su agentBlueprintId
   4. Seleziona Salva

3. Aspetta 5-10 minuti per la propagazione.

Verifica:

• App di Teams >> Apri 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à Frontier appaiono all'interno di Microsoft 365 Copilot e Microsoft 365 app una volta che la licenza e le impostazioni amministrative lo permettono.

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 domande:

   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 deployment problema

soluzioni comuni

• Endpoint di messaggistica errato: Aggiornamento nel portale Azure e nel Portale degli sviluppatori
• App web interrotta: Avvialo usando Azure Portal o CLI
• Token scaduto: Token di aggiornamento nelle variabili dell'ambiente Web App
• Variabili ambientali mancanti: Controlla le impostazioni dell'app nel portale 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. Vedi errori di 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 principio del servizio

  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:

• Strumenti di risoluzione dei problemi
• Risoluzione dei problemi nel server di strumenti mock

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 emissione dei permessi.

Soluzioni

Prova le seguenti soluzioni quando la cessione della licenza fallisce:

1. Verifica che le licenze siano disponibili:

   • Controlla lelicenzedi fatturazione> del centro > amministrativo Microsoft 365
   • Assicurati che Microsoft Agent 365 Frontier sia abilitato per il tenant

2. Assegnare manualmente la licenza:

   • Vai al centro > di amministrazione Microsoft 365 Utenti
   • Trova l'utente agentico
   • 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.