Používejte azd ai s agenty pro psaní kódu a skripty

Important

Položky označené jako náhled v tomto článku jsou aktuálně ve verzi Preview. Tato verze Preview se poskytuje bez smlouvy o úrovni služeb a Microsoft ji nedoporučuje pro produkční úlohy. Některé funkce nemusí být podporované nebo můžou mít omezené možnosti. Další informace najdete v dodatečných podmínkách použití pro verze Preview v Microsoft Azure.

Používejte azd ai z programovacích agentů a skriptů se stejným chováním, jaké mají lidé v terminálu. Nastavíte samostatný kontext, zakážete výzvy, parsujete výstup JSON a vyvoláte koncové body přímého agenta pro spolehlivou automatizaci.

Předpoklady

Začínáme s dovedností Microsoft Foundry

Kódovací agenti fungují nejlépe, pokud už znají konvence azd ai. Microsoft Foundry Skill poskytuje programovacímu agentovi tyto znalosti: generuje správné příkazy azd ai a propojení ve Foundry a uplatňuje postupy popsané v tomto článku – nastavení kontextu projektu, předávání --no-prompt a vyžadování --output json pro strukturované výsledky. Nejprve nasměrujte svého agenta pro psaní kódu na danou dovednost a potom pomocí postupů ve zbytku tohoto článku zkontrolujte a zabezpečte to, co vytvoří.

Nastavení kontextu projektu jednou

Každý příkaz pro prostředek, například connection, toolbox, skill nebo routine, potřebuje koncový bod projektu ve Foundry, na který se má zaměřit. Při automatizaci nastavte tento endpoint jednou za relaci, úlohu CI nebo spuštění kódovacího agenta a pak ho používejte po zbytek běhu.

Existují dva vzory.

Připněte jedním kliknutím na azd ai project set

Pokud chcete, aby kontext trval napříč prostředími bez exportu proměnné prostředí, nastavte ho v globální konfiguraci:

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> je plně neinteraktivní, pokud už znáte adresu URL. azd ai project show potvrdí, který zdroj vyřešil aktivní koncový bod. Použijte ho na začátku relace, pokud si nejste jistí, v jakém stavu je hostitel.

Nastav proměnnou prostředí

Nastavte FOUNDRY_PROJECT_ENDPOINT v prostředí, ve kterém běží váš skript nebo agent kódování. Každý příkaz azd ai jej automaticky převezme po prostředí azd v projektu a globální konfiguraci.

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

Tento vzor se pro CI dobře hodí, protože tajné údaje a konfigurace obvykle už přicházejí jako proměnné prostředí a mezi jednotlivými úlohami není žádný globální stav, který by bylo potřeba vyčistit.

Úplné vysvětlení, jak rozhraní příkazového řádku řeší koncový bod, včetně pořadí priorit, najdete v tématu Nastavení kontextu projektu azd.

Zakázat výzvy

Každý azd ai příkaz přijímá --no-prompt. Když tuto možnost nastavíte, příkaz okamžitě selže, místo toho aby čekal na interaktivní vstup. Chybějící povinný argument nebo delete potvrzení, které by jinak čekalo na stisknutí klávesy, se stane okamžitou chybou se strukturovaným výstupem.

Vždy se nastavuje --no-prompt v CI a při volání agenta kódování.

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 také znamená "přeskočit výzvu k delete potvrzení", takže nemusíte --force jenom potlačit tuto jednu výzvu.

Získání výstupu JSON

Většina příkazů azd ai podporuje --output json, včetně příkazů connection, toolbox, skill a příkazů prostředku routine a azd ai agent show. Použijte ho ke spolehlivému zpracování výsledku pomocí jq, ConvertFrom-Json nebo parseru JSON vašeho jazyka namísto extrahování z textového výstupu čitelného pro člověka. Příkaz azd ai agent invoke používá --output raw pro nezměněnou odpověď serveru.

# 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

Textový výstup je pro lidi a může se měnit mezi verzemi. Tvar JSON je stabilní kontrakt.

Vytvářejte zdroje idempotentně.

create není upsert. Pokud pojmenovaný prostředek již existuje, opětovné spuštění selže. Toto výchozí nastavení funguje dobře pro sdílené prostředky v rozsahu projektu, protože brání tomu, aby jeden volající bezobslužně přepsal stav jiného volajícího.

Pro automatizaci, která musí uspět bez ohledu na předchozí stav, příkazy connection přijímají --force pro nahrazení existujícího prostředku.

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

Výstraha

--force NAHRADÍ připojení (ARM PUT), nesloučí se. Používejte jej opatrně při práci se sdílenými prostředky, protože úpravy provedené jiným volajícím stejného prostředku mohou být ztraceny.

Pokud potřebujete změnit jenom několik polí a chcete zachovat všechno ostatní, použijte update. Nebo použijte specializované podpříkazy kolekce, jako jsou tool, tag, metadata a key.

Vytvoření sady nástrojů ze souboru

Pro sadu nástrojů s více položkami, která obsahuje integrované nástroje, připojení a dovednosti, umístěte úplnou definici do souboru YAML a předejte --from-file do azd ai toolbox create. Soubor používá odpovídající obrazec AgentSchema .

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

--from-file je vstup načtený jednorázově v okamžiku vyvolání. Rozhraní příkazového řádku soubor nesleduje ani znovu nenačítá, takže pozdější úpravy souboru YAML se neprojeví, dokud příkaz nespustíte znovu. Vytvořte připojení s explicitními příznaky (--kind, --target, --auth-typea odpovídajícími příznaky přihlašovacích údajů) a pak na ně odkazujte podle názvu ze souboru panelu nástrojů.

Vyvolání nasazeného agenta bez projektu azd

Když agent pro psaní kódu nebo skript potřebuje volat nasazeného agenta, který se nachází mimo jeho pracovní adresář, použijte --agent-endpoint, abyste na něj cílili přímo. Tento přístup obchází jak azure.yaml, tak aktivní prostředí azd env. Samotná adresa URL stačí.

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

Tento obrazec použijte, když CI jednoho úložiště potřebuje volat agenta vlastněného jiným úložištěm nebo když server MCP frontsuje několik agentů a zná pouze jejich adresy URL koncových bodů. Úplnou sadu invoke možností najdete v tématu Vyvolání hostovaného agenta.

Předat tajné údaje do lokálního spuštění

Chcete-li agenta spustit lokálně s tajnými údaji, nastavte je jako proměnné prostředí azd a odkazujte na ně v mapě env pro službu azure.ai.agent v azure.yaml. Hodnoty jsou v .azure/<env>/.env, který je ve výchozím nastavení ignorován Gitem.

azd env set OPENAI_KEY "$AZURE_OPENAI_KEY"

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

U tajných kódů, které by neměly být v místním .env souboru, je uložte do připojení projektu Foundry a odkazujte na ně zástupným ${{connections.<name>.credentials.<field>}} symbolem. Podívejte se na Spuštění hostovaného agenta místně, kde najdete úplný přehled možností místního spuštění.

Skript s krátkým nastavením

Tento skript Bash kombinuje výše uvedené vzory. Ukotví kontext projektu, idempotentně vytvoří připojení i panel nástrojů, zapojí nástroj do panelu nástrojů a ověří výsledek parsováním formátu 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 zajišťuje, že skript selže hned, pokud některý krok skončí chybou. V kombinaci s --no-prompt vám to dává deterministický návratový kód vhodný pro CI kontroly.

Kontrola rozlišení koncového bodu

Agenti pro psaní kódu mohou předvídat, na který projekt ve Foundry bude příkaz cílit, podle tohoto pořadí priorit. První zdroj, který dává hodnotu vyhrává; pozdější zdroje se nekonzultují.

  1. --project-endpoint (nebo -p) příznak (vždy vyhrává).
  2. Uvnitř projektu azd: aktivní hodnota env azd.
  3. Globální konfigurace (nastavená uživatelem azd ai project set).
  4. FOUNDRY_PROJECT_ENDPOINT proměnná prostředí.
  5. Chyba se strukturovaným doporučením spustit azd ai project set nebo předat --project-endpoint.

Úplné vysvětlení, včetně toho, jak samostatný kontext komunikuje s prací v projektu, najdete v tématu Nastavení kontextu projektu azd.

Použijte tipy pro agenta pro kódování

  • Vždy předejte --no-prompt, a u příkazů, které ji podporují, přidejte také --output json. Společně vám poskytnou předvídatelný ukončovací kód a parsovatelný výsledek.
  • Pokud si nejste jistí, v jakém stavu je hostitel, ověřte vyřešený kontext azd ai project show na začátku relace. Je to nenáročné volání pouze pro čtení.
  • Při selhání upřednostněte parsování strukturovaného návrhu v chybovém výstupu před rozhodováním o dalších krocích. Například chyba „No Foundry project endpoint resolved“ znamená, že byste měli před dalším pokusem spustit azd ai project set nebo nastavit FOUNDRY_PROJECT_ENDPOINT.
  • Používejte --debug pouze při diagnostice problému. Vytváří podrobný víceřádkový výstup, který je obtížné analyzovat a nikdy neměl být programovým rozhraním.
  • Selhání create s hlášením „již existuje“ považujte za obnovitelná. Spusťte znovu s --force, pokud chcete prostředek nahradit, nebo přepněte na update a dílčí příkazy kolekce, pokud potřebujete změnit jen jeho část.

Související obsah

  • Poslední aktualizace v