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

L'interfaccia della riga di comando per sviluppatori Azure (azd) e la relativa azd ai agent estensione offrono un singolo flusso di lavoro della riga di comando per passare dall'idea a un agente ospitato pronto per la produzione in Microsoft Foundry. 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.

Tipi di agente

L'estensione azd ai agent è incentrata sugli agenti ospitati.

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.

File di configurazione

Tre file definiscono la modalità di compilazione e distribuzione di un agente.

La distinzione principale è che agent.yaml descrive che cos'è il tuo agente, mentre azure.yaml descrive in che modo viene distribuito.

Le risorse attive nel progetto Foundry stesso, ad esempio connessioni, strumenti, competenze e routine, vengono gestite tramite comandi diretti azd ai anziché dichiarati in agent.yaml.

Sostituzione di variabili

Nei file di progetto dell'agente vengono visualizzate due sintassi variabili:

• ${VAR_NAME} è un azd segnaposto per variabile di ambiente. Viene risolto da .azure/<env>/.env al momento della distribuzione, quindi lo stesso agent.yaml funziona in ambienti come sviluppo, staging e produzione.
• {{ parameter }} è un parametro di modello manifesto. Si risolve durante azd ai agent init quando da un modello viene generato un progetto concreto.

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 determinano 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 la CLI 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 ed espone una sonda di integrità, indipendentemente dal protocollo.

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

Sessioni e conversazioni

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.

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 il tuo agente su un set di dati, assegna un punteggio alle risposte con uno o più valutatori e restituisce un indicatore complessivo della qualità. È possibile gestirlo con azd ai agent eval.
• L'ottimizzazione riscrive in modo iterativo la richiesta dell'agente di sollevare un segnale di valutazione. Usa una valutazione come funzione obiettivo e genera un prompt dei candidati 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. Genera lo scaffold una sola volta, poi usa i comandi diretti man mano che il progetto cresce.

# 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

• Guida introduttiva: Implementare il primo agente ospitato
• Che cosa sono gli agenti ospitati?
• Contratto di runtime dell'agente ospitato
• Ciclo di vita di sviluppo dell'agente