Usare azd ai con agenti e script di codifica

Importante

Gli elementi contrassegnati (anteprima) in questo articolo sono attualmente in anteprima pubblica. Questa anteprima viene fornita senza un contratto di servizio e non è consigliabile 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.

Utilizza azd ai con agenti di codifica e script, con lo stesso comportamento che gli utenti ottengono nel terminale. È possibile impostare il contesto autonomo, disabilitare le richieste, analizzare l'output JSON e richiamare gli endpoint dell'agente diretto per un'automazione affidabile.

Prerequisiti

Introduzione a Microsoft Foundry Skill

Gli agenti di codifica funzionano meglio quando conoscono già le azd ai convenzioni. La Microsoft Foundry Skill fornisce a un agente di codifica tale conoscenza: genera comandi corretti azd ai e collegamenti di Foundry, e applica le procedure descritte in questo articolo, impostando il contesto del progetto, passando --no-prompt e richiedendo --output json per ottenere risultati strutturati. Per prima cosa, indirizzare l'agente di codifica alla competenza, quindi utilizzare i criteri descritti nel resto di questo articolo per rivedere e perfezionare il risultato.

Impostare il contesto del progetto una sola volta

Per ogni comando di risorsa, ad esempio connection, toolbox, skillo routine, è necessario un endpoint di progetto Foundry come destinazione. In automazione impostare l'endpoint una volta per sessione, processo CI o chiamata dell'agente di codifica e quindi usarlo per il resto dell'esecuzione.

Esistono due modelli.

Aggiungi una sola volta con azd ai project set

Quando si vuole che il contesto venga salvato in modo permanente tra shell senza esportare una variabile di ambiente, impostarlo nella configurazione globale:

azd ai project set https://my-project.services.ai.azure.com/api/projects/my-project --no-prompt
azd ai project show

azd ai project set <endpoint> è completamente non interattivo quando si conosce già l'URL. azd ai project show conferma quale origine si è risolta nell'endpoint attivo. Usarlo nella parte superiore di una sessione se non si è certi dello stato in cui si trova l'host.

Impostare una variabile di ambiente

Impostare FOUNDRY_PROJECT_ENDPOINT nell'ambiente in cui viene eseguito lo script o l'agente di codifica. Ogni comando azd ai lo seleziona automaticamente dopo l'ambiente azd nel progetto e la configurazione globale.

export FOUNDRY_PROJECT_ENDPOINT="https://my-project.services.ai.azure.com/api/projects/my-project"
azd ai connection list --output json

Questo modello si adatta bene alla CI perché i segreti e la configurazione arrivano già, in genere, come variabili di ambiente e non esiste uno stato globale da ripulire tra i job.

Per una spiegazione completa del modo in cui l'interfaccia della riga di comando risolve l'endpoint, incluso l'ordine di precedenza, vedere Impostare il contesto del progetto azd.

Disattiva i messaggi

Ogni azd ai comando accetta --no-prompt. Quando è impostata, il comando fallisce immediatamente invece di bloccarsi in attesa di input interattivo. La mancanza di un argomento obbligatorio o di una conferma di delete che altrimenti attenderebbe la pressione di un tasto, genera immediatamente un errore con un output strutturato.

Imposta sempre --no-prompt in CI e nelle invocazioni del coding-agent.

azd ai connection create my-search \
  --kind cognitive-search \
  --target https://my-search.search.windows.net \
  --auth-type api-key \
  --key "$KEY" \
  --no-prompt

Tip

--no-prompt implica anche "ignorare la delete richiesta di conferma", quindi non è sufficiente --force eliminare tale richiesta.

Recuperare l'output di un JSON

La maggior parte dei comandi azd ai supporta --output json, inclusi i comandi delle risorse connection, toolbox, skill e routine e azd ai agent show. Usalo per analizzare il risultato in modo affidabile con jq, ConvertFrom-Json o il parser JSON del tuo linguaggio, invece di analizzare l'output testuale leggibile dall'uomo. Il azd ai agent invoke comando usa --output raw per la risposta del server non modificata.

# List connections, extract names with jq
azd ai connection list --output json | jq -r '.[].name'

# Show a single resource as JSON
azd ai routine show daily-digest --output json | jq '.trigger'

# PowerShell example
$conn = azd ai connection show my-search --output json | ConvertFrom-Json
Write-Host $conn.target

L'output di testo è destinato agli esseri umani e può cambiare tra le versioni. La forma JSON è il contratto stabile.

Creare risorse in modo idempotente

create non è un upsert. Se la risorsa denominata esiste già, una nuova esecuzione non riesce. Questa impostazione predefinita funziona bene per le risorse condivise con ambito progetto perché impedisce a un chiamante di sovrascrivere automaticamente lo stato di un altro chiamante.

Per l'automazione che deve avere esito positivo indipendentemente dallo stato precedente, i connection comandi accettano --force di sostituire la risorsa esistente.

azd ai connection create my-search \
  --kind cognitive-search \
  --target https://my-search.search.windows.net \
  --auth-type api-key \
  --key "$KEY" \
  --force --no-prompt

Avvertimento

--force SOSTITUISCE la connessione (un ARM PUT), non la unisce. Usarlo con attenzione sulle risorse condivise perché le modifiche apportate da un altro chiamante alla stessa risorsa potrebbero andare perse.

Se è sufficiente modificare alcuni campi e conservare tutto il resto, usare update. In alternativa, usa i sottocomandi dedicati per la raccolta come tool, tag, metadata e key.

Creare una casella degli strumenti da un file

Per un toolbox con più voci che raggruppa strumenti, connessioni e abilità predefiniti, inserire la definizione completa in un file YAML e passare --from-file in azd ai toolbox create. Il file usa la forma AgentSchema corrispondente.

azd ai toolbox create research --from-file ./resources/research-toolbox.yaml --no-prompt

--from-file è un input one-shot letto in fase di chiamata. L'interfaccia della riga di comando non tiene traccia o rilegge il file, quindi le modifiche future apportate a YAML non hanno alcun effetto fino a quando non si esegue nuovamente il comando. Creare connessioni con flag espliciti (--kind, --target, --auth-type e i flag delle credenziali corrispondenti), quindi fare riferimento a esse per nome dal file della casella degli strumenti.

Richiamare un agente distribuito senza un progetto azd

Quando un agente di codifica o uno script deve chiamare un agente distribuito che si trova al di fuori della propria directory di lavoro, usa --agent-endpoint per fare riferimento direttamente a tale agente. Questo approccio ignora sia azure.yaml che il azd env attivo. L'URL da solo è sufficiente.

azd ai agent invoke \
  --agent-endpoint https://my-project.services.ai.azure.com/api/projects/my-project/agents/release-summarizer/versions/3 \
  "Summarize today's release notes." \
  --no-prompt

Usa questa struttura quando la pipeline CI di un repository deve chiamare un agente gestito da un repository diverso, oppure quando un server MCP fa da interfaccia a più agenti e conosce solo gli URL dei rispettivi endpoint. Per il set completo di invoke opzioni, vedere Richiamare un agente ospitato.

Passare i segreti a un'esecuzione locale

Per avviare l'agente in locale con i segreti, impostali come variabili d'ambiente azd e fai riferimento a essi nella mappa env per il servizio azure.ai.agent in azure.yaml. I valori si trovano in .azure/<env>/.env, che è gitignored per impostazione predefinita.

azd env set OPENAI_KEY "$AZURE_OPENAI_KEY"

# azure.yaml
services:
  my-agent:
    host: azure.ai.agent
    env:
      OPENAI_KEY: ${OPENAI_KEY}

Per i segreti che non dovrebbero essere memorizzati in un file locale .env, memorizzarli in una connessione del progetto Foundry e farvi riferimento con un segnaposto ${{connections.<name>.credentials.<field>}}. Vedere Eseguire un agente ospitato in locale per la superficie di esecuzione locale completa.

Creare uno script per una breve configurazione

Questo script bash combina i modelli precedenti. Aggiunge il contesto del progetto, crea una connessione e una casella degli strumenti in modo idempotente, associa uno strumento alla casella degli strumenti e verifica il risultato analizzando il JSON.

#!/usr/bin/env bash
set -euo pipefail

azd ai project set "$FOUNDRY_PROJECT_ENDPOINT" --no-prompt

# A 'remote-tool' connection holds the URL and credentials for the MCP server.
azd ai connection create tavily \
  --kind remote-tool \
  --target https://mcp.tavily.com/mcp \
  --auth-type custom-keys \
  --custom-key "x-api-key=$TAVILY_KEY" \
  --force --no-prompt

# Create the toolbox with the connection wired in, in a single shot
cat > research-toolbox.yaml <<'EOF'
description: Research tools
connections:
  - name: tavily
EOF

azd ai toolbox create research --from-file ./research-toolbox.yaml --no-prompt

echo "Toolbox state:"
azd ai toolbox connection list research --output json | jq .

set -euo pipefail garantisce che lo script si interrompa immediatamente se un passaggio genera un errore. In combinazione con --no-prompt, ciò fornisce un codice di uscita deterministico adatto ai controlli CI.

Verificare la risoluzione degli endpoint

Gli agenti di coding possono prevedere a quale progetto Foundry sarà destinato un comando seguendo questo ordine di priorità. La prima origine che restituisce un valore vince; le fonti successive non vengono consultate.

  1. Flag --project-endpoint (o -p) (prevale sempre).
  2. All'interno di un progetto azd: il valore dell'ambiente azd attivo.
  3. Configurazione globale (impostata da azd ai project set).
  4. Variabile di ambiente FOUNDRY_PROJECT_ENDPOINT.
  5. Errore con un suggerimento strutturato per eseguire azd ai project set o passare --project-endpoint.

Per la spiegazione completa, incluso il modo in cui il contesto autonomo interagisce con il lavoro in-project, vedere Impostare il contesto del progetto azd.

Applica i suggerimenti dell'agente di programmazione

  • Passare sempre --no-prompt e aggiungere --output json ai comandi che lo supportano. Insieme, forniscono un codice di uscita prevedibile più un risultato analizzabile.
  • Verificare il contesto risolto con azd ai project show all'inizio di una sessione se non si è certi dello stato in cui si trova l'host. È una chiamata economica, di sola lettura.
  • In caso di errore, dare priorità all'analisi del suggerimento strutturato nell'output dell'errore per decidere i passaggi successivi. Ad esempio, un errore "No Foundry project endpoint resolved" indica che è necessario eseguire azd ai project seto impostare FOUNDRY_PROJECT_ENDPOINT, prima di riprovare.
  • Usare --debug solo durante la diagnosi di un problema. Produce output dettagliato e su più righe difficile da analizzare e non è mai stato progettato per essere un'interfaccia programmatica.
  • Considera recuperabili gli errori create con "already exists". Esegui nuovamente con --force se devi sostituire l'intera risorsa, oppure passa a update e ai sottocomandi della raccolta se devi modificarne solo una parte.

Contenuti correlati

  • Last updated on