azd ai gebruiken met coderingsagenten en scripts

Important

Items die in dit artikel zijn gemarkeerd (preview) zijn momenteel beschikbaar als openbare preview. Deze preview wordt aangeboden zonder een service level agreement en we raden deze niet aan voor productieworkloads. Bepaalde functies worden mogelijk niet ondersteund of hebben mogelijk beperkte mogelijkheden. Zie Aanvullende gebruiksvoorwaarden voor Microsoft Azure Previews voor meer informatie.

Gebruik azd ai vanuit codeeragents en scripts met hetzelfde gedrag als mensen in een terminal. U stelt zelfstandige context in, schakelt prompts uit, parseert JSON-uitvoer en roept direct agent-eindpunten aan voor betrouwbare automatisering.

Prerequisites

Begin met de Microsoft Foundry Skill

Coderingsagenten werken het beste wanneer ze de azd ai conventies al kennen. De Microsoft Foundry Skill geeft een coderingsagent die kennis biedt: het genereert juiste azd ai opdrachten en Foundry bedrading, en past de procedures in dit artikel toe: het instellen van de projectcontext, het doorgeven --no-prompten aanvragen van --output json gestructureerde resultaten. Richt uw code-agent eerst op de vaardigheid en gebruik vervolgens de patronen in de rest van dit artikel om te evalueren en robuuster te maken wat deze produceert.

De projectcontext eenmaal instellen

Elke resourceopdracht, zoals connection, toolbox, skillof routine, heeft een Foundry-projecteindpunt nodig om het doel te bereiken. Stel in automatisering dat eindpunt eenmaal per sessie, CI-taak of aanroep van coderingsagent in en gebruik het vervolgens voor de rest van de uitvoering.

Er zijn twee patronen.

Een keer vastzetten met azd ai project set

Als u wilt dat de context in shells blijft bestaan zonder een omgevingsvariabele te exporteren, stelt u deze in globale configuratie in:

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> is volledig niet-interactief wanneer u de URL al kent. azd ai project show bevestigt welke bron het actieve eindpunt heeft opgelost. Gebruik deze boven aan een sessie als u niet zeker weet in welke status de host zich bevindt.

Een omgevingsvariabele instellen

Stel FOUNDRY_PROJECT_ENDPOINT in in de omgeving waarin uw script of codeeragent wordt uitgevoerd. Elke azd ai opdracht haalt deze automatisch op na de in-project azd-omgeving en de algemene configuratie.

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

Dit patroon past goed bij CI omdat geheimen en configuratie meestal al als omgevingsvariabelen binnenkomen en er geen globale status is om tussen taken op te schonen.

Zie De context van het azd-project instellen voor een volledige uitleg over hoe de CLI het eindpunt bepaalt, inclusief de precedentievolgorde.

Prompts uitschakelen

Elke azd ai opdracht accepteert --no-prompt. Wanneer u dit instelt, mislukt de opdracht onmiddellijk in plaats van te wachten op interactieve invoer. Een ontbrekend verplicht argument of een bevestiging via delete, die anders op een toetsaanslag zou wachten, resulteert direct in een fout bij gestructureerde uitvoer.

Stel --no-prompt altijd in, in CI en in aanroepen van de 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 impliceert ook 'sla de delete bevestigingsprompt over', dus u hoeft --force niet alleen die ene prompt te onderdrukken.

JSON-uitvoer ophalen

De meeste azd ai opdrachten ondersteunen --output json, waaronder de resourceopdrachten connection, toolbox, skill en routine en azd ai agent show. Gebruik het om het resultaat betrouwbaar te parseren met jq, ConvertFrom-Json of de JSON-parser van je programmeertaal, in plaats van de voor mensen leesbare tekstuitvoer te scrapen. De azd ai agent invoke opdracht gebruikt --output raw voor het ongewijzigde serverantwoord.

# 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

De tekstuitvoer is bedoeld voor mensen en kan veranderen tussen releases. De JSON-structuur vormt het stabiele contract.

Resources idempotent aanmaken

create is geen upsert. Als de benoemde resource al bestaat, mislukt het opnieuw uitvoeren. Deze standaardinstelling werkt goed voor gedeelde resources op projectniveau, omdat hiermee wordt voorkomen dat de ene aanroeper onopgemerkt de status van een andere aanroeper overschrijft.

Voor automatisering die moet slagen ongeacht de eerdere status, accepteren connection de --force opdrachten om de bestaande resource te vervangen.

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

Warning

--force VERVANGT de connectie (een ARM PUT), het wordt niet samengevoegd. Gebruik het voorzichtig bij gedeelde resources, omdat bewerkingen van een andere aanroeper in dezelfde resource mogelijk verloren kunnen gaan.

Als u slechts enkele velden hoeft te wijzigen en alles wilt behouden, gebruikt updateu . Of gebruik de speciale verzamelingssubopdrachten zoals tool, tag, metadataen key.

Een werkset maken op basis van een bestand

Voor een toolbox met meerdere items die ingebouwde hulpprogramma's, verbindingen en vaardigheden bundelt, neemt u de volledige definitie op in een YAML-bestand en geeft u --from-file door aan azd ai toolbox create. Het bestand maakt gebruik van de bijbehorende AgentSchema-shape .

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

--from-file is invoer die eenmalig wordt gelezen op het moment van aanroepen. De CLI houdt het bestand niet bij of leest het opnieuw, dus toekomstige bewerkingen in de YAML hebben geen effect totdat u de opdracht opnieuw uitvoert. Maak verbindingen met expliciete vlaggen (--kind, --target, --auth-typeen de overeenkomende referentievlagmen) en verwijs deze vervolgens op naam uit het werksetbestand.

Een geïmplementeerde agent aanroepen zonder een azd-project

Wanneer een codeeragent of script een geïmplementeerde agent moet aanroepen die zich buiten de werkmap bevindt, gebruikt u --agent-endpoint om die rechtstreeks aan te spreken. Deze aanpak omzeilt zowel azure.yaml als de actieve azd env. Alleen de URL is voldoende.

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

Gebruik deze shape wanneer de CI van de ene opslagplaats een agent moet aanroepen die eigendom is van een andere opslagplaats, of wanneer een MCP-server meerdere agents fronteert en alleen de eindpunt-URL's kent. Zie invoke voor de volledige set opties.

Geheimen doorgeven aan een lokale uitvoering

Als u de agent lokaal wilt starten met geheimen, stelt u deze in als azd omgevingsvariabelen en verwijst u ernaar vanuit de env kaart voor uw azure.ai.agent service in azure.yaml. De waarden staan in .azure/<env>/.env, dat standaard door Git wordt genegeerd.

azd env set OPENAI_KEY "$AZURE_OPENAI_KEY"

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

Voor geheimen die niet in een lokaal .env bestand mogen wonen, slaat u deze op in een Foundry-projectverbinding en verwijst u ernaar met een ${{connections.<name>.credentials.<field>}} tijdelijke aanduiding. Zie Een gehoste agent lokaal uitvoeren voor alle mogelijkheden van lokaal uitvoeren.

Een korte installatie uitvoeren

Dit bash-script combineert de bovenstaande patronen. Het legt de projectcontext vast, maakt idempotent een verbinding en een toolbox, voegt een hulpprogramma toe aan de toolbox en controleert het resultaat door JSON te parseren.

#!/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 zorgt ervoor dat het script snel mislukt als er stapfouten optreden. In combinatie met --no-prompt, dat geeft u een deterministische afsluitcode die geschikt is voor CI-poorten.

Oplossing van eindpunt controleren

Codeeragenten kunnen voorspellen op welk Foundry-project een opdracht gericht is door deze prioriteitsvolgorde te volgen. De eerste bron die resulteert in een waarde wint; latere bronnen worden niet geraadpleegd.

  1. --project-endpoint (of -p) vlag (wint altijd).
  2. Binnen een azd-project: de actieve azd env-waarde.
  3. Globale configuratie (ingesteld door azd ai project set).
  4. FOUNDRY_PROJECT_ENDPOINT omgevingsvariabele.
  5. Fout met een gestructureerde suggestie om uit te voeren azd ai project set of door te geven --project-endpoint.

Zie De azd-projectcontext instellen voor de volledige uitleg, inclusief hoe de zelfstandige context communiceert met in-projectwerk.

Tips voor de codeeragent toepassen

  • Geef altijd --no-prompt mee en voeg --output json toe aan opdrachten die dit ondersteunen. Samen geven ze u een voorspelbare afsluitcode plus een parseerbaar resultaat.
  • Controleer aan het begin van een sessie met azd ai project show de vastgestelde context als u niet zeker weet wat de status van de host is. Het is een goedkope, alleen-lees aanroep.
  • Bij een fout geeft u de voorkeur aan het parseren van de gestructureerde suggestie in de foutuitvoer om de volgende stappen te bepalen. Een fout als "No Foundry project endpoint resolved" betekent bijvoorbeeld dat u azd ai project set moet uitvoeren of FOUNDRY_PROJECT_ENDPOINT moet instellen voordat u het opnieuw probeert.
  • Alleen gebruiken --debug bij het diagnosticeren van een probleem. Het produceert uitgebreide, multi-line uitvoer die moeilijk te parseren is en is nooit bedoeld om een programmatische interface te zijn.
  • Behandel create-mislukkingen met "bestaat al" als herstelbaar. Voer opnieuw uit met --force als u de resource zelf mag vervangen, of schakel over naar update en de subopdrachten voor de verzameling als u alleen een deel ervan hoeft te wijzigen.

Verwante inhoud

  • Last updated on