Esercitazione: Configurare un bot di Teams per l'agente SRE di Azure

In questa esercitazione distribuisci l'agente SRE di Azure come bot di Microsoft Teams, consentendo al team di comunicare direttamente nei DM o @-menzionandolo nei canali.

Suggerimento

Operazioni eseguite in questa esercitazione:

• L'agente viene visualizzato come bot in Microsoft Teams.
• I membri del team possono inviare un DM al bot per indagini private.
• I membri del team possono @menzionare il bot nei canali per la risoluzione dei problemi collaborativi.
• Le risposte tornano automaticamente a Teams.

Prerequisiti

Prima di iniziare, assicurarsi di avere le risorse e l'accesso seguenti:

Requisito	dettagli
Agente SRE di Azure	Un agente distribuito e in esecuzione
Sottoscrizione di Azure	Per creare la risorsa del servizio Azure Bot
Identità gestita assegnata dall'utente	L'identità che l'agente utilizza (creata durante la fase di distribuzione dell'agente)
Accesso amministratore di Teams	Per pubblicare l'app bot nell'organizzazione

Informazioni generali

Configurare il bot di Teams in tre passaggi:

1. Distribuire il servizio Azure Bot: registrare l'endpoint dell'agente con Bot Framework.
2. Compilare il pacchetto dell'app Teams: Creare il manifest che Teams necessita per installare il bot.
3. Pubblica in Teams: rendere il bot disponibile per l'organizzazione.

Passaggio 1: Distribuire il servizio Azure Bot

Il servizio Azure Bot instrada i messaggi tra Teams e l'agente. La base di codice del tuo agente include un modello Bicep che crea questa risorsa.

Raccogliere i valori obbligatori

Prima della distribuzione, raccogliere i valori seguenti:

Valore	Dove trovarlo	Esempio
ID client dell'app bot	L'ID client dell'identità gestita del tuo agente	aaaaaaaa-0000-1111-...
Il dominio dell'app bot	FQDN del contenitore dell'applicazione dell'agente	my-agent.eastus2.azuresre.ai
Nome visualizzato del bot	Nome che si desidera visualizzare per il bot in Teams	SRE Agent
Tipo di app	UserAssignedMsi per l'identità gestita (scelta consigliata)	UserAssignedMsi
ID del locatario	Identificativo tenant di Microsoft Entra	aaaaaaaa-0000-1111-...

Eseguire la distribuzione usando l'interfaccia della riga di comando di Azure

Eseguire il comando seguente per distribuire la risorsa del servizio Bot.

az deployment group create \
  --name sre-agent-bot \
  --resource-group <RESOURCE_GROUP> \
  --template-file deploy/teams-bot.bicep \
  --parameters \
    resourceBaseName=<BOT_NAME> \
    botAadAppClientId=<MANAGED_IDENTITY_CLIENT_ID> \
    botAppDomain=<AGENT_FQDN> \
    botDisplayName="SRE Agent" \
    microsoftAppType=UserAssignedMsi \
    microsoftAppTenantId=<TENANT_ID>

Il modello Bicep crea le risorse seguenti:

• Una risorsa del servizio Azure Bot.
• Una connessione a un canale di Teams su quel bot.
• Endpoint di messaggistica che punta a https://<AGENT_FQDN>/api/messages.

Configura il tuo agente

L'agente richiede tre variabili di ambiente per accettare i messaggi di Teams. Impostare queste variabili nell'app contenitore.

Variable	Valore	Descrizione
ID applicazione bot di Teams	ID Cliente dell'identità gestita	Identifica il bot per il Bot Framework
Tipo di app bot di Teams	UserAssignedMsi	Metodo di autenticazione (scelta consigliata per l'identità gestita)
Identificativo Tenant del Bot di Teams	Identificativo tenant di Microsoft Entra	Definisce l'ambito dell'autenticazione per il tenant

I nomi esatti delle variabili di ambiente seguono la convenzione di associazione di configurazione ASP.NET per la distribuzione. Senza queste variabili, l'endpoint di Teams restituisce 503 e il bot viene visualizzato offline.

Suggerimento

Con UserAssignedMsi, non è necessaria una password o un segreto. L'identità gestita gestisce automaticamente l'autenticazione.

Passaggio 2: Compilare il pacchetto dell'app Teams

Il pacchetto dell'app Teams è un file ZIP che contiene un manifesto e icone. La codebase dell'agente include un modello e uno script di compilazione.

Creare il file di ambiente

Creare un .env file con i valori di distribuzione.

TEAMS_APP_ID=<UNIQUE_GUID_FOR_TEAMS_APP>
AAD_APP_CLIENT_ID=<MANAGED_IDENTITY_CLIENT_ID>
BOT_DOMAIN=<AGENT_FQDN>
BOT_NAME="SRE Agent"
RESOURCE_SUFFIX=<SHORT_NAME>
MICROSOFT_APP_TYPE=UserAssignedMsi
MICROSOFT_APP_TENANT_ID=<TENANT_ID>
RESOURCE_GROUP=<RESOURCE_GROUP>

Annotazioni

Generare un nuovo GUID per TEAMS_APP_IDo creare un'app nel portale per sviluppatori di Teams e usarne l'ID.

Eseguire lo script di compilazione

Eseguire lo script di compilazione per generare il pacchetto dell'app.

cd TeamsResources
chmod +x build.sh
./build.sh

Lo script esegue le azioni seguenti:

1. Sostituisce i tuoi valori nel modello di manifest.
2. Distribuisce il servizio Bot in Azure.
3. Crea appPackage.zip con il manifesto e le icone.

Il risultato appPackage.zip è pronto per il caricamento in Teams.

Passaggio 3: Pubblicare in Teams

Caricare il pacchetto dell'app e verificare che il bot sia disponibile nell'organizzazione.

Caricare il pacchetto dell'app

Seguire questa procedura per pubblicare il bot nell'organizzazione.

1. Aprire l'interfaccia di amministrazione di Teams in admin.teams.microsoft.com.
2. Passare a app Teams>Gestisci app.
3. Selezionare Carica nuova app.
4. Seleziona appPackage.zip.
5. Selezionare Pubblica per rendere disponibile l'app nell'organizzazione.

Verificare in Teams

Verificare che il bot sia accessibile e risponda.

1. Apri Microsoft Teams.
2. Selezionare App nella barra laterale.
3. Cercare il nome del bot (ad esempio, "Agente SRE").
4. Selezionare Aggiungi per installarlo.
5. Avviare una chat digitando "Hello".

L'agente risponde con un messaggio di benvenuto che introduce se stesso e le relative funzionalità.

Testare l'integrazione

Dopo la pubblicazione, testare il bot sia nei messaggi diretti che nelle menzioni del canale.

Test DM

Aprire una chat diretta con il bot:

You: Check the health of my resources

Agent: Searching your subscription for resource health...
✅ 10/12 resources healthy
⚠️ web-app-prod: High memory (87%)

Test del canale

In un canale del team, menziona il bot con @

@SREAgent what's the error rate on api-gateway?

Il bot invia un riconoscimento rapido durante l'esecuzione dell'analisi completa, quindi pubblica la risposta dettagliata.

Come funziona

La tabella seguente descrive il flusso di messaggi tra Teams e l'agente.

Passo	Che succede
Si invia un messaggio in Teams	Teams lo fornisce all'agente POST /api/messages
Agent riceve il messaggio	Bot Framework SDK autentica e analizza il messaggio
Mapping dei thread	L'agente mappa la conversazione di Teams su un thread interno
Elaborazione	Stesso motore di ragionamento della chat del portale con accesso completo agli strumenti
Risposta rapida (solo canali)	Breve notifica pubblicata durante l'esecuzione dell'analisi
Risposta completa	La risposta dell'agente viene sottoposta a polling e restituita a Teams

Le risposte vengono recapitate alla conversazione di Teams poco dopo l'elaborazione. Lo stesso thread è visibile nel portale per i dettagli completi delle chiamate agli strumenti.

Risoluzione dei problemi

Usare la tabella seguente per risolvere i problemi comuni relativi alla configurazione del bot di Teams.

Sintomo	Resolution
Il bot non risponde	Verificare che le variabili di ambiente del bot di Teams siano impostate nell'app contenitore. Verificare che l'ID app sia impostato su un ID client di identità gestita reale.
503 dall'endpoint di Teams	Il bot non è configurato. Impostare le tre variabili di ambiente necessarie.
Errori di autenticazione	Verificare che l'ID client dell'identità gestita corrisponda a quello del Servizio BotmsaAppId.
Bot non trovato in Teams	Verificare che l'app sia pubblicata e che l'utente abbia l'autorizzazione per installare le app.
Funziona nel portale ma non in Teams	Verificare che il servizio Bot sia distribuito e che l'endpoint di messaggistica sia raggiungibile.

Passo successivo

Chatta dai tuoi strumenti

Contenuti correlati

• Chatta dai tuoi strumenti