Avvio rapido: creare il primo pilota automatico

In questo Avvio rapido, si porta un Autopilot da zero a un'istanza funzionante in Microsoft Teams. Si esegue il provisioning dell'infrastruttura, si crea un progetto autopilot a partire da un agente ospitato, lo si pubblica, lo si fa approvare da un amministratore e si ottiene l'istanza.

Autopilot è un agente che agisce in modo autonomo in Microsoft 365, con una propria identità. Non si costruisce direttamente un pilota automatico: si crea un modello e ogni pilota automatico è un'istanza creata a partire da esso. Per il modello sottostante, vedere Che cos'è un autopilot in Microsoft Foundry?

Prerequisiti

Licenze e registrazione

La creazione di un autopilot con un account utente agente richiede quanto segue:

• Registrare il tenant nel programma di anteprima di Frontier.
• Accettare le condizioni per il servizio di Microsoft Agent 365 dopo la registrazione. Per i dettagli, vedere Visualizzare in anteprima le funzionalità di Microsoft Agent 365 tramite il programma Frontier.
• Verificare che il tenant abbia almeno una licenza Microsoft 365 Copilot o una licenza Microsoft Agent 365, inclusa Microsoft E7.
• Verificare che sia disponibile una licenza Microsoft Agent 365 Frontier. Dopo l'iscrizione, i tenant idonei ricevono una sottoscrizione di anteprima da 25 posti. Ogni istanza di Foundry autopilot usa una licenza, perché ogni istanza crea un account utente agente.

Controllare il conteggio dei posti prima di iniziare. Se il tenant non dispone di posti liberi, la creazione viene completata e quindi ha esito negativo quando si crea l'istanza.

Permissions

Il provisioning crea assegnazioni di ruolo e risorse, motivo per cui il solo Collaboratore non è sufficiente. Per la matrice completa, vedi Riferimento delle autorizzazioni dell'agente ospitato.

Non è necessario un ruolo della directory Microsoft Entra. Foundry crea il progetto di identità dell'agente quando si crea l'agente.

Tools

• interfaccia della riga di comando di Azure
• CLI per sviluppatori di Azure
• Docker, in esecuzione

Creare tutte le risorse in un'area che supporta gli agenti ospitati. Consulta la disponibilità delle Regioni.

Scegliere un esempio di codice

Chi lo fa: tu.

Questa guida introduttiva utilizza un esempio di codice. Tutto ciò che distribuisci deriva dall'esempio, quindi clonane uno prima di iniziare. Entrambi gli esempi eseguono la stessa operazione, quindi scegliere la lingua preferita:

• Esempio di agente Autopilot (C#)
• Esempio di agente Autopilot (Python)

Clona l'esempio, quindi apri la relativa cartella nel terminale. Esegui ogni comando di questa guida rapida da quella cartella.

L'esempio contiene il codice dell'agente, i modelli di infrastruttura e gli script che creano e pubblicano l'agente.

Eseguire il provisioning, la creazione e pubblicazione

Chi esegue questa operazione: l'utente o un amministratore Azure. Questa fase richiede tutte le autorizzazioni nella tabella Permissions, ad eccezione delle due relative all'amministratore e all'assunzione.

Dalla cartella di esempio, accedi con entrambe le CLI e quindi effettua il provisioning.

az login --tenant <tenant-id>
azd auth login --tenant-id <tenant-id>
azd provision

Un comando esegue tre fasi: effettua il provisioning dell'infrastruttura, compila il progetto dell'agente e lo pubblica. Le tre sezioni successive illustrano le operazioni di ogni fase e come confermare il funzionamento.

Risultato previsto: azd provision viene completato senza risorse non riuscite e una richiesta è in attesa nel interfaccia di amministrazione di Microsoft 365.

A seconda delle impostazioni del tenant, potrebbero essere necessari ambiti di accesso aggiuntivi interfaccia della riga di comando di Azure prima del provisioning, ad esempio ambiti per Foundry, Microsoft Graph e Azure Resource Manager. Se azd auth login restituisce un errore di autorizzazione, usare i comandi di accesso nell'esempio README.

È anche possibile eseguire le fasi separatamente, utile quando utenti diversi mantengono le autorizzazioni o quando si vuole modificare l'agente tra le fasi. Usare azd provision --preview per vedere cosa crea il modello prima di eseguirne il commit. Per controllare personalmente ogni fase, richiamare direttamente gli script di creazione e pubblicazione nella cartella dell'esempio scripts invece di lasciare che gli hook post-provisioning li eseguano.

Configurare l'infrastruttura

Autorizzazione necessaria:Proprietario o Collaboratore più Amministratore Controllo di accesso basato su ruoli, nell'ambito del gruppo di risorse.

L'esempio crea un account e un progetto Foundry, una distribuzione di modelli, un Registro Azure Container e Application Insights con un'area di lavoro Log Analytics. Crea inoltre le assegnazioni dei ruoli necessari per queste risorse, che è l’unica cosa che il ruolo Collaboratore da solo non può fare.

Risultato previsto: ogni risorsa nel modello di esempio esiste e segnala l'esito positivo.

Compilare il progetto dell'agente

Autorizzazione necessaria:Utente Foundry nell'ambito del progetto e AcrPush o Container Registry Repository Writer nell'ambito del Registro di sistema.

L'esempio compila il codice dell'agente in un'immagine del contenitore, lo inserisce nel Registro di sistema e crea un agente ospitato insieme alla prima versione dell'agente. Il traffico indirizza a tale versione.

L'agente crea due oggetti Microsoft Entra: un progetto di identità dell'agente e un'identità dell'agente per l'agente stesso. Non crei questi oggetti e non è necessario un ruolo della directory per ottenerli.

Salva i valori di distribuzione. Sono necessari se si risolvono i problemi:

azd env get-values

Risultato previsto: l'output include il nome dell'agente, la versione dell'agente e l'ID progetto.

Per modificare le operazioni eseguite dall'agente prima di pubblicarla, modificare le istruzioni dell'agente e il manifesto dello strumento nell'esempio e quindi eseguire azd provision di nuovo. Ogni esecuzione crea una nuova versione dell'agente.

Pubblicare il progetto dell'agente

Autorizzazione necessaria:Utente Foundry a livello di progetto.

La pubblicazione invia l'agente come modello di Autopilot e lo presenta all'amministratore. L'esempio esegue questa operazione alla fine del provisioning, utilizzando lo script di pubblicazione nella cartella scripts.

La pubblicazione imposta tre elementi che saranno importanti in seguito:

• Pubblicazione con Autopilot, che è ciò che rende questo un progetto che assume le istanze anziché un agente pubblicato nell'archivio degli agenti.
• Ambito di assunzione, che determina chi può creare istanze dopo l'approvazione.
• Dettagli di visualizzazione, inclusi nome, descrizioni e icona.

Risultato previsto: la chiamata di pubblicazione ha esito positivo e una richiesta è in attesa nel interfaccia di amministrazione di Microsoft 365.

API di pubblicazione

L'esempio invoca l'API di pubblicazione di Microsoft 365 per conto dell'utente. Leggere questa sezione se si sta automatizzando il flusso o si desidera sapere cosa invia l'esempio.

POST {{endpoint}}/agents/<agent-name>/microsoft365/publish?api-version=2025-11-15-preview
Authorization: Bearer <access-token>
Content-Type: application/json

{{endpoint}} è l'endpoint del progetto, nel formato https://<resource-name>.services.ai.azure.com/api/projects/<project-name>. Ottieni un token per l'https://ai.azure.com audience:

az account get-access-token --resource https://ai.azure.com --query accessToken -o tsv

Quattro campi distinguono Autopilot da un agente pubblicato negli archivi degli agenti di Microsoft 365 Copilot e di Teams. Impostare tutte e quattro le opzioni seguenti:

L'oggetto agenticUserTemplate contiene le impostazioni di identità per l'account utente dell'agente:

I campi rimanenti sono i dettagli visualizzati dagli utenti e si comportano come per qualsiasi agente pubblicato: agentDisplayName, appVersion, shortDescriptionfullDescription, developerName, developerWebsiteUrl, privacyUrl, e termsOfUseUrl. Impostare canRespondWithoutMention per controllare se Autopilot risponde a tutti i messaggi negli ambienti di Teams o solo quando qualcuno @mentions.

Un corpo della richiesta completo per un pilota automatico:

{
  "agentDisplayName": "Contoso Workstream Manager",
  "publishAsAutopilot": true,
  "publishScope": "Tenant",
  "appVersion": "1.0.0",
  "canRespondWithoutMention": true,
  "shortDescription": "Keeps release work on track.",
  "fullDescription": "Tracks release readiness, updates work items, and sends weekly status.",
  "developerName": "Contoso IT",
  "developerWebsiteUrl": "https://contoso.com",
  "privacyUrl": "https://contoso.com/privacy",
  "termsOfUseUrl": "https://contoso.com/terms",
  "useAgenticUserTemplate": true,
  "agenticUserTemplate": {
    "Id": "digitalWorkerTemplate",
    "File": "agenticUserTemplateManifest.json",
    "SchemaVersion": "0.1.0-preview",
    "AgentIdentityBlueprintId": "<blueprint-client-id>",
    "CommunicationProtocol": "activityProtocol"
  }
}

Per pubblicare invece un agente negli store degli agenti, impostare publishAsAutopilot su false e omettere il modello utente per l'agente. Per tale flusso, vedere Pubblicare agenti in Microsoft 365 e Teams usando l'API REST.

Approvare il progetto

Chi esegue questa operazione: l'amministratore del tenant, con il ruolo di Amministratore globale o Amministratore dell'intelligenza artificiale. I ruoli lettore possono visualizzare la richiesta, ma non possono approvarla.

L'approvazione avvia una procedura guidata composta da quattro passaggi: selezionare a chi assegnare l'agente, applicare un modello di criteri, concedere il consenso e pubblicare.

1. Accedere al interfaccia di amministrazione di Microsoft 365 e quindi selezionare Agenti>tutti gli agenti.

2. Nella scheda Richieste, trova il tuo pilota automatico. Il relativo stato è In attesa di attivazione.

   

3. Seleziona l’autopilot per aprire la procedura guidata Pubblica nuovo agente.

4. In Pubblica per gli utenti verificare i prodotti host e il gruppo di destinatari di pubblicazione. In Attivaselezionare chi può creare istanze dell'agente: Nessuno, Tutti gli utenti o Gruppi specifici. Questa scelta rappresenta l'ambito di selezione.

   

5. In Applica modello scegliere un modello di criteri. I criteri Microsoft vengono applicati per impostazione predefinita e gli amministratori aggiungono e modificano i criteri personalizzati. Questo passaggio mostra anche il numero di licenze autopilot disponibili per il tenant.

   

6. In Accetta autorizzazioni esaminare le autorizzazioni richieste da Autopilot e selezionare Concedi consenso amministratore. Il consenso qui disciplina il token, cioè quali tipi di chiamate Autopilot può effettuare. Non concede a nessuno i dati del team.

   

7. In Rivedi e termina controllare il gruppo di destinatari, l'ambito di attivazione e il modello di criteri e quindi selezionare Pubblica.

   

8. Verificare l'autopilot nella scheda Registry. Il suo stato è Disponibile.

   

Risultato previsto: l'Autopilot viene visualizzato nel registro come Disponibile e le persone incluse nell'ambito di assunzione possono creare istanze.

Crea la tua istanza

Chi lo fa: tu, se l'amministratore ti ha incluso nell'ambito di selezione.

Dopo che Autopilot è presente nel registro, è possibile acquisirlo dall'App Store di Microsoft Teams o dallo Store degli agenti di Microsoft 365 Copilot.

1. Trova il pilota automatico sotto Agenti per il tuo team.

   In Microsoft Teams, vai a App>Agenti per il tuo team.

   

   In Microsoft 365 Copilot passare ad Agenti>agenti per il team.

   

2. Selezionare l'autopilot, quindi selezionare Crea istanza.

3. Denominare l'istanza, impostarne l'alias e il dominio e confermare chi lo gestisce. Il nome può avere un massimo di 32 caratteri.

   

4. Fare clic su Crea.

La creazione dell'istanza consuma una licenza e crea l'identità dell'agente e l'account utente dell'agente dell'istanza stessa. Sei diventato il suo manager.

Risultato previsto: autopilot avvia una chat di Teams con l'utente e viene visualizzato nell'organigramma.

Pulire le risorse

Per rimuovere le risorse Azure create, eseguire:

azd down

L'eliminazione delle risorse di Azure non rimuove le istanze che le persone hanno assunto dal progetto. Collaborare con l'amministratore per ritirare il progetto.

Risoluzione dei problemi

Contenuto correlato

• Che cos'è un pilota automatico in Microsoft Foundry? spiega il modello di identità e perché i piloti automatici usano i progetti guida.
• Il ciclo di vita di Autopilot in Microsoft Foundry illustra cosa accade dopo la pubblicazione, incluso l'aggiornamento e la fine di un autopilot.
• L’integrazione di Microsoft Agent 365 con Foundry include la sincronizzazione del registro, la raccolta dei dati e la residenza dei dati.