Inicjowanie projektu hostowanego agenta przy użyciu interfejsu wiersza polecenia dewelopera Azure

Ważna

Elementy oznaczone podglądem w tym artykule są obecnie w wersji zapoznawczej. Ta wersja zapoznawcza jest udostępniana bez umowy dotyczącej poziomu usług, a Microsoft nie zaleca 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żyj azd ai agent init, aby utworzyć szkielet projektu hostowanego agenta z plikami potrzebnymi do kompilowania, testowania i wdrażania agenta AI do Microsoft Foundry. W tym artykule wybierzesz punkt wyjścia i zainicjujesz projekt z szablonu, z własnego kodu lub na podstawie istniejącego projektu Foundry.

Jeśli używasz agenta kodowania, takiego jak GitHub Copilot, umiejętności Microsoft Foundry mogą pomóc w wybraniu szablonu początkowego, utworzenia szkieletu projektu i zinterpretowaniu wygenerowanej azd konfiguracji.

Wymagania wstępne

Wybieranie punktu początkowego

Istnieją trzy sposoby rozpoczęcia projektu. Wybierz ścieżkę zgodną z twoją sytuacją.

Rozważenie Rozpoczynanie od szablonu Przynieś swój własny kod Łączenie istniejącego projektu
Najlepsze dla Nowi agenci, uczenie narzędzi. Istniejący kod agenta, który chcesz hostować w usłudze Foundry. Agenci już działają w projekcie Foundry.
Polecenie azd ai agent init w pustym katalogu. azd ai agent init w katalogu z istniejącym kodem. azd ai agent init, a następnie wybierz istniejący projekt.
Co otrzymujesz Projekt z kompletnym szkieletem: pojedynczy element azure.yaml, kod źródłowy agenta w katalogu src/<agent-name>/ oraz plik Dockerfile do wdrażania kontenera. Infrastruktura domyślnie nie używa Bicep i można ją później wyodrębnić. Wygenerowany azure.yaml wpis usługi oraz, do wdrożenia kontenera, plik Dockerfile opakowujący kod. Infrastruktura domyślnie nie używa Bicep i można ją później wyodrębnić. azure.yaml podłączony przewodowo do istniejącego projektu Foundry. Infrastruktura domyślnie nie używa Bicep i można ją później wyodrębnić.
Zmiany kodu Żaden. Wszystko gotowe do uruchomienia. Może być potrzebny adapter protokołu. Żaden.

Zainicjuj na podstawie szablonu

Uruchom kreatora interaktywnego w pustym katalogu i wybierz pozycję Rozpocznij nowy z szablonu:

azd ai agent init

Kreator przeprowadzi Cię przez następujące opcje.

Podpowiedź Opis
Szablon agenta Wybierz spośród szablonów zorganizowanych według struktury i języka (Python lub .NET).
Subskrypcja platformy Azure Subskrypcja używana do znajdowania lub tworzenia projektu Foundry.
Projekt odlewni Wybierz istniejący projekt lub utwórz nowy. Jeśli go utworzysz, wybierz również region.
Wdrożenie modelu Sprawdź ustawienia modelu szablonu. Podczas dodawania szablonu do istniejącego projektu użyj polecenia --model-deployment <name>, aby jawnie ponownie użyć wdrożenia.

Nazwa agenta pochodzi z szablonu. CLI tworzy środowisko azd o nazwie <directory>-dev i konfiguruje je przy użyciu informacji z wybranego projektu Foundry. Szablony deklarują ustawienia źródła agenta i wdrożenia w programie azure.yaml; szablony kontenerów również zawierają element Dockerfile.

Inicjowanie z adresu URL azure.yaml

Jeśli masz konkretny przykład agenta, ustaw --template na azure.yaml tego przykładu. CLI wykorzystuje ten plik jako manifest projektu i pobiera wskazane źródło agenta.

azd ai agent init --template https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/agent-framework/responses/01-basic/azure.yaml --src .

W przypadku zastosowania szablonu element --src służy do wybierania miejsca docelowego całego projektu, a nie tylko źródła agenta. Poprzednie polecenie zapisuje azure.yaml w bieżącym katalogu i zachowuje względne ścieżki źródłowe szablonu. Bez metody --src inicjalizacja może utworzyć katalog o nazwie takiej jak szablon. Uruchom kolejne polecenia azd env, aprowizacji i wdrażania z katalogu zawierającego wygenerowany azure.yaml.

Szablony mogą odwoływać się do zewnętrznych danych wejściowych, takich jak token GitHub lub punkt końcowy usługi. Przygotuj te wartości przed zainicjowaniem; interfejs wiersza polecenia wyświetla monit o nierozwiązane zmienne środowiskowe i przechowuje je w wybranym azd środowisku. Nie commituj danych logowania ani katalogu .azure.

Uwaga / Notatka

Wdrożenie szablonu wymaga pełnego azure.yaml. Aby dołączyć bezpośrednią definicję agenta do istniejącego projektu, użyj polecenia agent add --file. Sparametryzowane AgentManifest otoki nie są obsługiwane przez żadną ze ścieżek.

Użyj --template (-t) w dokumencie projektu azure.yaml. --manifest (-m) jest przestarzałym aliasem, a nie wsparciem dla wcześniejszego formatu manifestu. Autonomiczne definicje agentów, AgentManifest otoki i azureml:// wskaźniki manifestu nie są akceptowane przez ten przepływ pracy.

Określanie modelu

Wybierz model w czasie inicjowania:

azd ai agent init --model gpt-4.1

Możesz też użyć istniejącego wdrożenia modelu w projekcie Foundry:

azd ai agent init --model-deployment my-deployment

Podczas korzystania z szablonu azure.yaml dodaj --model-deployment <name> do tego samego polecenia inicjowania i wybierz istniejący projekt. Ta opcja nie oferuje obecnie interaktywnego wybieraka istniejącego wdrożenia. Bez nadpisania przyjęta konfiguracja może zachować żądany model szablonu. Przed uruchomieniem azd provision przejrzyj zarówno deklarację wdrożenia projektu, jak i ustawienie modelu agenta.

Wybieranie trybu wdrażania

Domyślnie azd ai agent init stosuje wdrażanie kodu w projektach Python i .NET. Wdrożenie kodu przesyła Twój kod źródłowy w postaci pakietu ZIP. Aby zamiast tego utworzyć szkielet projektu opartego na kontenerze, przekaż polecenie --deploy-mode container:

azd ai agent init --deploy-mode container

Aby wdrożyć gotowy obraz kontenera, przekaż --image i --agent-name. Ta opcja pomija wybór szablonu i języka, tworzenie szkieletów kodu, generowanie plików Dockerfile i Azure Container Registry konfigurację.

azd ai agent init --agent-name my-agent --image myregistry.azurecr.io/my-agent:v1

W przypadku inicjowania nienadzorowanego kodu źródłowego podaj --runtime i --entry-point za pomocą --deploy-mode code. Wygenerowany .agentignore używa składni .gitignore do wykluczania plików z pliku ZIP wdrożenia; przejrzyj go przed przesłaniem źródła.

Przeglądanie szablonów nieinteraktywnie

Aby sprawdzić katalog przed wygenerowaniem szkieletu lub sterować azd ai agent init za pomocą skryptu, wyświetl katalog:

# Everything in the catalog
azd ai agent sample list

# Just the featured Python agent samples
azd ai agent sample list --featured-only --language python --type agent

# Full azd templates only, as JSON for scripting
azd ai agent sample list --type azd --output json

Każdy wpis zawiera gotowy do uruchomienia initCommand , który można skopiować i uruchomić w katalogu, do którego chcesz utworzyć szkielet.

Wskazówka

Gdy ponownie używasz przykładu przy użyciu innej tożsamości agenta Foundry, przekaż --agent-name <new-name> w elemencie azd ai agent init, aby nazwa zapisana w azure.yaml nie kolidowała z domyślną nazwą przykładu.

Inicjowanie z istniejącego kodu

Jeśli masz istniejący kod agenta w języku Python lub .NET, uruchom azd ai agent init w katalogu, który już zawiera Twój kod:

cd my-agent/
azd ai agent init

CLI wykrywa istniejące pliki i generuje wokół nich wpis usługi azure.yaml, nie nadpisując kodu. W przypadku wdrożenia kontenera dodaje również plik Dockerfile. Domyślnie infrastruktura pozostaje bez użycia Bicep, chyba że później zdecydujesz się na infrastrukturę jako kod.

Kod agenta musi spełniać kontrakt czasu wykonywania hostowanego agenta:

  • Nasłuchuj na porcie 8088.
  • Zaserwuj sondę kondycji pod adresem GET /readiness.
  • Obsługa jednego z obsługiwanych protokołów (responses lub invocations).

Jeśli Twój kod jeszcze nie obsługuje jednego z tych protokołów, dodaj adapter protokołu, lekką nakładkę SDK, która tłumaczy między protokołem Foundry a logiką Twojego agenta.

Użyj --src polecenia , aby określić katalog źródłowy lub docelowy na potrzeby inicjowania:

azd ai agent init --src src/my-agent

Dodawanie agenta opartego na plikach do istniejącego projektu

Użyj metody agent add, a nie zastosowania szablonu, jeśli masz bezpośrednią definicję agenta w formacie YAML lub JSON:

azd ai agent add support-agent --file ./agents/support.yaml
azd deploy support-agent

support-agent jest kluczem serwisowym w azure.yaml elemencie, a niekoniecznie nazwą agenta usługi Foundry. Polecenie dodaje lub aktualizuje usługę przy użyciu ścieżki głównej $ref względem azure.yaml. Sprawdza poprawność lokalnie; nie uwierzytelnia, nie kopiuje źródła, nie tworzy zasobów zdalnych ani nie wdraża.

Projekt musi zadeklarować dokładnie jedną azure.ai.project usługę. Użyj --project <service-key>, aby potwierdzić tę usługę, a --source <directory>, aby zastąpić katalog źródłowy agenta. Katalog musi już istnieć wewnątrz projektu.

Inicjowanie agentów promptów i głosowych

To samo rozszerzenie obsługuje agentów bez hostowanego kodu źródłowego. W przypadku agenta promptu wybierz --kind prompt i podaj jego nazwę, model i instrukcje:

azd ai agent init --kind prompt \
  --agent-name support-agent \
  --model <model-name> \
  --instructions "Answer support questions concisely."

Użyj --description do podsumowania agenta monitu. --rai-policy Dołącza istniejącą zasadę konta według nazwy lub identyfikatora usługi ARM; none dziedziczy domyślne ustawienie konta. Ta opcja nie tworzy zasad i jest ignorowana dla hostowanych agentów. Podczas wdrażania szablonu zadeklaruj zasady zamiast tego w azure.yaml.

W przypadku zarządzanego agenta głosowego promptu:

azd ai agent init --kind prompt-voice --agent-name support-voice

Model głosu zarządzanego jest domyślnie ustawiony na gpt-realtime i nie wymaga wdrożenia modelu. Użyj --model i --voice , aby wybrać zarządzany model i głos wyjściowy. Ta ścieżka nie obsługuje ustawień źródła, protokołu, kodu i kontenera. Wdróż za pomocą azd provision i azd deploy, a następnie użyj punktu końcowego Voice WebSocket z azd ai agent show z klientem Voice Live. Tekst invoke nie jest klientem obsługi głosowej.

Aby dodać obsługę głosową do hostowanego agenta, należy przyjąć pełny element azure.yaml, który deklaruje obie usługi. Usługa głosowa używa conversationEngine.type: hosted_agent i conversationEngine.name do odwoływania się do hostowanej usługi docelowej. Pola modelType: hosted_agent i targetAgent wcześniejszego typu nie są obsługiwane.

Nawiązywanie połączenia z istniejącym projektem Foundry

Aby zarządzać istniejącym projektem Foundry za pomocą azd, uruchom kreatora i wybierz opcję połączenia z istniejącym projektem. Możesz również pominąć wybór interaktywny, podając bezpośrednio identyfikator zasobu Azure projektu:

azd ai agent init --project-id /subscriptions/{sub}/resourceGroups/{rg}/providers/Microsoft.CognitiveServices/accounts/{account}/projects/{project}

Aby znaleźć identyfikator projektu, otwórz portal Foundry, przejdź do pozycji Zarządzaj>Szczegóły projektu, a następnie skopiuj wartość Identyfikator zasobu.

Warning

Gdy inicjalizujesz istniejący projekt za pomocą --project-id, narzędzie pomija automatyczne przypisania ról, które wykonuje podczas tworzenia nowego projektu. Upewnij się, że wymagane role są już przypisane. Pełną macierz można znaleźć w informacjach referencyjnych dotyczących uprawnień hostowanych agentów.

Przejrzyj, co zostanie utworzone

Domyślnie init tworzy następującą strukturę projektu. Plik Dockerfile jest potrzebny tylko do wdrożenia kontenera:

.
|-- azure.yaml                  # Unified azd project and hosted agent configuration
|-- src/
|   \-- <agent-name>/
|       |-- Dockerfile          # Container build definition
|       \-- ...                 # Agent source code
|-- .azure/                     # Environment configuration
\-- infra/                      # Optional IaC, created when you pass --infra

Szablony i przykłady udostępniają ujednolicony azure.yaml w katalogu głównym projektu. Podczas inicjowania azd przyjmuje lub generuje ten plik. Domyślnie nie trzeba utrzymywać Bicep ani plików programu Terraform, chyba że zdecydujesz się na wyrzucenie infrastruktury.

W przypadku agentów Python przejrzyj wygenerowaną usługę agenta i dodaj PYTHONNOUSERSITE: "1" do mapy env przed lokalnym testowaniem lub wdrożeniem. Zainstaluj zależności w środowisku wirtualnym agenta lub w jego obrazie, a nie w katalogu user-site. Zobacz Konfigurowanie uruchamiania Pythona.

Wybierz infrastrukturę Terraform lub Bicep

Aby zarządzać infrastrukturą za pomocą programu Terraform, wybierz ją podczas inicjowania projektu:

azd ai agent init --infra=terraform

Tryb infrastruktury i wdrażania to niezależne opcje. W przypadku agenta opartego na kontenerach z infrastrukturą programu Terraform użyj:

azd ai agent init --infra=terraform --deploy-mode container

W nowym projekcie polecenie zapisuje pliki Terraforma w katalogu infra/ i konfiguruje dostawcę infrastruktury Terraform w azure.yaml. W projekcie z istniejącą infrastrukturą infrastrukturę Foundry można wygenerować jako oddzielną warstwę pod elementem infra/foundry/. Przed aprowizowaniem przejrzyj wygenerowaną konfigurację.

Aby zamiast tego wybrać Bicep, użyj --infra=bicep lub skróconej formy --infra. Pominięcie --infra zachowuje domyślny przepływ pracy bez infrastruktury.

azd provision wdraża wybraną infrastrukturę. azd deploy nadal tworzy wersję hostowanego agenta; wybór Terraform nie przenosi zarządzania wersją agenta do stanu Terraform.

Aby uzyskać informacje na temat struktury i dostosowywania plików, zobacz Hostowana infrastruktura agenta. Przed użyciem narzędzia Terraform w potoku skonfiguruj Terraform CI/CD i zdalny stan.