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 agenti vocali, prompt e ospitati.

Tipo Descrizione Quando utilizzare
Agente virtuale Un'applicazione distribuita come codice sorgente o un'immagine container. È 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 Agente vocale di prompt dichiarativo o wrapper vocale che si connette a un agente ospitato. È necessaria un'esperienza vocale in tempo reale tramite un client Voice Live.

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 inline o tramite un elemento root $ref esplicito che punta a una definizione YAML o JSON diretta. Usare azd ai agent add <service> --file <path> per un servizio basato su file. I wrapper con AgentManifest parametri non sono supportati dall'inizializzazione corrente. L'elenco uses: del servizio fa riferimento alle dipendenze, ad esempio il progetto, le connessioni e le caselle degli strumenti.

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 endpoint non vuoto risolto dall'ambiente attivo ha la precedenza sul contesto globale. Per il fallback della shell e il comportamento specifico del comando, vedere Impostare il contesto del 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 Cronologia dei messaggi per il protocollo Responses. Le invocazioni non salvano automaticamente la cronologia delle conversazioni.

Le sessioni sono identificate da un oggetto session_id. L'interfaccia della riga di comando salva la selezione della sessione per agente e la riutilizza per impostazione predefinita. Usare --new-session per avviare una sessione aggiornata o --session-id <id> per specificare come destinazione una sessione specifica. La cache non è indicizzata in base all'utente delegato; mantenere una mappatura esplicita da utente a sessione quando si usa --user-identity.

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. I comandi variano: le connessioni e le routine hanno update, le skill pubblicano una nuova versione tramite update e i toolbox usano mutazioni di connessione e skill che producono versioni, seguite da publish.

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 rapida dell'agente usa azd ai agent eval e un eval.yaml locale, incluso il flusso di lavoro dell'ottimizzatore. La valutazione del progetto usa l'estensione installata separatamente azd ai eval e evals/azure.eval.yaml, con sorgenti trace o dataset e controlli di qualità CI espliciti. I due formati di configurazione non sono intercambiabili.
  • 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.

Gruppi di comandi per mansione dello sviluppatore

Scegliere un comando per il risultato necessario. Aggiungi --help per ispezionarne i flag e i formati di output supportati.

Job Commands Indicazioni
Configurazione di un progetto e dei modelli amministrati azd ai project add, azd ai project deployment add Configurazione del progetto e contesto
Selezionare o ispezionare il contesto dell'endpoint azd ai project set, azd ai project show, azd ai project unsetazd ai project context La selezione dell'endpoint globale è separata dalle dichiarazioni di infrastruttura. L'output del contesto può contenere segreti.
Esplorare gli esempi o inizializzare un agente azd ai agent sample list, azd ai agent init, azd ai agent add Inizializzare agenti ospitati, di prompt e vocali
Eseguire ed esaminare localmente azd ai agent run, azd ai inspector launch Sviluppo locale
Richiamare, delegare l'identità utente o inviare intestazioni personalizzate azd ai agent invoke Opzioni di invocazione
Esaminare, seguire o annullare il lavoro azd ai agent invocations show, azd ai agent invocations follow, azd ai agent invocations cancel Invocazione di lunga durata
Esaminare o aggiornare un endpoint azd ai agent endpoint show, azd ai agent endpoint update Aggiornamenti degli endpoint e delle schede
Esaminare lo stato, diagnosticare i problemi o leggere i log azd ai agent show, azd ai agent doctor, azd ai agent monitor Diagnostica e log
Creare, elencare, controllare, arrestare o eliminare una sandbox azd ai agent sessions create, azd ai agent sessions list, azd ai agent sessions show, azd ai agent sessions stop, azd ai agent sessions delete Gestione delle sessioni
Inizializzare, recuperare o gestire file sandbox azd ai agent files upload, azd ai agent files download, azd ai agent files list, azd ai agent files mkdir, azd ai agent files stat, azd ai agent files delete Operazioni sui file di sessione
Ripristinare la sorgente distribuita azd ai agent code download Scaricare il codice o un file ZIP
Esaminare gli store durevoli e mantenere gli elementi condivisi azd ai agent state-stores list, azd ai agent state-stores select, azd ai agent state-stores showazd ai agent state-stores items Operazioni e limiti dello state store
Aggiungere dipendenze dell'agente alla configurazione di deployment azd ai agent connection add, azd ai agent toolbox add Entrambi i servizi devono esistere già in azure.yaml. Questi comandi aggiungono uses voci, non risorse remote.
Gestire le credenziali di connessione e i metadati azd ai connection create, azd ai connection list, azd ai connection show, azd ai connection update, azd ai connection delete Autenticazione e manutenzione della connessione
Autore, versione o scaricare competenze riutilizzabili azd ai skill add, azd ai skill create, azd ai skill update, azd ai skill list, azd ai skill show, azd ai skill download, azd ai skill delete Flussi di lavoro competenze
Creare/modificare e gestire toolbox azd ai toolbox add, azd ai toolbox create, azd ai toolbox list, azd ai toolbox show, azd ai toolbox delete Configurazione Toolbox
Sviluppare e promuovere le raccolte di strumenti azd ai toolbox connection, azd ai toolbox skill, azd ai toolbox versions listazd ai toolbox publish Le mutazioni derivano dalla versione più recente; la promozione è esplicita.
Pianificare, assegnare o controllare routine azd ai routine add, azd ai routine create, azd ai routine list, azd ai routine show, azd ai routine update, azd ai routine enable, azd ai routine disable, azd ai routine dispatch, azd ai routine run list, azd ai routine delete Flussi di lavoro di routine
Genera ed esegui una valutazione rapida azd ai agent eval generate, azd ai agent eval update, azd ai agent eval run, azd ai agent eval list, azd ai agent eval show Risorse per la valutazione rapida e l'ottimizzazione
Migliorare e distribuire una variante di ottimizzazione azd ai agent optimize, azd ai agent optimize status, azd ai agent optimize list, azd ai agent optimize cancel, azd ai agent optimize apply, azd ai agent optimize deploy Flusso di lavoro di ottimizzazione
Creare un pacchetto o pubblicare un agente Activity per Teams azd ai agent pack, azd ai agent publish Distribuzione di Teams
Eliminare una versione ospitata o un agente azd ai agent delete Eliminazione dell'agente
Valutare un progetto e applicare quality gate azd ai eval init, azd ai eval generate, azd ai eval create, azd ai eval run, azd ai eval dataset, azd ai eval evaluator, azd ai eval job Valutazione del progetto; installare azure.ai.evaluations separatamente.
Registrare set di dati riutilizzabili e relative versioni azd ai dataset Ciclo di vita del set di dati; installare azure.ai.dataset separatamente.
Inviare, sospendere, riprendere, annullare o pubblicare processi di fine-tuning azd ai finetuning init, azd ai finetuning jobs Fine-tuning; installare azure.ai.finetune separatamente.
Carica e gestisci pesi personalizzati del modello azd ai models Importazione e manutenzione di modelli personalizzati; installare azure.ai.models separatamente.

Ogni estensione che aggiunge comandi espone version; esaminare invece il microsoft.foundry bundle con azd ext list . I gruppi di connessioni, routine e skill espongono context anche per il progetto locale e l'ispezione dell'ambiente. Considerare l'output come potenzialmente sensibile.

Distribuzione dell'agente di attività

Dopo aver distribuito un agente del protocollo Activity, azd ai agent pack crea appPackage.zip per il sideloading. Usare --output-dir, --display-namee --app-version per personalizzare il pacchetto. La pacchettizzazione non equivale alla pubblicazione.

azd ai agent publishpubblica tramite Microsoft 365. Per impostazione predefinita, gli agenti attività semplici sono distribuiti come shared, a meno che non siano configurati diversamente; --scope tenant richiede l'approvazione dell'amministratore. I Digital Workers richiedono l'ambito del tenant. Usare valori ripetibili --access-boundary, --clear-access-boundaries per rimuovere i limiti esistenti e valori ripetibili --optional-permission-scope <resource-app-id>=<scope> per le autorizzazioni facoltative. personal non è un publish scope; usare pack --scope personal e installare il pacchetto in sideload per i test per utente.

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: