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

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ż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.

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 Kompletny projekt szablonowy: pojedynczy azure.yaml, kod źródłowy agenta w katalogu src/<agent-name>/ oraz plik Dockerfile do wdrożenia kontenera. Infrastruktura jest domyślnie bicep mniej i może zostać wyrzucona później. Wygenerowany azure.yaml wpis usługi oraz, do wdrożenia kontenera, plik Dockerfile opakowujący kod. Infrastruktura jest domyślnie bicep mniej i może zostać wyrzucona później. azure.yaml podłączony przewodowo do istniejącego projektu Foundry. Infrastruktura jest domyślnie bicep mniej i może zostać wyrzucona później.
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 Wybierz istniejące wdrożenie modelu lub zostanie ono utworzone na podstawie domyślnych ustawień szablonu.

Nazwa agenta pochodzi z szablonu. CLI tworzy środowisko azd o nazwie <directory>-dev i konfiguruje je przy użyciu informacji z wybranego projektu Foundry. Każdy szablon zawiera kod źródłowy agenta, plik Dockerfile oraz plik azure.yaml, który pełni funkcję ujednoliconego manifestu projektu azd i konfiguracji hostowanego agenta.

Inicjowanie z adresu URL azure.yaml

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

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

Uwaga / Notatka

Manifesty agentów (agent.manifest.yaml) i autonomiczne definicje agentów (agent.yaml) są przestarzałe. Począwszy od wersji rozszerzeń Foundry azd (azure.ai.agents 1.0.0-beta.1), cała konfiguracja hostowanego agenta znajduje się w jednym elemencie azure.yaml. Zobacz Utwórz plik azure.yaml dla agentów hostowanych.

Opcja -m nadal akceptuje adres URL starszego manifestu agenta, ale obecne przykłady publikują ujednolicony azure.yaml.

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

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

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. Infrastruktura pozostaje domyślnie bez bicepu, chyba że infrastruktura zostanie wyrzucona jako kod później.

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.

Aby dodać agenta do istniejącego projektu azd, init wykrywa projekt i dodaje nowy wpis usługi do istniejącego pliku azure.yaml. Użyj --src, aby określić podkatalog:

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

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 project, otwórz portal Foundry, przejdź do pozycji Zarządzaj>Project szczegóły i 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

Po zakończeniu init Twój katalog projektu zawiera następującą strukturę:

.
|-- 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 only after you eject infrastructure

Szablony i przykłady udostępniają ujednolicony azure.yaml w katalogu głównym projektu. Podczas inicjowania azd przyjmuje lub generuje ten plik. Od teraz pracujesz z azure.yaml. Infrastruktura domyślnie nie używa języka Bicep. Wyrzuć infrastrukturę tylko wtedy, gdy musisz bezpośrednio zarządzać wygenerowanymi plikami IaC.

Treści powiązane

  • Last updated on