Condividi tramite

Distribuire agenti in Microsoft Teams

Microsoft Teams presenta problemi di distribuzione univoci per gli agenti di Copilot Studio a causa dell'ambiente di conversazione persistente. A differenza delle distribuzioni basate sul Web in cui le sessioni vengono reimpostate automaticamente, Teams gestisce i thread di conversazione a tempo indeterminato, che possono causare contesto non aggiornato, scadenza dei token e contenuto memorizzato nella cache obsoleto.

Questo articolo fornisce indicazioni per la distribuzione efficace degli agenti di Copilot Studio in Teams. Si apprenderà come gestire sessioni persistenti, implementare strategie di debug e garantire prestazioni affidabili nei cicli di vita delle conversazioni estesi.

Considerazioni chiave trattate:

  • Gestione del ciclo di vita della sessione e gestione dell'inattività
  • Tecniche di debug per conversazioni persistenti
  • Strategie di distribuzione per il controllo della versione e l'aggiornamento
  • Modelli di implementazione specifici di Teams

Seguire queste procedure per creare agenti affidabili che eseguano in modo coerente nell'ambiente Teams, fornendo un feedback chiaro agli utenti sulle modifiche di stato e sul comportamento del sistema.

Perché la distribuzione di Teams è diversa

Le conversazioni di Teams vengono mantenute tra giorni senza reimpostazione automatica. A differenza delle sessioni di Web Chat, l'evento ConversationStart viene generato solo la prima volta che viene aggiunto un agente. La reinstallazione dell'app non innesca nuovamente questo evento.

La persistenza di Teams crea diversi rischi:

  • Contesto obsoleto: la cronologia delle conversazioni rimane a meno che non venga cancellata.
  • Scadenza del token: i connettori possono scadere durante sessioni lunghe.
  • Limiti di contesto: i messaggi accumulati possono superare i limiti del modello.
  • Memorizzazione nella cache degli aggiornamenti: gli utenti potrebbero continuare a interagire con la logica obsoleta.

La gestione proattiva dello stato e indicazioni chiare per gli utenti sono essenziali.

Gestire il ciclo di vita della sessione

Gestire il ciclo di vita della sessione con il controllo dell'inattività.

Implementare la reimpostazione dell'inattività

Crea un nuovo topic e seleziona il trigger L'utente è inattivo per un po' per avviare un flusso di reimpostazione dopo un periodo di inattività dell'utente.

  1. Aggiungere il trigger di inattività e impostare un timeout (ad esempio, 15 minuti).
  2. Aggiungere 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. Terminare la conversazione e contrassegnare la sessione come risolta.

Screenshot dell'editor di argomenti di Copilot Studio che mostra un flusso di lavoro di reimpostazione dell'inattività con trigger, messaggio, valori di variabili non crittografati e nodi di conversazione finale.

Questo approccio impedisce l'overflow del contesto e garantisce un comportamento prevedibile quando un utente ritorna.

Fornire indicazioni dopo la reimpostazione

Dopo la cancellazione dello stato, inviare un messaggio che spiega cosa è successo. Ad esempio: "Sembra che la conversazione sia diventata inattiva, quindi sto cancellando il contesto precedente per sicurezza. Dici "hello" per riavviare."

Poiché ConversationStart si attiva solo una volta, la prima volta che un agente viene aggiunto, l'argomento Greeting diventa il tuo effettivo punto di inizializzazione. La richiesta all'utente di pronunciare "hello" garantisce che la logica di avvio venga eseguita correttamente.

Offrire un comando di reimpostazione autonomo

Aggiungere messaggi che informano gli utenti che possono digitare un comando specifico: "Se qualcosa sembra errato, provare a digitare /debug clearstate per aggiornare lo stato".

Questo comando forza una reimpostazione completa della conversazione:

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

Usare 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 per gli agenti distribuiti in Teams, usare il OnKnowledgeRequested trigger .

Usare OnKnowledgeRequested per visualizzare le query riscritte

Copilot Studio riscrive le domande dell'utente prima di eseguire il recupero. Se si abilita il OnKnowledgeRequested trigger, è possibile:

  • Diagnosticare le mancate corrispondenze delle finalità
  • Informazioni sul modo in cui le query vengono riscritte
  • Aumentare l'attendibilità utente durante il debug

Annotazioni

È possibile configurare il OnKnowledgeRequested trigger solo nella visualizzazione codice usando YAML. Non c'è supporto per il progettista visivo.

Aggiungere un messaggio che visualizza sia le query per parole chiave sia quelle semantiche generate. Per 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.

Benefici:

  • Aiuta a eseguire il debug di mancate corrispondenze nell'intento.
  • Mostra agli utenti ciò che l'agente cerca.
  • Crea l'attendibilità nelle azioni dell'agente.
  • Aiuta gli autori durante i test.

Controllo della versione e affidabilità degli aggiornamenti

La gestione delle versioni degli agenti e la garanzia che gli utenti interagiscono con la logica più recente siano particolarmente importanti in un ambiente persistente come Teams.

Versione del bot Surface in un saluto o in un argomento dedicato

Includere un identificatore di versione usando l'argomento Greeting o un argomento Version dedicato:

Contoso Helpdesk Bot – Version 1.3 (Nov 2025)

Aggiornare questo valore con ogni pubblicazione per aiutare gli utenti e i team di supporto a verificare quale compilazione è attiva. L'aggiornamento dei metadati della versione aggiorna anche il contenuto memorizzato nella cache. La modifica del nome o della descrizione dell'agente richiede a Teams di caricarlo come nuovo aggiornamento.

Abilitare "Forza la versione più recente" durante la pubblicazione

L'impostazione Forza versione più recente garantisce che Teams carichi la logica dell'agente più recente al successivo invio di un messaggio da parte dell'utente. Questa impostazione consente anche di invalidare le versioni memorizzate nella cache. Tuttavia, forzando un aggiornamento interrompe qualsiasi conversazione in corso.

Screenshot della finestra di dialogo per la pubblicazione dell'agente con avvisi relativi alle credenziali, al modello di anteprima e con l'opzione

Considerazioni sull'implementazione specifiche di Teams

Teams ha comportamenti particolari che richiedono particolare attenzione.

Tratta il tema del saluto come la tua logica d'avvio

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

  • Inserire la logica di inizializzazione in Greeting.
  • Aggiungere istruzioni chiare nella descrizione dell'app Teams.
  • Ricorda agli utenti: "Dopo un timeout, digitare "hello" per avviare una nuova conversazione".

Ottimizzare trigger e fallback

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

  • Gestisce più varianti di saluto.
  • Include la gestione dell'addio.
  • Fornisce più espressioni di esempio.
  • Offre risposte amichevoli e utili di riserva.
  • Usa parole chiave per guidare gli utenti ad argomenti pertinenti.
  • Usa OnKnowledgeRequested per diagnosticare gli intenti mancati.
  • Reindirizza agli argomenti pertinenti in base alle parole chiave.
  • Richiede agli utenti di riformulare se il bot è effettivamente bloccato.

Convalidare il comportamento di autenticazione del connettore

Quando si usano connettori (ServiceNow, Outlook e altri), testare:

  • Comportamento della scheda di accesso iniziale.
  • Cosa accade quando il token scade e come viene rinnovato automaticamente.
  • Come funzionano l'invalidazione forzata e i flussi di riacquisizione del consenso.

Suggerimento

I connettori potrebbero non aggiornare i token durante le sessioni estese. Usare le funzioni di reimpostazione dell'inattività o /debug clearstate per riattivare OAuth quando necessario. Comunicare questo comando per supportare team e utenti per la risoluzione dei problemi rapida.

Testare in condizioni reali

Poiché Teams mantiene lo stato tra le sessioni, i test devono riflettere l'esperienza utente reale:

  1. Eseguire la distribuzione usando Mostra solo a me.
  2. Testare scenari a lungo termine (ritornare dopo ore).
  3. Pubblicare gli aggiornamenti e confermare che l'agente cambia versione.
  4. Convalidare il rendering delle schede adattive su desktop e dispositivi mobili.
  5. Testare le azioni in contesti conversazionali diversi.

Elenco di controllo per la distribuzione

Fatto? Task
✓ Trigger di inattività configurato per cancellare la cronologia delle conversazioni
✓ La messaggistica utente spiega le reimpostazioni e guida il riavvio
✓ /debug clearstate documentata per gli utenti
✓ OnKnowledgeRequested abilitata per la trasparenza durante lo sviluppo
✓ Identificatore della versione incluso nelle risposte
✓ Forzare la versione più recente abilitata in base alle esigenze
✓ L'argomento di Greeting include la logica di inizializzazione.
✓ Il comportamento di fallback è intuitivo
✓ Autenticazione del connettore testata per la scadenza e il rinnovo
✓ Completamento dei test in Teams in condizioni reali

Punti chiave

  • Gestire il ciclo di vita della sessione configurando i trigger di inattività e usando le opzioni di cancellazione dello stato quando appropriato.
  • Migliorare la trasparenza visualizzando l'attività di sistema tramite la riscrittura delle query e i messaggi correlati allo stato.
  • Tenere conto dei comportamenti specifici di Teams, ad esempio la gestione dei messaggi di saluto manuali e la gestione della memoria persistente.
  • Mantenere l'affidabilità dell'agente implementando le procedure di controllo delle versioni e applicando gli aggiornamenti quando necessario.
  • Supportare l'autonomia degli utenti fornendo comandi per la risoluzione dei problemi self-service e opzioni di ripristino guidate.
  • Last updated on