Używanie azd ai z agentami kodowania i skryptami

Ważna

Elementy oznaczone jako (wersja zapoznawcza) w tym artykule są aktualnie dostępne w publicznej wersji zapoznawczej. Ta wersja zapoznawcza jest udostępniana bez umowy dotyczącej poziomu usług i nie zalecamy korzystania z niej w przypadku obciążeń produkcyjnych. Niektóre funkcje mogą nie być obsługiwane lub mogą mieć ograniczone możliwości. Aby uzyskać więcej informacji, zobacz Warunki dodatkowe korzystania z testowych wersji Microsoft Azure.

Używaj azd ai z poziomu agentów kodujących i skryptów, z takim samym działaniem jak w terminalu używanym przez człowieka. Ustawiasz samodzielny kontekst, wyłączasz podpowiedzi, przetwarzasz dane wyjściowe w formacie JSON i wywołujesz bezpośrednie punkty końcowe agenta na potrzeby niezawodnej automatyzacji.

Wymagania wstępne

Zacznij od umiejętności Microsoft Foundry

Agenty kodujące działają najlepiej, gdy znają już konwencje azd ai. Umiejętność Microsoft Foundry zapewnia agentowi kodującemu tę wiedzę: generuje on poprawne polecenia azd ai i połączenia w usłudze Foundry oraz stosuje praktyki opisane w tym artykule — ustawia kontekst projektu, przekazuje --no-prompt i prosi o --output json, aby uzyskać wyniki strukturalne. Najpierw skieruj swojego agenta programistycznego do tego zestawu umiejętności, a następnie skorzystaj ze wzorców opisanych w dalszej części artykułu, aby sprawdzić, dopracować i zabezpieczyć to, co wygeneruje.

Ustaw kontekst projektu raz

Każde polecenie dotyczące zasobu, takie jak connection, toolbox, skill lub routine, wymaga wskazania punktu końcowego projektu Foundry jako celu. W automatyzacji ustaw ten punkt końcowy raz na sesję, zadanie ciągłej integracji lub wywołanie agenta kodowania, a następnie użyj go w pozostałej części przebiegu.

Istnieją dwa wzorce.

Przypnij raz za pomocą azd ai project set

Jeśli chcesz, aby kontekst był zachowywany między powłokami bez eksportowania zmiennej środowiskowej, ustaw go w globalnej konfiguracji:

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> jest w pełni nieinterakcyjny, gdy znasz już adres URL. azd ai project show potwierdza, które źródło rozpoznało aktywny punkt końcowy. Użyj go na początku sesji, jeśli nie masz pewności, w jakim stanie znajduje się host.

Ustawianie zmiennej środowiskowej

Ustaw FOUNDRY_PROJECT_ENDPOINT w środowisku, w którym jest uruchamiany skrypt lub agent kodowania. Każde azd ai polecenie automatycznie pobiera je po środowisku azd w projekcie i globalnej konfiguracji.

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

Ten wzorzec dobrze pasuje do CI, ponieważ sekrety i konfiguracja są zwykle już przekazywane jako zmienne środowiskowe i nie ma globalnego stanu, który trzeba czyścić między zadaniami.

Aby uzyskać pełne wyjaśnienie tego, jak CLI określa punkt końcowy, w tym kolejność priorytetów, zobacz Ustaw kontekst projektu azd.

Wyłącz monity

Każde azd ai polecenie przyjmuje --no-prompt. Po jej ustawieniu polecenie natychmiast kończy się błędem, zamiast czekać na interaktywne dane wejściowe. Brak wymaganego argumentu lub delete potwierdzenie, które w przeciwnym razie wymagałoby naciśnięcia klawisza, staje się natychmiastowym błędem przy danych wyjściowych o strukturze.

Zawsze ustawiaj --no-prompt w CI i w wywołaniach agenta kodującego.

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

Wskazówka

--no-prompt oznacza też „pomiń monit potwierdzenia delete”, więc nie potrzebujesz --force tylko po to, aby wyłączyć ten jeden monit.

Pobieranie danych wyjściowych JSON

Większość poleceń azd ai obsługuje --output json, w tym polecenia zasobów connection, toolbox, skill i routine oraz azd ai agent show. Użyj tego, aby niezawodnie przetworzyć wynik za pomocą jq, ConvertFrom-Json lub parsera JSON dostępnego w Twoim języku, zamiast parsować tekstowe dane wyjściowe przeznaczone do odczytu przez człowieka. To azd ai agent invoke polecenie używa --output raw dla niezmodyfikowanej odpowiedzi serwera.

# 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

Dane wyjściowe tekstu są przeznaczone dla ludzi i mogą ulec zmianie między wydaniami. Kształt JSON jest stabilnym kontraktem.

Twórz zasoby idempotentnie

create nie jest operacją wstawienia lub aktualizacji. Jeśli nazwany zasób już istnieje, ponowne uruchomienie zakończy się niepowodzeniem. To ustawienie domyślne dobrze sprawdza się w przypadku współdzielonych zasobów przypisanych do projektu, ponieważ uniemożliwia jednemu wywołującemu po cichu nadpisanie stanu innego wywołującego.

W przypadku automatyzacji, która musi zakończyć się powodzeniem niezależnie od stanu początkowego, polecenia connection obsługują opcję --force, aby zastąpić istniejący zasób.

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 Zastępuje połączenie (ARM PUT), nie scala. Należy używać go ostrożnie na zasobach współdzielonych, ponieważ zmiany innego wywołującego dotyczące tego samego zasobu mogą zostać utracone.

Jeśli musisz zmienić tylko kilka pól i chcesz zachować wszystko inne, użyj polecenia update. Możesz też użyć dedykowanych poleceń podrzędnych kolekcji, takich jak tool, tag, metadatai key.

Utwórz przybornik z pliku

W przypadku przybornika wielowejściowego, który grupuje wbudowane narzędzia, połączenia i umiejętności, umieść pełną definicję w pliku YAML i przekaż --from-file do azd ai toolbox create. Plik używa odpowiedniego kształtu AgentSchema .

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

--from-file jest wejściem odczytywanym jednorazowo w momencie wywołania. Interfejs wiersza polecenia nie śledzi ani nie odczytuje ponownie pliku, więc przyszłe edycje kodu YAML nie mają wpływu, dopóki nie uruchomisz ponownie polecenia. Utwórz połączenia z jawnie określonymi flagami (--kind, --target, --auth-type i odpowiadającymi im flagami poświadczeń), a następnie odwołuj się do nich według nazwy z pliku zestawu narzędzi.

Wywoływanie wdrożonego agenta bez projektu azd

Gdy agent programistyczny lub skrypt musi wywołać wdrożonego agenta znajdującego się poza swoim katalogiem roboczym, użyj --agent-endpoint, aby odwołać się do niego bezpośrednio. To podejście pomija zarówno azure.yaml, jak i aktywne środowisko azd. Sam adres URL jest wystarczający.

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

Użyj tego układu, gdy system CI jednego repozytorium musi wywołać agenta z innego repozytorium albo gdy serwer MCP obsługuje kilku agentów i zna tylko adresy URL ich punktów końcowych. Aby uzyskać pełny zestaw invoke opcji, zobacz Wywoływanie hostowanego agenta.

Przekaż sekrety do lokalnego uruchomienia

Aby uruchomić agenta lokalnie z sekretami, ustaw je jako zmienne środowiskowe azd i odwołuj się do nich w mapie env dla usługi azure.ai.agent w azure.yaml. Wartości znajdują się w .azure/<env>/.env, które jest domyślnie ignorowane przez Git.

azd env set OPENAI_KEY "$AZURE_OPENAI_KEY"

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

Sekrety, których nie należy przechowywać w lokalnym pliku .env, zapisuj w połączeniu projektu w Foundry i odwołuj się do nich przy użyciu symbolu zastępczego ${{connections.<name>.credentials.<field>}}. Zobacz Uruchamianie hostowanego agenta lokalnie, aby uzyskać pełny opis uruchamiania lokalnego.

Utwórz skrypt krótkiej konfiguracji

Ten skrypt bash łączy powyższe wzorce. Przypina kontekst projektu, tworzy połączenie i zestaw narzędzi w sposób idempotentny, podłącza narzędzie do zestawu narzędzi i weryfikuje wynik poprzez analizę składniową formatu 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 gwarantuje, że skrypt natychmiast zakończy działanie, jeśli którykolwiek krok zakończy się błędem. W połączeniu z --no-prompt zapewnia to deterministyczny kod zakończenia odpowiedni dla bramek CI.

Sprawdź rozpoznawanie punktów końcowych

Agenty kodujące mogą przewidzieć, do którego projektu Foundry będzie kierowane polecenie, kierując się następującą kolejnością priorytetów. Pierwsze źródło, które daje wartość wygrywa; późniejsze źródła nie są konsultowane.

  1. --project-endpoint (lub -p) flaga (ma zawsze pierwszeństwo).
  2. W projekcie azd: aktywna wartość azd env.
  3. Globalna konfiguracja (ustawiona przez azd ai project set).
  4. FOUNDRY_PROJECT_ENDPOINT zmienna środowiskowa.
  5. Błąd z sugestią ustrukturyzowaną uruchamiania azd ai project set lub przekazywania --project-endpoint.

Aby uzyskać pełne wyjaśnienie, w tym sposób interakcji autonomicznego kontekstu z pracą w projekcie, zobacz Ustawianie kontekstu projektu azd.

Zastosuj wskazówki dotyczące agenta programistycznego

  • Zawsze przekazuj --no-prompt, a w poleceniach, które to obsługują, dodaj --output json. Razem zapewniają przewidywalny kod zakończenia oraz wynik możliwy do sparsowania.
  • Zweryfikuj ustalony kontekst za pomocą azd ai project show na początku sesji, jeśli nie masz pewności, w jakim stanie znajduje się host. Jest to tanie, tylko do odczytu połączenie.
  • W przypadku niepowodzenia należy przy podejmowaniu decyzji o kolejnych krokach opierać się na analizie ustrukturyzowanej sugestii zawartej w komunikacie o błędzie. Na przykład błąd „No Foundry project endpoint resolved” oznacza, że przed ponowieniem próby należy uruchomić azd ai project set lub ustawić FOUNDRY_PROJECT_ENDPOINT.
  • Używaj --debug tylko podczas diagnozowania problemu. Generuje pełne, wielowierszowe dane wyjściowe, które trudno przeanalizować i nigdy nie miały być interfejsem programowym.
  • Uznawaj niepowodzenia create z komunikatem „already exists” za możliwe do odzyskania. Uruchom ponownie za pomocą --force, jeśli to Twój zasób i chcesz go zastąpić, lub przełącz się na update i podpolecenia dla kolekcji, jeśli musisz zmienić tylko jego część.

Treści powiązane

  • Last updated on