La solution è il contenitore, e per esportare deve essere unmanaged

Quando crei un agente in Copilot Studio, l’agente nasce già dentro una solution di Power Platform: viene aggiunto automaticamente a una solution predefinita, che puoi però cambiare. La documentazione descrive la solution come un “carrier” per gli agenti, cioè il veicolo con cui li sposti fra ambienti diversi.

Per lavorare sulle solution non serve uscire da Copilot Studio: seleziona i tre punti (…) sulla barra laterale e poi Solutions. Da lì crei una solution personalizzata con New solution, compilando Display Name, Name, Publisher e Version. Due scelte pesano più delle altre: usare un publisher personalizzato con il proprio prefix, perché il prefisso serve a evitare collisioni di nomi e non è modificabile dopo che i componenti sono stati creati; e impostare la solution come preferita, con Set as your preferred solution in fase di creazione oppure con Set preferred solution nell’elenco delle solution, così i nuovi agenti nascono lì e non nella default.

Il punto che l’esame verifica più spesso è la coppia managed/unmanaged. Una solution appena creata è unmanaged: è la copia di lavoro, quella che modifichi in ambiente di sviluppo. Una solution managed è l’artefatto che distribuisci a valle, e la doc è categorica: non si esportano solution managed. Se converti la tua solution in managed, devi crearne una nuova. La regola operativa è quindi esportare l’unmanaged come managed verso test e produzione, tenendo l’unmanaged solo nell’ambiente di sviluppo. Se ti trovi davanti a una domanda in cui l’export è bloccato, la solution convertita è il sospetto numero uno.

Aggiungere un agente esistente e i suoi oggetti richiesti

Un agente costruito prima di avere una solution personalizzata va aggiunto a mano. Apri la solution, seleziona Add existing, poi Agent e di nuovo Agent; nell’elenco Add existing agents scegli gli agenti e confermi con Add.

Aggiungere l’agente non basta. Gli oggetti che gli hai attaccato sono componenti distinti, e qui conviene fermarsi sulla terminologia, perché sono quattro cose diverse: un topic è un pezzo di conversazione autorizzata, un tool è un’azione che l’agente può invocare, una knowledge source è una fonte da cui attingere risposte, un agent flow è un flusso Power Platform. Per portarseli dietro, nel pannello Objects individui l’agente sotto Agents, apri i tre punti (⋮), poi Advanced e Add required objects. La stessa operazione va ripetuta sui workflow quando usi agent flow ed environment variable. Se in solution non ci sono ancora environment variable, le aggiungi con Add existing, More, Environment variable.

Attenzione all’ordine con i custom connector: vanno importati prima, in una solution separata, e solo dopo arriva la connection reference con la solution dell’agente.

Che cosa viaggia davvero? Le istruzioni dell’agente, cioè il main prompt, sono incluse nell’export. Alcuni componenti, come topic personalizzati e knowledge source, possono invece non essere inclusi se sono archiviati come risorse o tabelle Dataverse separate, a seconda di come li hai creati o collegati. Alcune proprietà non si trasferiscono affatto: Conversation ID, CDS Bot ID, Environment ID e i commenti a livello di topic o di nodo; l’agente importato può ritrovarsi senza icona e con i dettagli dei canali vuoti. Un vincolo secco: non si esporta una solution che contiene un agente con dei punti nel nome di un topic.

Infine la trappola classica: rimuovere l’agente dalla solution non rimuove i suoi componenti, che vanno rimossi separatamente. E vale il contrario: non toccare i componenti unmanaged dell’agente direttamente dalla solution senza rimuovere anche l’agente, perché export e import falliscono.

Environment variable, connection reference e variabile globale

Tre oggetti con nomi simili e ruoli diversi. La environment variable porta i parametri di configurazione che cambiano fra ambienti. La connection reference è un componente di solution che punta a una connessione, cioè a una credenziale di autenticazione per un connettore. La variabile globale non c’entra nulla con il rilascio: vive nella conversazione e contiene stato a runtime.

La distinzione fra le prime due è esplicita nella doc: la connessione non è memorizzata nella environment variable. Con il tipo di dati Data source scegli connettore, connessione e tipo di parametro, ma la connessione serve solo a recuperare i valori disponibili, per esempio i siti SharePoint a cui hai accesso o le liste di un sito. Per SharePoint servono infatti due environment variable distinte, una per Site e una per List, oltre a una connessione valida. Gli altri tipi disponibili sono Decimal number, Text, JSON, Two options e Secret.

Per non trascinare un valore di sviluppo in produzione si agisce sul Current Value: nella solution apri la environment variable e sotto Current Value scegli … e poi Remove from this solution. Il valore resta nel tuo ambiente di sviluppo ma non finisce nel pacchetto, e in import le variabili senza valore né default chiedono un valore.

Environment variable  HR site        Data Type: Data source
  Default Value       (facoltativo, usato se manca il Current Value)
  Current Value       rimosso dalla solution prima dell'export
Connection reference  SharePoint - HR
  Connection          credenziale, fornita nell'ambiente di destinazione

Che cosa va rifatto a destinazione

Copilot Studio ha elementi che non sono solution-aware e richiedono passaggi post-deploy nell’ambiente a valle: Azure Application Insights settings, Manual authentication settings, Direct Line / Web channel security settings, Deployed channels e Sharing, sia verso altri maker sia verso gli utenti finali. Dopo l’import, quindi, riconfiguri l’autenticazione utente dell’agente, e ricorda che devi pubblicare l’agente importato prima di poterlo condividere. Le connessioni le verifichi dalla pagina Connection Settings nelle impostazioni dell’agente, dove lo stato può essere Connected, Not Connected, Deactivated, Expired o Stale.

La confusione tipica da evitare in sede d’esame: pensare che una solution importata correttamente basti a rendere l’agente operativo. Non basta. La solution porta struttura, istruzioni e riferimenti; canali, telemetria, autenticazione manuale e condivisione sono lavoro manuale a destinazione.