Bot Slack e Teams

Porta Archyl negli strumenti che il tuo team usa già. Menziona @Archyl in Slack o Microsoft Teams e fai domande sull'architettura del tuo software — il modello C4, gli ADR, le dipendenze, la proprietà e altro — per ottenere risposte basate sui tuoi dati reali, direttamente nel canale.

Panoramica

Il bot è collegato per organizzazione. Una volta che un amministratore collega uno spazio di lavoro, chiunque al suo interno può interrogare il bot menzionandolo. Il bot risponde con i permessi dell'amministratore che lo ha collegato e il suo ambito sono i progetti della tua organizzazione.

Per impostazione predefinita quell'ambito è tutti i progetti dell'organizzazione. Un amministratore può limitare qualsiasi canale a un team o a un insieme di progetti — vedi Limitare un canale a un team o a progetti più avanti.

Il bot risponde in due modi:

Passi dall'una all'altra selezionando una chiave API in Organizzazione → Bot → Strumenti MCP (vedi Abilitare gli strumenti MCP più sotto).

Collegare Slack

1. In Archyl, vai su Organizzazione → Bot.
2. Clicca su Aggiungi a Slack. Verrai portato su Slack per autorizzare l'app Archyl e scegliere uno spazio di lavoro.
3. Dopo l'approvazione, torni in Archyl e lo spazio di lavoro appare sotto Connesso.
4. In Slack, invita il bot in un canale e menzionalo:

   @Archyl cosa dipende dal servizio di pagamento?
   

Il bot risponde in un thread per mantenere ordinati i canali. Menzionalo di nuovo (nel canale o nel thread) per porre una domanda di follow-up.

• Modifica riesegue l'installazione di Slack (aggiorna la connessione).
• Disconnetti rimuove l'integrazione.

Collegare Microsoft Teams

Teams usa un pacchetto dell'app e un codice di collegamento monouso.

1. In Archyl, vai su Organizzazione → Bot e clicca su Scarica l'app Teams per ottenere archyl-teams-app.zip.
2. In Teams, installa l'app: App → Gestisci le tue app → Carica un'app personalizzata, e seleziona il .zip. (Se non vedi questa opzione, un amministratore di Teams deve consentire il caricamento di app personalizzate o caricarla nel catalogo app della tua organizzazione.)
3. Tornato in Archyl, clicca su Collega Teams. Otterrai un codice come @Archyl link 6GXH6NKL.
4. In Teams, invia esattamente questo messaggio al bot Archyl (in una chat 1:1, semplicemente link 6GXH6NKL). Il bot risponde ✅ Collegato alla tua organizzazione Archyl.
5. Ora menzionalo con le tue domande:

   @Archyl quale team possiede l'API gateway?
   

Il codice di collegamento è valido per 15 minuti ed è monouso. Generane uno nuovo in qualsiasi momento dalla scheda Bot.

Nota: i bot di Microsoft Teams richiedono un account aziendale o scolastico (Microsoft 365) — non funzionano con un account Microsoft personale.

Abilitare gli strumenti MCP (modalità agentica)

Per impostazione predefinita, il bot risponde direttamente dal contesto della tua architettura. Per consentirgli di usare gli strumenti MCP dal vivo — cercare progetti per nome, tracciare dipendenze, creare ADR o documentazione e altro — assegnagli una chiave API:

1. Crea una chiave API in Profilo → Chiavi API (o riutilizzane una esistente).
2. Vai su Organizzazione → Bot → Strumenti MCP e seleziona quella chiave.
3. Tutto qui — la prossima volta che qualcuno menziona il bot, ragionerà sulla tua architettura con gli strumenti del server MCP e mostrerà ogni azione che esegue prima di rispondere.

L'ambito è importante:

• Una chiave di lettura consente al bot di cercare informazioni ma non di modificare nulla.
• Una chiave di scrittura gli consente inoltre di creare o aggiornare elementi, ADR, documentazione, ecc. Scegli una chiave di scrittura solo se vuoi che il bot apporti modifiche.

Seleziona Nessuna in qualsiasi momento per disattivare la modalità agentica e tornare alle risposte dirette.

Limitare un canale a un team o a progetti

Per impostazione predefinita ogni canale vede tutti i progetti della vostra organizzazione. Spesso è ciò che si vuole, ma un canale #pagamenti di solito non dovrebbe rispondere a domande sulla piattaforma di credito.

Per limitarlo, andate su Organizzazione → Bot → Ambito del canale e fate clic su Limita un canale:

1. Cosa vede il canale — un team, oppure uno o più progetti.
2. Quale canale — scegliete la piattaforma, date un nome al canale per l'elenco e fate clic su Ottieni il comando.
3. Incollate il comando — inviate @Archyl scope <codice> in quel canale. Il bot conferma e il canale compare nell'elenco non appena l'ambito è applicato.

I codici sono validi 15 minuti e a uso singolo. Per riampliare un canale, fate clic su Rimuovi accanto ad esso nell'elenco.

Perché un codice e non un pulsante? Il bot risponde con i permessi dell'amministratore che lo ha collegato e non può sapere chi sta scrivendo in un canale. Il codice è l'autorizzazione: è stato generato da un amministratore in Archyl, quindi l'ambito non può essere modificato da chiunque scriva nel canale.

Alcune cose da sapere:

• L'ambito per team segue il team. Un progetto aggiunto in seguito a un team limitato è coperto automaticamente, senza dover rilimitare il canale.
• L'ambito è applicato, non suggerito. Vale per ogni chiamata agli strumenti e ogni elenco: un canale limitato non può leggere un altro progetto, nemmeno se glielo si chiede per identificativo.
• ADR, documenti e contratti API a livello di organizzazione restano visibili: appartengono all'organizzazione, non a un progetto.
• Il nome è solo un'etichetta. Il bot non ha accesso ai nomi dei canali; quello che digitate è ciò che mostra l'elenco, e il collegamento riguarda il canale in cui incollate il comando.

Avviare esecuzioni di agenti da Slack o Teams

Puoi affidare lavoro a un agente gestito senza uscire da Slack o Microsoft Teams:

@Archyl run [Payments API] add retries to the webhook sender

Il bot risponde nel thread con un link all'esecuzione, poi vi scrive di nuovo quando l'agente ha bisogno di te (un piano da rivedere o una domanda) e quando termina, con il link alla pull request. In Slack ti menziona in questi aggiornamenti; in Teams arrivano come risposte nello stesso thread.

Collega prima il tuo account di chat. Un'esecuzione scrive codice e apre pull request, quindi viene creata a tuo nome, con i tuoi accessi, non con i permessi dell'amministratore che ha collegato lo spazio di lavoro. Vai su Profilo → Account di chat, fai clic su Collega il mio account Slack o Collega il mio account Microsoft Teams e invia @Archyl connect <code> ovunque il bot sia presente su quella piattaforma. I codici sono validi 15 minuti e a uso singolo. Scollega l'account dalla stessa scheda o con @Archyl disconnect. Slack e Teams si collegano separatamente.

Come viene interpretato il comando:

• Progetto — il nome tra parentesi quadre. In un canale limitato a un solo progetto puoi ometterlo: @Archyl run fix the flaky login test. Un canale limitato a più progetti accetta solo progetti all'interno del suo ambito.
• Profilo dell'agente — il profilo predefinito della tua organizzazione, oppure un altro con profile:<name> prima del compito: @Archyl run [Web] profile:frontend-fixer align the pricing cards.
• Accesso e quota — ti serve l'accesso in modifica al progetto. Ogni esecuzione viene conteggiata nelle esecuzioni degli agenti della tua organizzazione, esattamente come un'esecuzione avviata nell'app. Gli agenti gestiti sono disponibili nei piani Scale e Custom.

Le revisioni del piano e le risposte alle domande dell'agente avvengono in Archyl, nella pagina dell'esecuzione linkata dal bot.

Anteprime dei link in Slack

Quando qualcuno pubblica un link a una pagina di Archyl in un canale Slack, il bot lo espande in un'anteprima: il titolo, il tipo e lo stato, il progetto e un estratto. Funziona con i link a un progetto, a un elemento del diagramma, a una decisione, a una pagina di documentazione, a una richiesta di modifica e a una discussione. Usa Copia link in Archyl per ottenere link da condividere (Menzioni, citazioni e link).

Ciò che viene mostrato in anteprima segue le stesse regole delle risposte del bot:

• l'anteprima viene generata con i permessi dell'amministratore che ha collegato lo spazio di lavoro, e solo per i progetti dell'organizzazione a cui è collegato;
• in un canale limitato, un link a un progetto fuori dal suo ambito resta un link semplice;
• anche un link a qualcosa che non esiste, o che il bot non può vedere, resta un link semplice, quindi un'anteprima non rivela mai se una pagina esiste;
• i link vengono mostrati in anteprima una volta pubblicato il messaggio, non mentre lo si scrive.

Microsoft Teams non mostra ancora l'anteprima dei link di Archyl.

Attivare le anteprime

Le anteprime richiedono due permessi Slack, links:read e links:write. Gli spazi di lavoro collegati prima del 18 ottobre 2026 devono essere ricollegati da Organizzazione → Bot per concederli.

Se ospiti Archyl in autonomia con la tua app Slack, configurala anche nelle impostazioni dell'app Slack:

1. In Event Subscriptions, iscriviti all'evento bot link_shared.
2. Nella stessa pagina, aggiungi il tuo dominio Archyl in App unfurl domains, per esempio archyl.example.com.

Come funzionano i permessi

• Il bot risponde con i permessi dell'amministratore che ha collegato lo spazio di lavoro, nell'ambito dei progetti della tua organizzazione.
• Le esecuzioni degli agenti sono l'eccezione: @Archyl run agisce come la persona che lo ha digitato, tramite il suo account Slack o Teams collegato, e richiede il suo accesso in modifica al progetto.
• Un canale limitato vede solo i progetti del suo team o del suo elenco. Viene applicato a ogni chiamata agli strumenti e a ogni elenco, non lasciato al prompt.
• In modalità agentica, ciò che il bot può leggere e modificare è ulteriormente regolato dall'ambito della chiave API selezionata.
• Ogni domanda viene conteggiata nell'utilizzo IA della tua organizzazione, esattamente come la chat nell'app.

Suggerimenti

• Sii preciso con i nomi. Puoi riferirti a progetti, sistemi, ADR e documenti per nome — il bot li associa agli elementi corretti per te.
• Continua nel thread. Menziona di nuovo il bot per proseguire una serie di domande.
• Il Markdown funziona nativamente. Le risposte sono formattate per ogni piattaforma (grassetto, elenchi, link, codice).
• Limita i canali condivisi. Restringi #pagamenti al team Pagamenti e la risposta sbagliata non finirà mai nel canale sbagliato (Limitare un canale a un team o a progetti).

Passaggi successivi

• Server MCP — Collega agenti IA e IDE agli strumenti di Archyl
• Notifiche webhook — Invia eventi di architettura a sistemi esterni