Distribuire un agente in Microsoft Foundry con l'estensione dell'agente AI della CLI per sviluppatori di Azure

Questo articolo illustra come usare l'estensione dell'agente di intelligenza artificiale Azure Developer cli (azd) per configurare e distribuire un agente in Microsoft Foundry. L'estensione consente di eseguire lo scaffolding e distribuire gli agenti dal terminale o dall'editor, combinando le funzionalità Foundry con azd i comandi del ciclo di vita (azd init, azd up) per un flusso di lavoro coerente da locale a cloud.

Funzionalità principali

• Scaffolding del progetto: Impostare progetti di agenti completi (modelli di infrastruttura come codice, definizioni di agente, configurazione) e iniziare subito a iterare.
• Configurazione dichiarativa: definire servizi, risorse e distribuzioni di modelli in un azure.yaml file per ambienti coerenti.
• Provisioning e distribuzione unificati: eseguire azd up per compilare contenitori, eseguire il push di immagini, creare risorse, distribuire modelli e pubblicare l'agente in un unico passaggio.
• Gestione delle definizioniAgent: Importare definizioni degli agenti da cataloghi, GitHub o percorsi locali. L'interfaccia della riga di comando esegue il mapping dei parametri necessari alle variabili di ambiente.
• Protezione per impostazione predefinita: configurare automaticamente le identità gestite e la sicurezza di base senza gestire manualmente le credenziali.
• Provisioning di modelli scalabili: specificare nomi, versioni e capacità dei modelli; azd li distribuisce in modo coerente tra gli ambienti.

Prerequisiti

• Interfaccia della riga di comando Azure Developer (azd) installata (versione 1.21.3 o successiva) e autenticata azd auth login.
  • L'estensione azd ai agent installata (azd extension install azure.ai.agents). Se l'estensione non è installata, quando si inizializza il modello di avvio o si esegue azd ai agent l'estensione viene installata automaticamente.
• Una sottoscrizione Azure con l'autorizzazione per creare gruppi di risorse e risorse di Microsoft Foundry.
• È necessario avere il Azure CLI installato per le operazioni necessarie.

Configurare e distribuire un agente

Completare le sezioni seguenti per effettuare il provisioning e distribuire un agente in Microsoft Foundry usando l'estensione dell'agente azd di intelligenza artificiale.

Inizializzare il modello Foundry

1. Inizializzare un nuovo progetto con il azd-ai-starter-basic modello. In una cartella vuota eseguire:

   azd init -t Azure-Samples/azd-ai-starter-basic --location northcentralus
   

   Annotazioni

   Gli agenti ospitati sono attualmente disponibili solo nell'area Azure degli Stati Uniti Centro-Settentrionali. Altre informazioni sulla disponibilità a livello di area degli agenti ospitati sono disponibili nella documentazione di Microsoft Foundry.

2. Quando richiesto, immettere un nome di ambiente per il progetto agente, ad esempio "my-analytics-agent".

   Processo azd init :

   • Clona i file del modello iniziale nel progetto
   • Crea la struttura di directory con infra/ (infrastruttura come file di codice) e src/ cartelle
   • Genera un azure.yaml file di configurazione
   • .azure/<env>/.env Configurazione per variabili specifiche dell'ambiente

Inizializzare la definizione dell'agente

Il modello iniziale fornisce la struttura del progetto, ma è necessario aggiungere una definizione di agente specifica. Le definizioni degli agenti descrivono il comportamento, gli strumenti e le funzionalità dell'agente. Trovare definizioni di esempio nel repository di Agent Framework.

Usare la propria definizione dell'agente o una dal catalogo. Esegui il comando azd ai agent init con il valore <agent-definition-url> proprio:

azd ai agent init -m <agent-definition-url>

Ad esempio, usare l'URL seguente per un semplice agente calcolatrice:

azd ai agent init -m https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/langgraph/calculator-agent/agent.yaml

Il comando azd ai agent init:

• Scarica il file YAML di definizione dell'agente nella directory del src/ progetto
• Analizza la definizione dell'agente per comprendere i requisiti
• Aggiornamenti azure.yaml con i servizi e le configurazioni corrispondenti
• Esegue il mapping dei parametri dell'agente alle variabili di ambiente

Esaminare la struttura del progetto

Il modello inizializzato include questi file chiave:

├── .azure/                 # Environment-specific settings (.env)
├── infra/                  # Bicep files for Azure infrastructure
├── src/                    # Agent definition and code
└── azure.yaml              # Project configuration

Aprire azure.yaml per vedere come viene configurato il progetto dell'agente:

requiredVersions:
    extensions:
        azure.ai.agents: latest
services:
    CalculatorAgent:
        project: src/CalculatorAgent
        host: azure.ai.agent
        language: docker
        docker:
            remoteBuild: true
        config:
            container:
                resources:
                    cpu: "1"
                    memory: 2Gi
                scale:
                    maxReplicas: 3
                    minReplicas: 1
            deployments:
                - model:
                    format: OpenAI
                    name: gpt-4o-mini
                    version: "2024-07-18"
                  name: gpt-4o-mini
                  sku:
                    capacity: 10
                    name: GlobalStandard
infra:
    provider: bicep
    path: ./infra
    module: main

Questa configurazione dichiarativa definisce il servizio agente e le risorse di intelligenza artificiale Azure necessarie, incluse le distribuzioni di modelli.

Configurare e distribuire l'agente

Eseguire azd up per distribuire le risorse e l'agente:

azd up

Il azd up comando orchestra il flusso di lavoro di distribuzione, dall'infrastruttura a un endpoint agente attivo:

• infrastruttura Provision: creare l'account, il progetto e Azure le risorse di Microsoft Foundry definiti nei file Bicep. - Gli hook di pre-provisioning controllano gli agenti, le loro dipendenze, modelli e altre risorse, quindi popolano le variabili di ambiente in modo che Bicep sappia cosa deve effettuare il provisioning, tra cui: - AI_PROJECT_DEPLOYMENTS (JSON): la specifica dei modelli da distribuire. - AI_PROJECT_CONNECTIONS (JSON): specifica delle connessioni da creare. - AI_PROJECT_DEPENDENT_RESOURCES (JSON): specifica delle risorse dipendenti. - ENABLE_HOSTED_AGENTS (booleano): indica se è necessario il provisioning degli agenti ospitati (con un registro di controllo degli accessi e CapHost).
• Distribuisce i modelli: effettua il provisioning delle distribuzioni del modello specificate in azure.yaml ,ad esempio GPT-4o-mini con la capacità configurata.
• Crea ed esegue il push del contenitore: se l'agente dispone di codice personalizzato, azd lo inserisce in un'immagine del container e lo registra nell'Azure Container Registry.
• Pubblicare l'agente: creare un'applicazione agente in Microsoft Foundry e distribuire l'agente come servizio attivo e chiamabile.

Una volta completato azd up, l'output mostra l'endpoint del progetto Microsoft Foundry, il gruppo di risorse, i nomi dei progetti e i dettagli dell'applicazione agente. L'output fornisce anche un collegamento diretto al playground dell'agente nel portale di Microsoft Foundry.

Identità e sicurezza

azd configura automaticamente i modelli di accesso sicuro in modo da non dover gestire manualmente le credenziali:

• Identità gestita: L'agente usa l'identità gestita assegnata dal sistema del progetto Foundry per autenticarsi con altre risorse Azure.
• Assegnazioni di ruolo: azd concede automaticamente le autorizzazioni necessarie (per esempio, garantendo all'agente l'accesso a Strumenti Foundry, memorizzazione o database).
• Endpoint security: gli endpoint dell'agente usano l'autenticazione Microsoft Entra ID (Azure AD) per impostazione predefinita, in modo che solo gli utenti o le applicazioni autorizzati possano chiamare l'agente.

Queste configurazioni di sicurezza seguono le procedure consigliate di Azure e funzionano immediatamente, così si inizia con una base sicura.

Testare l'agente in Microsoft Foundry

1. Aprire il portale di Microsoft Foundry.
2. Passare al progetto configurato da azd (il nome del progetto viene visualizzato nell'output azd up ).
3. Aprire la sezione Agenti per visualizzare l'agente distribuito.
4. Avvia l'agente sul playground e invia una query di test, ad esempio "Riepiloga le tue capacità".

Viene visualizzata la risposta dell'agente nella finestra di chat.

Gestire e risolvere i problemi degli agenti con azd

Dopo aver distribuito l'agente, usare i comandi seguenti azd per richiamare, sviluppare, monitorare e gestirlo.

Richiamare l'agente

Usare azd ai agent invoke per chiamare l'agente distribuito in remoto o in locale. Questo comando invia un messaggio all'agente e ne restituisce la risposta.

azd ai agent invoke --message "What is 12 multiplied by 8?"

Eseguire l'agente in locale

Usare azd ai agent run per avviare un ciclo di sviluppo locale. Questo comando esegue l'agente nel computer locale, rileva immediatamente le modifiche e si connette alle risorse remote di Azure definite nel .azure/<environment-name>/.env file.

azd ai agent run

Trasmettere i log in tempo reale

Usare azd ai agent monitor con il flag --follow per seguire in tempo reale l'output del log dall'agente distribuito. Ciò è utile per osservare il comportamento dell'agente e diagnosticare i problemi in tempo reale.

azd ai agent monitor --follow

Controllare l'integrità e lo stato dell'agente

Usare azd ai agent show per visualizzare le informazioni correnti sull'integrità, sullo stato della distribuzione e sull'endpoint per l'agente.

azd ai agent show

Eliminare tutte le risorse

Usare azd down per eseguire il deprovisioning di tutte le risorse di Azure create da azd up. In questo modo viene rimosso l'account Microsoft Foundry, il progetto, le distribuzioni di modelli, il registro contenitori e qualsiasi altra infrastruttura definita nei file Bicep.

azd down

Configurazione avanzata

È possibile personalizzare i progetti in modo da soddisfare requisiti avanzati oltre il flusso di lavoro predefinito.

Personalizzare le implementazioni di modelli

Il azure.yaml file consente di controllare i modelli distribuiti. Per aggiungere o modificare un modello, modificare il file:

services:
    CalculatorAgent:
        project: src/CalculatorAgent
        host: azure.ai.agent
        language: docker
        docker:
            remoteBuild: true
        config:
            container:
                resources:
                    cpu: "1"
                    memory: 2Gi
                scale:
                    maxReplicas: 3
                    minReplicas: 1
            deployments:
                - model:
                    format: OpenAI
                    name: gpt-4o-mini
                    version: "2024-07-18"
                  name: gpt-4o-mini
                  sku:
                    capacity: 10
                    name: GlobalStandard

Eseguire azd up per distribuire il nuovo modello e aggiornare il progetto.

Questa configurazione di esempio distribuisce più modelli in modo che l'agente possa usare un modello più grande per motivi complessi e uno più piccolo per le query semplici.

Gestire le variabili di ambiente

Variabili di ambiente che azd impostano o usano:

Queste variabili vengono archiviate in .azure/<environment-name>/.env. Personalizzarli per ogni ambiente (sviluppo, test e produzione).

Usare più ambienti

azd supporta più ambienti denominati in modo da poter gestire configurazioni separate per lo sviluppo, i test e la produzione senza sovrascrivere le impostazioni dell'altra.

Creare un nuovo ambiente con azd env new:

azd env new my-agent-prod

Passare da un ambiente esistente all'altro con azd env select:

azd env select my-agent-dev

Ogni ambiente ha un proprio .azure/<environment-name>/.env file che archivia le variabili di ambiente elencate nella tabella precedente. Quando si esegue azd up o azd provision, azd è destinato all'ambiente attualmente selezionato. Usare questo modello per distribuire la stessa definizione dell'agente in diverse sottoscrizioni o aree di Azure.

Casi d'uso e scenari di esempio

Usare azd e l'estensione dell'agente di intelligenza artificiale per potenziare vari scenari degli agenti con Microsoft Foundry.

Creare assistenti di conversazione

Creare agenti che rispondono alle domande con il contesto e si connettono ai dati interni.

• Distribuire varianti per i test A/B
• Integrare Azure AI Search per risposte arricchite da funzionalità di recupero
• Integrare le API aziendali tramite strumenti personalizzati

Creare agenti di dati e informazioni dettagliate

Recapita riepiloghi, calcoli e visualizzazioni.

• Connettersi a Azure SQL Database o Cosmos DB.
• Usare gli strumenti dell'interprete di codice per il calcolo
• Combinare modelli di ragionamento più grandi con modelli più piccoli a basso costo

Orchestrare più agenti

Coordina gli specialisti per flussi di lavoro complessi.

• Aggiungere un agente coordinatore per instradare le richieste.
• Definire le relazioni in modo dichiarativo in azure.yaml.
• Ridimensionare gli agenti in modo indipendente in base al carico.

Standardizzare la distribuzione aziendale

Favorire la coerenza tra i team.

• Pubblicare progetti e modelli riutilizzabili
• Applicare la sicurezza, la conformità e il monitoraggio coerenti
• Automatizza il provisioning e la distribuzione in CI/CD con azd provision e azd deploy.

Esplorare l'ecosistema

• Esplora agenti di esempio: Sfoglia il repository Agent Framework per agenti .NET e agenti Python e distribuirli con azd ai agent init.
• Unisciti alla community: Condividi esperienze e poni domande nelle discussioni su GitHub di Azure Developer CLI.
• Segnala problemi e suggerisci funzionalità: Fornisci feedback, segnala problemi o proponi suggerimenti sulle funzionalità nel repository Azure/azure-dev e taggali con ai-agent.
• Consultare la documentazione: visitare la documentazione di Microsoft Foundry per guide complete sullo sviluppo di agenti.

Risorse aggiuntive

• Installare l'interfaccia della riga di comando per sviluppatori di Azure
• Documentazione CLI degli sviluppatori di Azure
• Documentazione di Microsoft Foundry
• Repository di Agent Framework (esempi e strumenti)
• Repository GitHub di Azure Developer CLI
• modello iniziale Foundry