Gli sviluppatori di Microsoft Teams vengono avvertiti che chiamare ogni estensione "bot" sta causando guasti in produzione. Nel 2026, i limiti della piattaforma stessa — 10-15 secondi per rispondere a un messaggio — trasformeranno i bot con un'architettura errata in tempeste di timeout, costringendo i team a riprogettare le proprie pipeline.

Perché la distinzione è importante

Teams offre tre tipi di estensioni, ognuna progettata per un diverso modello di interazione. Mescolarle impone il runtime sbagliato, l'SDK sbagliato e il modello di scalabilità errato.

Teams apps, bot e agent – cosa sono

  • Teams apps – Tab di superficie, pagine statiche o semplici componenti UI all'interno del client Teams. Sono essenzialmente web app: stateless, renderizzate su richiesta e ospitate come qualsiasi altro servizio HTTP. Non è previsto alcun flusso conversazionale.
  • Bots – Costruiti con il Bot Framework SDK, i bot seguono dialoghi scriptati. La loro logica è un albero deterministico if/else che decide la risposta successiva basandosi esclusivamente sull'attività in arrivo. Poiché il percorso decisionale è noto in anticipo, la risposta rientra nella breve finestra di timeout della piattaforma.
  • Agents – Entità guidate da obiettivi che ricevono un obiettivo di alto livello, un set di strumenti e un LLM (large language model). Utilizzando l'Agents SDK o Semantic Kernel, l'LLM sceglie quale strumento chiamare, in quale ordine e quando chiedere chiarimenti all'utente. Il flusso è dinamico e spesso richiede molteplici chiamate esterne e un ragionamento complesso.

La distinzione è netta: un bot è deterministico; un agent è probabilistico e orchestra le chiamate agli strumenti a runtime.

La trappola del timeout

Quando gli sviluppatori inseriscono ragionamenti complessi — prompt LLM, ricerche in database o chiamate API esterne — direttamente all'interno dell'handler dei messaggi di un bot, Teams rileva che la richiesta persiste oltre la finestra di 10-15 secondi. La piattaforma interrompe la risposta e riprova, il che può causare un effetto a cascata con duplicazione del lavoro e throttling. Il sintomo appare come un errore intermittente di "bot non rispondente", ma la causa principale è architettonica.

Costruire una pipeline asincrona pronta per la produzione

  1. Webhook entry point – L'endpoint HTTP del bot accetta l'attività di Teams e ne conferma immediatamente la ricezione.
  2. Queue the event – L'handler invia il payload a una coda persistente come Azure Service Bus.
  3. Background worker – Una Azure Durable Function, un trigger di Service Bus o qualsiasi worker a lunga esecuzione preleva il messaggio, esegue il ragionamento dell'LLM o l'orchestrazione degli strumenti e invia la risposta finale a Teams tramite l'API di proactive messaging del Bot Framework.

Poiché il webhook iniziale risponde istantaneamente, Teams non raggiunge mai il timeout e il lavoro pesante procede al proprio ritmo. La coda bufferizza i picchi e i worker scalano automaticamente in base alla lunghezza della coda in attesa (backlog).

Guida rapida alla decisione (il test della lavagna)

  • È possibile disegnare l'intero albero decisionale prima di scrivere qualsiasi codice? Sì → Costruisci un bot. Il flusso deterministico si adatta al modello del Bot Framework e rientra nella finestra di risposta.
  • Il problema è definito da un obiettivo di alto livello e da un elenco di possibili strumenti? Sì → Costruisci un agent. Lascia che l'LLM pianifichi e invochi gli strumenti; delega la pianificazione a un worker in background.

Cosa aspettarsi in seguito

Questa guida è la prima parte di una serie per gli sviluppatori .NET 9 che costruiscono soluzioni intelligenti per Teams su Azure.

Se stai già riscontrando errori di "Bot timed out" nei log di Teams, la soluzione è semplice: disaccoppia il webhook dal carico di lavoro pesante, adotta un worker guidato da una coda e scegli il tipo di estensione corretto fin dall'inizio. La piattaforma ha un limite di timeout, ma la tua architettura può evitarlo.

Takeaway: Etichettare erroneamente un'estensione di Teams come un bot impone un design sincrono che Teams non può sostenere. Separa la richiesta dal ragionamento, scegli l'SDK corretto e la tua soluzione Teams rimarrà reattiva anche quando il "cervello" che la guida è un agent basato su LLM.