Notatka
Dostęp do tej strony wymaga autoryzacji. Może spróbować zalogować się lub zmienić katalogi.
Dostęp do tej strony wymaga autoryzacji. Możesz spróbować zmienić katalogi.
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
- Zainstalowano rozszerzenia Azure Developer CLI Foundry.
- Uwierzytelniona sesja Azure (
azd auth login). - Dostęp jako Współautor do subskrypcji platformy Azure.
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 (
responseslubinvocations).
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.