Sviluppo di agenti con l'interfaccia della riga di comando per sviluppatori di Azure

Importante

Gli elementi contrassegnati come anteprima in questo articolo sono attualmente in anteprima. Questa anteprima viene fornita senza un contratto di servizio e Microsoft non lo consiglia per i carichi di lavoro di produzione. Alcune funzionalità potrebbero non essere supportate o potrebbero avere funzionalità limitate. Per ulteriori informazioni, vedere Condizioni supplementari per l'uso delle versioni di anteprima di Microsoft Azure.

L'interfaccia della riga di comando per sviluppatori Azure (azd) e la relativa azd ai agent estensione offrono un singolo flusso di lavoro da riga di comando per passare dall'idea a un agente pronto per la produzione in Microsoft Foundry. È possibile sviluppare agenti ospitati basati su codice e agenti vocali dichiarativi basati su prompt. Questo articolo illustra il percorso di sviluppo, i file che definiscono un agente e i concetti di base che si incontrano lungo il percorso.

Questo articolo è rivolto agli sviluppatori che preferiscono un flusso di lavoro incentrato sul terminale e automatizzabile tramite script rispetto al portale Foundry o agli SDK dei linguaggi.

Percorso dello sviluppatore

Il azd ai flusso di lavoro segue lo stesso ciclo di vita, indipendentemente dal fatto che si crei un piccolo prototipo o un agente di produzione. Si esegue lo scaffolding di un progetto una sola volta, quindi si combinano i comandi man mano che il progetto si evolve.

Stage Cosa fai Dove saperne di più
Install Installare azd e le estensioni Foundry. Configurare l'ambiente per sviluppatori
Eseguire lo scaffolding Inizializza un agente ospitato a partire da un modello o dal tuo codice esistente, oppure crea un agente vocale basato su prompt. Guida introduttiva: Distribuire un agente ospitato o Avvio rapido: Creare un agente vocale prompt
Definire Configurare l'agente, le dipendenze della distribuzione del modello, i protocolli, gli strumenti e l'ambiente in azure.yaml. Creare azure.yaml per gli agenti ospitati
Develop Scrivere la logica dell'agente, aggiungere strumenti usando una casella degli strumenti e testare localmente. Panoramica della casella degli strumenti
Deploy Effettuare il provisioning dell'infrastruttura e distribuirla in Foundry. Distribuire un agente ospitato
Operate Monitorare i log, gestire le versioni e automatizzare le esecuzioni. Gestire gli agenti ospitati
Evaluate Misurare la qualità dell'agente e migliorare il prompt. Esegui valutazioni degli agenti con l'interfaccia della riga di comando (CLI) di azd

Tipi di agente

L'estensione azd ai agent supporta tipi di agenti dichiarativi e basati sul codice.

Tipo Descrizione Quando utilizzare
Agente virtuale Un'applicazione containerizzata che sviluppi nel codice, impacchetti come immagine Docker e distribuisci su Foundry. È necessaria logica personalizzata, integrazione del framework o controllo completo sul comportamento.
Agente di prompt Un agente definito interamente tramite istruzioni e configurazioni degli strumenti, senza codice personalizzato. Si vuole un agente rapido basato su configurazione senza scrivere codice dell'applicazione.
Agente vocale basato su richiesta Un agente vocale dichiarativo che utilizza un modello gestito o distribuito autonomamente senza codice di runtime personalizzato. Si vuole un'esperienza vocale in tempo reale senza creare e ospitare una pipeline audio.
Agente vocale ospitato con un wrapper gestito Una destinazione ospitata gestisce la logica di conversazione, mentre un servizio voce separato la delega tramite conversationEngine. Voice Live gestisce l'esperienza audio. Hai bisogno di una logica personalizzata per l'agente senza implementare il riconoscimento vocale e la sintesi nell'ambiente di destinazione ospitato.

Gli agenti ospitati offrono il controllo completo sulle integrazioni di runtime, framework e strumenti, mentre Foundry gestisce l'infrastruttura, il ridimensionamento e la gestione delle sessioni.

Gli agenti vocali basati su prompt non richiedono un contenitore personalizzato. Se devi eseguire una pipeline audio personalizzata da voce a voce o in cascata in un tuo contenitore, crea un agente vocale con un agente ospitato e usa il protocollo invocations_ws.

Per mantenere la logica di conversazione in un agente di testo ospitato mentre Voice Live gestisce l'audio, usare il flusso di lavoro del wrapper vocale ospitato. Il wrapper e il target sono servizi separati nel medesimo progetto azure.yaml. Questo flusso non sostituisce il flusso personalizzato della pipeline audio invocations_ws esistente.

Prima di usare le opzioni dell'interfaccia della riga di comando vocale di anteprima pubblica, controllare l'estensione installata come descritto nei prerequisiti di avvio rapido dell'agente vocale.

File di configurazione

Un progetto agente ospitato usa un azure.yaml file nella radice del progetto per dichiarare sia l'agente che il relativo modello di provisioning e distribuzione. Il file usa un modello a servizi separati, in cui ogni servizio denominato ha un valore host, come azure.ai.project, azure.ai.agent, azure.ai.connection, azure.ai.toolbox, azure.ai.skill o azure.ai.routine.

File Purpose Chi la mantiene
azure.yaml Dichiara il progetto Foundry, le distribuzioni di modelli, il servizio agente ospitato, le dipendenze, i protocolli, gli strumenti, le variabili di ambiente, le risorse del contenitore e le impostazioni di distribuzione. L'identità dell'agente, il modello, i protocolli, gli strumenti e i valori dell'ambiente risiedono nel azure.ai.agent servizio. L'inizializzazione lo genera. È possibile personalizzarla in base alle esigenze.

Il servizio azure.ai.agent definisce l'agente ospitato in linea e usa uses: per fare riferimento ad altri servizi, ad esempio il progetto, le connessioni, le cassette degli strumenti, le competenze e le routine. Non esiste alcun file autonomo agent.yaml o agent.manifest.yaml nel modello di progetto dell'agente azd ospitato corrente.

Per un agente vocale basato su prompt, azure.yaml archivia la definizione dell'agente dichiarativo, tra cui kind: prompt-voice, il modello, il tipo di modello e il nome dell'agente. Non include un runtime del contenitore dell'agente ospitato. Per personalizzare istruzioni, audio, rilevamento dei turni, trascrizione, output vocale, strumenti e messaggi di saluto, vedere Configurare un agente vocale.

Per un wrapper vocale ospitato, conversationEngine.name fa riferimento al nome del servizio della destinazione ospitata. La dipendenza uses del wrapper determina l'ordine di distribuzione e conversationEngine.version usa per impostazione predefinita la versione distribuita dall'ambiente corrente. Vedere le informazioni di riferimento sul servizio vocale per i campi di configurazione.

Sostituzione di variabili

Utilizzare ${VAR_NAME} in azure.yaml per i valori che differiscono in base all'ambiente azd. Il segnaposto viene risolto da .azure/<env>/.env in fase di distribuzione o di esecuzione, quindi lo stesso azure.yaml funziona in ambienti diversi, ad esempio sviluppo, gestione temporanea e produzione.

Posizione in cui viene eseguita l'interfaccia della riga di comando

I azd ai comandi funzionano sia all'interno che all'esterno di una directory del azd progetto:

  • All'interno di un progetto azd, i comandi risolvono l'endpoint del progetto Foundry dall'ambiente azd attivo.
  • Al di fuori di un progetto azd, imposta il contesto attivo una volta sola con azd ai project set <endpoint>, oppure passa --project-endpoint a un singolo comando relativo alle risorse (connection, toolbox, skill o routine). Come soluzione di riserva, azd ai legge la variabile di ambiente FOUNDRY_PROJECT_ENDPOINT.
  • Un ambiente del progetto ha sempre la precedenza sul contesto globale, quindi passando alla directory di un progetto, l'interfaccia della riga di comando punterà all'endpoint di quel progetto.

Protocols

Un protocollo definisce il contratto HTTP tra Foundry e il contenitore dell'agente. L'agente è in ascolto sulla porta 8088 e fornisce un probe di integrità, indipendentemente dal protocollo.

Protocol Stile dell'API Quando utilizzare
responses API Risposte OpenAI (POST /responses) La scelta standard, compatibile con l'ecosistema di API OpenAI.
invocations Contratto JSON personalizzato (POST /invocations) Quando è necessario il controllo completo sui payload di richiesta e risposta.

Per la specifica completa, vedere Contratto di runtime dell'agente ospitato.

Queste impostazioni del protocollo si applicano ai contenitori dell'agente ospitato. Gli agenti vocali basati su prompt non configurano un protocollo per agenti ospitati.

azd ai agent invoke non supporta le conversazioni vocali per agenti vocali basati su prompt o wrapper vocali ospitati. Per informazioni sul comportamento dell'interfaccia della riga di comando e sul test, vedere Limitazioni dell'agente vocale.

Sessioni e conversazioni

Concetto Descrizione
Session Ambiente di esecuzione isolato per un'interazione con un singolo agente. Ogni sessione viene eseguita nella propria sandbox con risorse dedicate.
Conversazione Sequenza di messaggi all'interno di una sessione. Foundry gestisce la cronologia delle conversazioni e può idratarla tra le richieste.

Le sessioni sono identificate da un oggetto session_id. Quando si esegue azd ai agent invoke, per impostazione predefinita Foundry riutilizza la sessione dell'ultima esecuzione. Usare --new-session per avviare una sessione aggiornata o --session-id <id> per specificare come destinazione una sessione specifica.

Risorse in un progetto Foundry

Un progetto Foundry ospita più agenti. Contiene anche risorse condivise a cui fanno riferimento gli agenti in fase di esecuzione. L'interfaccia della riga di comando gestisce ognuno di essi tramite un gruppo di comandi dedicato.

Resource Che cos'è Gestito con
Connection Collega un progetto Foundry a una risorsa esterna, ad esempio un server MCP, un Azure AI Search o il grounding con Bing. Comandi di azd ai connection
Kit di strumenti Una raccolta con nome di strumenti utilizzati dagli agenti in fase di esecuzione. Comandi di azd ai toolbox
Skill Linee guida comportamentali riutilizzabili condivise tra gli agenti nel progetto. Comandi di azd ai skill
Routine Un attivatore e un'azione che invoca un agente. Comandi di azd ai routine

Queste risorse vengono condivise tra sviluppatori e agenti nello stesso progetto. Ogni gruppo di comandi espone i verbi standard create, updatedelete, show, e list .

Valutare e migliorare un agente

Dopo l'esecuzione di un agente, due flussi di lavoro correlati consentono di misurarne e migliorarne la qualità:

  • La valutazione esegue l'agente su un set di dati, assegna un punteggio alle risposte con uno o più valutatori e restituisce un segnale complessivo della qualità. È possibile gestirlo con azd ai agent eval.
  • L'ottimizzazione riscrive in modo iterativo il prompt dell'agente per sollevare un segnale di valutazione. Usa una valutazione come funzione obiettiva e genera un prompt candidato da rivedere e accettare. È possibile gestirlo con azd ai agent optimize.

Per i dettagli, vedere Eseguire valutazioni degli agenti con l'interfaccia della riga di comando azd e Ottimizzare i prompt degli agenti.

Ciclo di vita dell'implementazione

Il ciclo di sviluppo completo si condensa in una breve sequenza di comandi. Eseguire lo scaffolding una sola volta e usare i comandi diretti man mano che il progetto cresce.

Per il percorso dell'agente vocale gestito, vedere Avvio rapido: Creare un agente vocale del prompt.

# Scaffold a project from a template or your existing code
azd ai agent init

# Run locally and invoke
azd ai agent run
azd ai agent invoke --local "Hello, world!"

# Provision infrastructure and deploy the agent
azd up

# Extend the project with shared resources at any time
azd ai connection create my-search --kind cognitive-search --target https://... --auth-type api-key --key "..."
azd ai routine create daily-digest --trigger recurring --cron "0 7 * * *" --agent-name my-agent

# Evaluate quality
azd ai agent eval generate
azd ai agent eval run

# Tear down all Azure resources
azd down

Contenuti correlati

  • Ultimo aggiornamento: