Distribuire agenti in Microsoft Teams

Microsoft Teams presenta sfide uniche di implementazione per gli agenti Copilot Studio a causa del suo ambiente di conversazione persistente. A differenza delle implementazioni basate su Web, dove le sessioni vengono reimpostate automaticamente, Teams mantiene i thread di conversazione indefinitamente, il che può portare a contesto obsoleto, scadenza del token e contenuti memorizzati in cache obsoleti.

Questo articolo fornisce indicazioni per distribuire efficacemente gli agenti di Copilot Studio in Teams. Impari a gestire le sessioni persistenti, implementare strategie di debug e garantire prestazioni affidabili lungo i cicli di vita delle conversazioni estese.

Considerazioni chiave trattate:

• Gestione del ciclo di vita delle sessioni e dell'inattività
• Tecniche di debug per conversazioni persistenti
• Strategie di controllo delle versioni e distribuzione degli aggiornamenti
• Modelli di implementazione specifici per Teams

Segui queste pratiche per sviluppare agenti solidi che offrano prestazioni coerenti nell’ambiente Teams, fornendo agli utenti un feedback chiaro sui cambiamenti di stato e sul comportamento del sistema.

Perché la distribuzione di Teams è diversa

Le conversazioni di Teams persistono per giorni senza una reimpostazione automatica. A differenza delle sessioni di chat Web, l'evento ConversationStart si attiva solo la prima volta che un agente viene aggiunto. La reinstallazione dell'app non riattiva questo evento.

La persistenza di Teams crea diversi rischi:

• Contesto non aggiornato: la cronologia della conversazione rimane finché non viene cancellata.
• Scadenza del token: i connettori possono scadere durante sessioni lunghe.
• Limiti del contesto: i messaggi accumulati possono superare i limiti del modello.
• Cache degli aggiornamenti: gli utenti potrebbero continuare a interagire con una logica obsoleta.

Una gestione proattiva dello stato e una guida chiara per l'utente sono essenziali.

Gestire il ciclo di vita della sessione

Gestisci il ciclo di vita della sessione con la gestione dell'inattività.

Implementare le reimpostazioni per inattività

Crea un nuovo argomento e seleziona il trigger L'utente è inattivo da un po' di tempo per avviare un flusso di reimpostazione dopo un periodo di inattività dell'utente. Altre informazioni su trigger di inattività sugli schemi specifici di Teams, incluse le variabili di controllo e il modello di conversazione persistente.

1. Aggiungi il trigger di inattività e imposta un timeout (ad esempio, 15 minuti).
2. Aggiungi uno o più nodi Cancella i valori delle variabili per rimuovere le variabili di sessione e la cronologia delle conversazioni, per impedire l'overflow del contesto.
3. Termina la conversazione e contrassegna la sessione come risolta.

Questo approccio previene il sovraccarico di contesto e garantisce un comportamento prevedibile quando un utente ritorna.

Fornire indicazioni dopo la reimpostazione

Dopo aver azzerato lo stato, invia un messaggio che spieghi cosa è successo. Ad esempio: "Sembra che la conversazione sia diventata inattiva, quindi sto cancellando il contesto precedente per sicurezza. Pronuncia "ciao" per riavviare".

Poiché ConversationStart si attiva solo una volta, la prima volta che un agente viene aggiunto, l'argomento Formula di saluto diventa il tuo punto di inizializzazione effettivo. Invitare l'utente a dire "ciao" assicura che la logica di avvio funzioni correttamente.

Offrire un comando di reimpostazione autonomo

Aggiungi messaggi che avvisano gli utenti che possono digitare un comando specifico: "Se qualcosa non funziona, prova a digitare /debug clearstate per aggiornare il mio stato".

Questo comando esegue una reimpostazione completa della conversazione:

• Cancella lo stato della conversazione
• Rimuove le informazioni del connettore nella cache
• Riautentica i connettori
• Carica la versione più recente dell'agente

Utilizza questo comando quando:

• Il bot sembra "bloccato" con informazioni obsolete
• L'autenticazione del connettore è scaduta
• Dopo gli aggiornamenti della logica del bot
• Quando il comportamento sembra incoerente

Aumentare la trasparenza e migliorare il debug

Per aumentare la trasparenza e migliorare il debug degli agenti distribuiti in Teams, usa il trigger OnKnowledgeRequested.

Usare OnKnowledgeRequested per visualizzare le query riscritte

Copilot Studio riscrive le domande degli utenti prima di effettuare il recupero. Se attivi il trigger OnKnowledgeRequested, puoi:

• Diagnosticare le discrepanze degli intenti
• Capire come vengono riscritte le query
• Aumentare la fiducia degli utenti durante il debug

Aggiungi un messaggio che mostri sia le query basate su parole chiave che quelle semantiche generate. Ad esempio:

kind: AdaptiveDialog
beginDialog:
  kind: OnKnowledgeRequested
  id: main
  actions:
    - kind: SendActivity
      id: sendActivity_debug
      activity: |-    
        **Debug**: sending this lexical query "{System.KnowledgeSearchQuery}"
        **Debug**: sending this semantic query "{System.SearchQuery}"
inputType: {}
outputType: {}

Questa query fornisce l'accesso in sola lettura alla query di ricerca ottimizzata (riscrittura della query) generata dall'orchestratore dalla domanda dell'utente.

Vantaggi:

• Aiuta a eseguire il debug delle mancate corrispondenze nell'intento.
• Mostra agli utenti cosa cerca l'agente.
• Aumenta la fiducia nelle azioni dell'agente.
• Assiste gli autori durante i test.

Controllo delle versioni e affidabilità degli aggiornamenti

Gestire le versioni degli agenti e assicurare che gli utenti interagiscano con la logica aggiornata è particolarmente importante in un ambiente persistente come Teams.

Mostrare la versione del bot nel messaggio di saluto o in un argomento dedicato

Includi un identificatore di versione utilizzando l’argomento Formula di saluto o un argomento Versione dedicato:

Contoso Helpdesk Bot – Version 1.3 (Nov 2025)

Aggiorna questo valore a ogni pubblicazione per aiutare utenti e team di supporto a verificare quale build è attiva. L’aggiornamento dei metadati della versione aggiorna anche i contenuti memorizzati nella cache. La modifica del nome o della descrizione dell'agente fa sì che Teams lo carichi come una nuova versione.

Abilita "Forza versione più recente" quando pubblichi

L'impostazione Forza versione più recente garantisce che Teams carichi la logica più recente dell'agente la prossima volta che l'utente invia un messaggio. Questa impostazione contribuisce anche a invalidare le versioni memorizzate nella cache. Tuttavia, forzare un aggiornamento interrompe qualsiasi conversazione in corso.

Considerazioni specifiche sull'implementazione in Teams

Teams ha comportamenti unici che richiedono particolare attenzione.

Considera l'argomento Formula di saluto come la tua logica di avvio

Poiché ConversationStart viene generato una sola volta, la prima volta che viene aggiunto un agente:

• Inserisci la logica di inizializzazione in Formula di saluto.
• Aggiungi istruzioni chiare nella descrizione dell'app Teams.
• Ricorda agli utenti: "Dopo un timeout, digita "ciao" per avviare una nuova conversazione."

Ottimizza trigger e fallback

Gli utenti di Teams interagiscono in modo naturale e imprevedibile. Assicurati che il tuo bot:

• Gestisca diverse varianti di saluto.
• Includa la gestione dei saluti di congedo.
• Fornisca molteplici espressioni di esempio.
• Offre risposte di fallback cordiali e utili.
• Utilizzi parole chiave per guidare gli utenti verso argomenti rilevanti.
• Utilizzi OnKnowledgeRequested per aiutare a diagnosticare intenti mancanti.
• Reindirizzi verso argomenti rilevanti in base a parole chiave.
• Inviti gli utenti a riformulare se il bot è davvero bloccato.

Convalidare il comportamento di autenticazione del connettore

Quando si utilizzano connettori (ServiceNow, Outlook e altri), testa:

• Come si comporta la scheda di accesso iniziale.
• Cosa succede quando il token scade e come viene automaticamente rinnovato.
• Come funzionano i flussi di invalidazione forzata e di riconsenso.

Eseguire test in condizioni reali

Poiché Teams mantiene lo stato tra le sessioni, i tuoi test dovrebbero riflettere l’esperienza utente reale:

1. Distribuisci usando Mostra solo a me.
2. Testa scenari di lunga durata (con ritorno dopo alcune ore).
3. Pubblica gli aggiornamenti e conferma che l'agente è passato alla versione più recente.
4. Convalida il rendering delle schede adattive su desktop e dispositivi mobili.
5. Testa le azioni in vari contesti conversazionali.

Elenco di controllo per la distribuzione

Punti chiave

• Gestisci il ciclo di vita della sessione configurando trigger di inattività e utilizzando opzioni per la cancellazione dello stato quando opportuno.
• Migliora la trasparenza evidenziando l'attività di sistema tramite riscritture di query e messaggi relativi allo stato.
• Considera i comportamenti specifici di Teams, come la gestione dei saluti manuali e della memoria persistente.
• Mantieni l'affidabilità dell'agente implementando procedure di controllo delle versioni e applicando aggiornamenti quando necessario.
• Supporta l'autonomia degli utenti fornendo comandi autonomi di risoluzione dei problemi e opzioni di recupero guidato.

Informazioni correlate

• Connettere e configurare un agente per Teams e Microsoft 365
• Concetti chiave: pubblicare e distribuire l'agente