Använda azd ai med kodningsagenter och skript

Använd azd ai från kodningsagenter och skript med samma beteende som människor får i en terminal. Du ställer in fristående kontext, inaktiverar prompter, parsar JSON-utdata och anropar direct agent-slutpunkter för tillförlitlig automatisering.

Förutsättningar

• Azd Foundry-tilläggen installerade.
• En autentiserad azd-session.
• En Microsoft Foundry-projektslutpunkt för de kommandon som du vill köra. Mer information finns i Ange azd-projektkontexten.
• Valfritt: en distribuerad värdbaserad agent när du behöver anropa en agentslutpunkt. Konfiguration finns i Distribuera en värdbaserad agent.

Börja med Microsoft Foundry Skill

Kodningsagenter fungerar bäst när de redan känner till konventionerna azd ai . Microsoft Foundry Skill ger en kodningsagent den kunskapen: den genererar rätt azd ai kommandon och Foundry-ledningar och tillämpar metoderna i den här artikeln – anger projektkontexten, skickar --no-promptoch begär --output json strukturerade resultat. Rikta först din kodningsagent mot färdigheten och använd sedan mönstren i resten av den här artikeln för att granska och härda det den genererar.

Ange projektkontexten en gång

Varje resurskommando, till exempel connection, toolbox, skilleller routine, behöver en Slutpunkt för Foundry-projektet som mål. Vid automatisering anger du den ändpunkten en gång per session, CI-jobb eller anrop av kodningsagent och använder den sedan under resten av körningen.

Det finns två mönster.

Fäst en gång med azd ai project set

När du vill att kontexten ska bevaras mellan gränssnitt utan att exportera en miljövariabel anger du den i global konfiguration:

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> är helt icke-interaktiv när du redan känner till URL:en. azd ai project show bekräftar vilken källa som löste den aktiva slutpunkten. Använd den överst i en session om du inte är säker på vilket tillstånd värden befinner sig i.

Ange en miljövariabel

Ange FOUNDRY_PROJECT_ENDPOINT i den miljö där skriptet eller kodningsagenten körs. Varje azd ai-kommando använder den automatiskt efter den azd-miljö som finns i projektet och den globala konfigurationen.

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

Det här mönstret passar CI bra eftersom hemligheter och konfigurationer vanligtvis redan kommer som miljövariabler och det inte finns något globalt tillstånd att rensa mellan jobb.

Fullständig förklaring av hur CLI löser slutpunkten, inklusive prioritetsordningen, finns i Ange azd-projektkontexten.

Inaktivera uppmaningar

Varje azd ai kommando accepterar --no-prompt. När du ställer in det avbryts kommandot omedelbart i stället för att vänta på interaktiv inmatning. Ett obligatoriskt argument som saknas eller en begäran om delete-bekräftelse som annars skulle vänta på en tangenttryckning resulterar omedelbart i ett fel med strukturerade utdata.

--no-prompt Ange alltid i CI och i kodningsagentanrop.

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

Hämta JSON-utdata

De flesta azd ai kommandon stöder --output json, inklusive resurskommandona connection, toolbox, skill och routine samt azd ai agent show. Använd det för att parsa resultatet på ett tillförlitligt sätt med jq, ConvertFrom-Jsoneller språkets JSON-parser i stället för att skrapa utdata som kan läsas av människor. Kommandot azd ai agent invoke använder --output raw för det oförändrade serversvaret.

# 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

Textutdata är för människor och kan ändras mellan versioner. JSON-formen är det stabila kontraktet.

Skapa resurser på ett idempotent sätt

create är inte en upsert. Om den namngivna resursen redan finns misslyckas en omkörning. Det här standardvärdet fungerar bra för delade resurser med projektomfattning eftersom det förhindrar att en anropare tyst skriver över en annan anropares tillstånd.

För automatisering som måste lyckas oavsett tidigare tillstånd accepterar connection kommandona att ersätta den befintliga resursen--force.

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

Om du bara behöver ändra några få fält och vill bevara allt annat använder du update. Du kan också använda de dedikerade samlingsunderkommandona, till exempel tool, tag, metadataoch key.

Skapa en verktygslåda från en fil

För en verktygslåda med flera poster som innehåller inbyggda verktyg, anslutningar och funktioner, lägger du den fullständiga definitionen i en YAML-fil och skickar --from-file till azd ai toolbox create. Filen använder motsvarande AgentSchema-form .

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

--from-file är engångsindata som läses när det anropas. CLI spårar eller läser inte filen igen, så framtida ändringar i YAML har ingen effekt förrän du kör kommandot igen. Skapa anslutningar med explicita flaggor (--kind, --target, --auth-typeoch matchande flaggor för autentiseringsuppgifter) och referera sedan till dem med namn från verktygslådefilen.

Anropa en distribuerad agent utan ett azd-projekt

När en kodningsagent eller ett skript behöver anropa en distribuerad agent som finns utanför arbetskatalogen använder du --agent-endpoint för att rikta den direkt. Den här metoden kringgår både azure.yaml och den aktiva azd env. Enbart URL:en räcker.

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

Använd den här formen när en lagringsplatss CI behöver anropa en agent som ägs av en annan lagringsplats, eller när en MCP-server frontar flera agenter och bara känner till deras slutpunkts-URL:er. Fullständig uppsättning invoke alternativ finns i Anropa en värdbaserad agent.

Skicka hemliga uppgifter till en lokal körning

Om du vill starta agenten lokalt med hemligheter anger du dem som azd miljövariabler och refererar till dem från kartan env för din azure.ai.agent tjänst i azure.yaml. Värdena finns i .azure/<env>/.env, som är gitignored som standard.

azd env set OPENAI_KEY "$AZURE_OPENAI_KEY"

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

För hemligheter som inte ska finnas i en lokal .env fil lagrar du dem i en Foundry-projektanslutning och refererar till dem med en ${{connections.<name>.credentials.<field>}} platshållare. Se Kör en värdbaserad agent lokalt för den fullständiga lokala körningsytan.

Skapa ett kort skript för konfiguration

Det här bash-skriptet kombinerar mönstren ovan. Den fäster projektkontexten, skapar en anslutning och en verktygslåda idempotently, kopplar ett verktyg till verktygslådan och verifierar resultatet genom att parsa 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 ser till att skriptet misslyckas snabbt om något steg ger ett fel. Tillsammans med --no-prompt ger det dig en deterministisk avslutningskod som lämpar sig för CI-kontroller.

Granska slutpunktsupplösning

Kodningsagenter kan förutsäga vilket Foundry-projekt ett kommando ska rikta in sig på genom att gå i den här prioritetsordningen. Den första källan som ger ett värde vinner. senare källor konsulteras inte.

1. --project-endpoint (eller -p) flagga (vinner alltid).
2. I ett azd-projekt: värdet för den aktiva azd-miljön.
3. Global konfiguration (anges av azd ai project set).
4. FOUNDRY_PROJECT_ENDPOINT miljövariabel.
5. Fel med ett strukturerat förslag om att köra azd ai project set eller skicka --project-endpoint.

Fullständig förklaring, inklusive hur den fristående kontexten interagerar med projektarbete, finns i Ange azd-projektkontexten.

Använda kodningsagenttips

• Skicka alltid med --no-prompt och lägg till --output json på kommandon som stöder det. Tillsammans ger de dig en förutsägbar slutkod plus ett parsbart resultat.
• Kontrollera den lösta kontexten med azd ai project show i början av en session om du är osäker på vilket tillstånd värden befinner sig i. Det är ett billigt, skrivskyddat samtal.
• Vid fel bör du hellre tolka det strukturerade förslaget i felutmatningen i stället för att avgöra nästa steg. Till exempel innebär felet "No Foundry project endpoint resolved" att du ska köra azd ai project set, eller ange FOUNDRY_PROJECT_ENDPOINT, innan du försöker igen.
• Använd --debug endast när du diagnostiserar ett problem. Den producerar utförliga, flerradsutdata som är svåra att parsa och aldrig var avsedda att vara ett programmatiskt gränssnitt.
• Behandla create-fel av typen "finns redan" som återställbara. Kör igen med --force om resursen är din att ersätta, eller växla till update och samlingens underkommandon om du bara behöver ändra en del av den.

Relaterat innehåll

• Ange azd-projektkontexten för att förstå hur CLI löser slutpunkten för Foundry-projektet.
• Konfigurera CI/CD för värdbaserade agenter med Azure Developer CLI för mönster som körs azd ai i pipelines.
• Anropa en värdbaserad agent för fullständiga azd ai agent invoke alternativ, inklusive --agent-endpoint.