Eseguire la migrazione dalle applicazioni agente al nuovo endpoint agente e all'esperienza di pubblicazione

Questa guida illustra in che modo l'esperienza di pubblicazione dell'agente è cambiata in Microsoft Foundry. Confronta il modello legacy (che ha creato una risorsa applicazione agente separata) con il nuovo modello a oggetti agente e illustra la migrazione degli agenti esistenti e delle applicazioni pubblicate.

Panoramica della modifica

Il nuovo modello a oggetti agente comprime le applicazioni agente e le distribuzioni degli agenti nell'oggetto Agent stesso. In precedenza, la pubblicazione creava una risorsa di applicazione dell'agente separata con la propria identità, endpoint e distribuzione. A questo punto, ogni agente ha queste funzionalità dal momento in cui viene creato.

Prima (modello precedente)

1. Modello di risorsa: un agente (piano dati), un'applicazione agente (piano di controllo) e deployment (piano di controllo) sono oggetti separati.
2. Proprietà dell'oggetto Agent: id (identificatore univoco per l'agente), namee versions (versione più recente dell'agente).
3. Identità: Gli agenti non pubblicati in un progetto Foundry condividono un'identità dell'agente Entra e un modello agente Entra. Al momento della pubblicazione, un agente riceve un'identità univoca e un blueprint con riferimento alla risorsa dell'applicazione agente.
4. Pubblicazione: due movimenti. Prima di tutto, la pubblicazione di un agente crea una risorsa applicazione agente e una distribuzione, in cui la distribuzione fa riferimento alla versione dell'agente pubblicata. L'applicazione agente espone un endpoint stabile che instrada il 100% del traffico a quella versione. Una distribuzione supporta la gestione del ciclo di vita di avvio/arresto. Il secondo gesto è che l'applicazione agente può quindi essere pubblicata in Microsoft 365 e Teams.

Dopo (nuovo modello)

1. Modello di risorsa: esistono solo oggetti Agent (piano dati e piano di controllo). Assorbono le responsabilità precedentemente possedute da Applicazione e Distribuzione dell'Agente.
2. Proprietà dell'oggetto Agent: id, name, versions, agent_endpoint (endpoint stabile), protocols, authorization_schemes, version_selector, blueprint, instance_identity e agent_card (visualizza i dettagli e le funzionalità dell'agente per i consumatori e A2A).
3. Identità: per impostazione predefinita, tutti gli agenti ricevono un'Entra Agent Identity e un Entra Agent Blueprint univoci. Bring Your Own Entra Agent Blueprint è supportato ma non è quello predefinito.
4. Pubblicazione: due movimenti equivalenti. Selezionare prima di tutto una versione dell'agente da esporre tramite l'endpoint stabile. In secondo luogo, rendere pubblico l'endpoint stabile dell'agente in M365/Teams.

Il cambiamento principale: la creazione di un agente è l'unico passaggio necessario per ottenere un endpoint stabile e un'identità univoca dell'agente. Non esiste un passaggio di pubblicazione separato per l'endpoint. La pubblicazione ora si riferisce in modo specifico alla distribuzione dell'agente tramite canali M365 e Teams.

Tipi di agente durante la transizione

Durante il periodo di transizione, è possibile che si verifichino tre tipi di agenti:

Il agent.identity valore distingue i nuovi agenti dagli agenti legacy: null significa legacy, diverso da null significa nuovi.

Cosa continua a funzionare

• Le applicazioni agente esistenti continuano a gestire il traffico attraverso gli endpoint.
• Gli agenti pubblicati in M365/Teams tramite le applicazioni agente continuano a funzionare.
• L'endpoint del progetto rimane disponibile per la compatibilità con le versioni precedenti,anche se non è più il percorso consigliato.
• Gli agenti legacy rimangono completamente funzionanti per lo sviluppo e il test nel progetto Foundry.

Percorsi di migrazione

Percorso 1: Nuovi agenti (nessuna azione necessaria)

Se si creano agenti dopo l'aggiornamento del modello a oggetti, ottengono automaticamente il nuovo modello con identità univoca, endpoint stabile e tutte le nuove funzionalità. Non è necessaria alcuna migrazione.

Percorso 2: Aggiornare un agente legacy

Gli agenti legacy (creati prima dell'aggiornamento) usano l'identità del progetto condiviso e non possono essere pubblicati tramite il nuovo modello. Per eseguire l'aggiornamento:

1. Verifica se il tuo agente è un agente legacy:

   GET {endpoint}/agents/{agent_name}?api-version=2025-11-15-preview
   Authorization: Bearer {{token}}
   Foundry-Features: AgentEndpoints=V1Preview
   

   Se instance_identity è Null nella risposta, si tratta di un agente legacy.

2. Creare un nuovo agente usando la stessa definizione:

   Nota

   Attualmente non è possibile aggiornare un agente legacy a un'identità univoca. Per ottenere un'identità univoca, creare un nuovo agente usando la stessa definizione (istruzioni, strumenti, configurazione del modello). Il nuovo agente riceve automaticamente un'identità univoca e un endpoint stabile. È previsto un percorso di aggiornamento sul posto per un aggiornamento futuro.

3. Dopo aver creato il nuovo agente, ha un'identità univoca ed è possibile usare tutte le nuove funzionalità, inclusa la nuova esperienza di pubblicazione che usa l'endpoint dell'agente.

Percorso 3: Eseguire la migrazione di un'applicazione agente esistente

Se si dispone di un'applicazione agente pubblicata in M365/Teams e si vuole eseguire la migrazione al nuovo modello, seguire questa procedura:

1. Creare un nuovo agente usando la stessa definizione dell'agente dietro l'applicazione agente (istruzioni, strumenti, configurazione del modello). Il nuovo agente riceve automaticamente un'identità univoca e un endpoint stabile. Per informazioni dettagliate, vedere Percorso 2 .

2. Pubblicare il nuovo agente per Microsoft 365 e Teams dal portale Foundry. La pubblicazione è disponibile solo tramite il portale foundry. Non è disponibile alcuna API di pubblicazione pubblica. Per la procedura, vedere Pubblicare gli agenti per Microsoft 365 Copilot e Microsoft Teams.

3. Verificare che il nuovo agente funzioni in M365/Teams con il nuovo endpoint stabile.

4. Disattivare l'applicazione agente precedente dopo aver verificato il funzionamento del nuovo agente:

   • Eliminare la risorsa Azure dell'applicazione dell'agente. L'eliminazione della risorsa non comporta l'eliminazione delle versioni dell'agente.
   • Per mantenere funzionanti le integrazioni esistenti, aggiornare qualsiasi codice che faccia riferimento all'URL dell'endpoint applicazione precedente per usare il nuovo URL dell'endpoint stabile dell'agente.

Modifiche all'URL dell'endpoint

Durante la migrazione, aggiornare qualsiasi codice o integrazione che faccia riferimento al formato dell'endpoint precedente:

Pubblicazione dell'esperienza utente durante la transizione

Durante la transizione, è possibile che si verifichino esperienze di pubblicazione diverse a seconda del tipo di agente:

• Nuovi agenti (agent.identity != null): viene visualizzata la nuova esperienza utente di pubblicazione con selezione dell'endpoint stabile, routing della versione e pubblicazione diretta in M365/Teams.
• Agenti legacy (agent.identity == null): viene visualizzata l'esperienza utente di pubblicazione dell'applicazione agente legacy. Un banner può indicare che la nuova esperienza è disponibile con un collegamento per l'aggiornamento.

Cronologia e obsolescenza

Faq

È necessario eseguire immediatamente la migrazione?

No. Le applicazioni agente esistenti continuano a funzionare. Tuttavia, le nuove funzionalità (suddivisione del traffico, più protocolli, disabilitazione/abilitazione, A2A) sono disponibili solo nel nuovo modello di agente.

L'applicazione agente smetterà di funzionare?

Non immediatamente. Le applicazioni agente sono deprecate con preavviso e un periodo di migrazione. Continuano a funzionare fino alla data di fine del supporto.

È possibile avere sia un'applicazione agente che un agente di nuovo modello per lo stesso agente sottostante?

Durante la transizione, sì. L'applicazione agente e il nuovo endpoint agente possono coesistere. Tuttavia, sono risorse separate con identità e endpoint separati.

Cosa succede ai ruoli di controllo degli accessi basati sui ruoli di Azure assegnati alle risorse dell'applicazione agente?

RBAC sulle risorse dell'applicazione dell'agente non si trasferisce all'oggetto agente. È necessario assegnare ruoli (ad esempio Foundry Agent Consumer) nella risorsa agente per il nuovo endpoint.

L'agente usa strumenti che eseguono l'autenticazione con l'identità dell'agente. Cosa cambia?

Con il nuovo modello, l'agente ha un'identità univoca dalla creazione, quindi non viene apportata alcuna modifica all'identità in fase di pubblicazione. Tuttavia, se si esegue la migrazione da un agente legacy, l'agente ottiene una nuova identità diversa sia dall'identità del progetto condiviso che da qualsiasi identità dell'applicazione agente. È necessario riassegnare l'RBAC (controllo degli accessi basato sui ruoli) per le risorse a valle.

Contenuto correlato

• applicazioni Agente in Microsoft Foundry
• Pubblicare gli agenti per Microsoft 365 Copilot e Teams
• Concetti relativi all'identità dell'agente in Foundry