Używanie azd ai z agentami kodowania i skryptami

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

• Zainstalowane rozszerzenia azd Foundry.
• Uwierzytelniona sesja azd .
• Punkt końcowy projektu Microsoft Foundry dla poleceń, które chcesz uruchomić. Aby uzyskać więcej informacji, zobacz Ustawianie kontekstu projektu azd.
• Opcjonalnie: wdrożony hostowany agent, gdy trzeba wywołać punkt końcowy agenta. Aby uzyskać informacje na temat instalacji, zobacz Wdrażanie hostowanego agenta.

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. Podstawowe polecenia zasobów używają go jako rezerwowego; nie zastępuje lokalnej konfiguracji wymaganej przez polecenia, takie jak agent show.

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.

Obecnie azd automatycznie włącza tryb nieinteraktywny w środowisku CI lub gdy wykryje środowisko agenta AI bez podłączonego terminala. Ustaw wartość AZD_NON_INTERACTIVE=false, aby zrezygnować z tego automatycznego działania. To ustawienie nie zastępuje jawnego --no-promptelementu .

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

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

Aby zachować niepodane pola połączenia, użyj polecenia azd ai connection update, podając tylko flagi, które chcesz zmienić. Nie można zmienić typu uwierzytelniania za pomocą metody update; ponowne utworzenie połączenia jest jawnym zastąpieniem. Zestawy narzędzi nie mają ogólnego polecenia update: mutacje połączeń i umiejętności poznawczych tworzą niezmienne wersje, a publish promuje wersję.

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 definicji przybornika interfejsu wiersza polecenia opisanej w temacie Tworzenie i używanie przybornika Foundry.

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/endpoint/protocols/openai/responses?api-version=v1" \
  "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 przypisuje kontekst projektu, zastępuje połączenie, tworzy toolbox i weryfikuje wpisy połączeń. Uruchom go na potrzeby początkowej konfiguracji: tworzenie toolboxa kończy się niepowodzeniem, jeśli nazwa już istnieje. Nie usuwaj udostępnionego przybornika tylko po to, by ponownie uruchomić skrypt.

#!/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 tam, gdzie polecenie uwidacznia go (-p na podstawowych poleceniach zasobów).
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.

Ta kolejność dotyczy głównego resolvera zasobów. Aktywne środowisko może również dostarczyć mechanizm awaryjny powłoki, gdy nie ma utrwalonego klucza punktu końcowego. agent invoke --agent-endpoint omija to rozstrzygnięcie, a polecenia zależne od konfiguracji, takie jak agent show, nadal wymagają projektu na dysku. Aby uzyskać informacje o zachowaniu specyficznym dla polecenia, 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

• Ustaw kontekst projektu azd, aby zrozumieć, jak narzędzie CLI określa punkt końcowy projektu Foundry.
• Skonfiguruj CI/CD dla hostowanych agentów za pomocą Azure Developer CLI dla wzorców uruchamianych azd ai w potokach.
• Wywołaj hostowanego agenta, aby uzyskać pełne azd ai agent invoke opcje, w tym --agent-endpoint.