Eseguire la migrazione da Prompt Flow a Microsoft Agent Framework in Foundry (versione classica)

Prompt Flow è uno strumento di sviluppo che semplifica l'intero ciclo di sviluppo di applicazioni di intelligenza artificiale basate su modelli di linguaggio di grandi dimensioni. Prompt Flow offre una soluzione completa che semplifica il processo di creazione di prototipi, sperimentazione, iterazione e distribuzione delle applicazioni di intelligenza artificiale.

Questo articolo illustra le differenze principali tra Prompt Flow e Agent Framework, esegue il mapping dei concetti di Prompt Flow agli equivalenti di Agent Framework, illustra le considerazioni specifiche di Foundry e descrive un piano di migrazione.

Per iniziare la migrazione, esaminare la mappatura concettuale per comprendere gli equivalenti di Agent Framework per il flusso corrente, quindi seguire Controllare, ricompilare e convalidare il flusso di lavoro del flusso Prompt e Distribuire e gestire il flusso di lavoro di Agent Framework migrato per istruzioni dettagliate passo dopo passo.

Prerequisiti

• Un'applicazione Prompt Flow esistente in esecuzione su Microsoft Foundry.
• Python 3.10 o versione successiva.
• Una sottoscrizione Azure con un progetto Foundry e un modello di chat distribuito.
• Microsoft Agent Framework SDK: pip install agent-framework agent-framework-foundry.
• interfaccia della riga di comando di Azure installato e autenticato (az login completato).

Perché eseguire la migrazione

Agent Framework sostituisce il grafo visivo basato su YAML di Prompt Flow con un framework di Python (e .NET) code-first che fornisce:

• Flussi di lavoro sicuri per i tipi: WorkflowBuilder convalida il grafico di esecuzione in fase di compilazione, rilevando le incompatibilità di tipo e i nodi non raggiungibili prima del runtime.
• Supporto agente integrato: crea agenti di intelligenza artificiale con FoundryChatClient().as_agent() e registra funzioni Python come strumenti senza registrazione separata dello strumento in YAML.
• Tracciamento OpenTelemetry nativo: l'Agent Framework emette automaticamente span per ogni invocazione dell'executor e chiamata LLM. Foundry include l'integrazione nativa per il tracciamento che non richiede codice aggiuntivo.
• Distribuzione flessibile: Impacchettare i flussi di lavoro come applicazioni FastAPI standard e distribuirle su App contenitore di Azure, Funzioni di Azure o Foundry Agent Service.
• Orchestrazione multi-agente: route, fan-out, fan-in e diramazione condizionale tra agenti specializzati che usano add_edge(), add_fan_out_edges() e add_fan_in_edges().

Considerazioni specifiche per Foundry

Usare FoundryChatClient per gli endpoint del progetto Foundry

Gli endpoint del progetto Foundry (https://<resource>.services.ai.azure.com) richiedono FoundryChatClient, non AzureOpenAIChatClient. L'AzureOpenAIChatClient è destinato a endpoint OpenAI non elaborati Azure (https://<resource>.openai.azure.com) e non funziona con gli URL del progetto Foundry.

import os

from agent_framework.foundry import FoundryChatClient
from azure.identity import DefaultAzureCredential

client = FoundryChatClient(
    project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
    model=os.environ["FOUNDRY_MODEL"],
    credential=DefaultAzureCredential(),
)

Variabili di ambiente

Il .env file usa variabili specifiche di Foundry:

FOUNDRY_PROJECT_ENDPOINT=https://<your-resource>.services.ai.azure.com
FOUNDRY_MODEL=<your-deployment-name>

Carica queste variabili all'inizio della tua applicazione con load_dotenv() dal pacchetto python-dotenv. Per le distribuzioni di produzione, archiviare i segreti in Azure Key Vault anziché .env file.

Tracciamento

Foundry include l'integrazione nativa per il tracciamento con Agent Framework. Gli agenti compilati con Agent Framework generano automaticamente tracce quando la traccia è abilitata per il progetto Foundry. Non sono necessari pacchetti o configurazioni aggiuntivi. Per informazioni dettagliate, vedere Configurare il tracciamento per i framework degli agenti di intelligenza artificiale.

Opzioni di distribuzione

Oltre a App contenitore di Azure, gli utenti di Foundry possono distribuire flussi di lavoro di Agent Framework nel servizio Foundry Agent per un'esperienza di hosting completamente gestita.

Mapping dei concetti chiave

La tabella seguente esegue il mapping dei concetti di Prompt Flow agli equivalenti di Agent Framework.

Parametri di tipo WorkflowContext

WorkflowContext usa parametri di tipo per controllare la modalità di comunicazione di un executor:

Importare Never da typing (Python 3.11+) o typing_extensions (Python 3.10). Il Never tipo indica che un executor non invia messaggi downstream. Usarlo negli executor del terminale che producono solo l'output finale del flusso di lavoro.

Piano di migrazione

Una migrazione tipica passa attraverso cinque passaggi. Seguite i passaggi in ordine. Ogni passaggio presenta un controllo che conferma l'intenzione di procedere. I primi passaggi (controllo, ricompilazione, convalida) si concentrano sul raggiungimento della parità funzionale con il flusso esistente. I passaggi successivi (operazioni, cutover) gestiscono la preparazione dell'ambiente di produzione e la migrazione del traffico.

Per le procedure pratiche di ricompilazione e convalida, vedere Controllare, ricompilare e convalidare il flusso di lavoro del prompt flow. Per la distribuzione e il passaggio, vedere Distribuire e operare il flusso di lavoro dell'Agent Framework migrato.

1. Controlla e mappa. Esportare il file flow.dag.yaml e mappare ogni nodo nel relativo equivalente di Agent Framework usando la tabella Mapping dei concetti presente in questo articolo. Identificare i nodi che necessitano di logica personalizzata e nodi che eseguono il mapping direttamente ai componenti di Agent Framework predefiniti. Prima di procedere, confermare che la tabella di mappatura dei nodi includa ogni nodo del flusso.

2. Ricostruire. Implementare il flusso di lavoro nuovamente usando le classi WorkflowBuilder e Executor. Inizia con un percorso lineare unico nel tuo flusso, quindi aggiungi rami, espansioni e connessioni condizionali. Procedi quando i file Python producono un output funzionante che rispecchia il comportamento del Prompt Flow.

3. Convalidare. Eseguire il flusso di richiesta originale e il nuovo flusso di lavoro di Agent Framework side-by-side con gli stessi input. Usare SimilarityEvaluator da AZURE AI Evaluation SDK per assegnare punteggi alla parità di output. Punta a un punteggio di somiglianza medio di almeno 3,5 (su 5) nel tuo parity_results.csv prima di continuare.

4. Eseguire la migrazione delle operazioni. Integrare la traccia OpenTelemetry, distribuire su App contenitore di Azure o sul servizio agente Foundry e aggiungere un controllo di qualità CI/CD che esegue la valutazione di parità in ogni richiesta di pull. Verificare che le tracce vengano visualizzate nel progetto Foundry, che la distribuzione sia funzionante e che la pipeline superi i test.

5. Cutover. Passare il traffico di produzione alla distribuzione di Agent Framework. Dopo aver confermato l'operatività stabile, decommissionare gli endpoint, le connessioni e le risorse di calcolo di Prompt Flow.

Contenuto correlato

Iniziare con la guida alla ricostruzione e alla convalida, quindi procedere alla distribuzione e al cutover. Usare la documentazione di Agent Framework e gli esempi di migrazione come riferimento.

• Controllare, ricompilare e convalidare il flusso di lavoro del prompt flow in Microsoft Agent Framework
• Distribuire e gestire il flusso di lavoro di Agent Framework migrato
• Configurare il tracciamento per i framework degli agenti di IA
• documentazione di Microsoft Agent Framework
• Microsoft Agent Framework GitHub repository
• Esempi di migrazione da PromptFlow a MAF
• Azure AI Evaluation SDK