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.
Interfejs wiersza polecenia dewelopera Azure (azd) i jego azd ai agent rozszerzenie zapewniają jeden przepływ pracy wiersza polecenia umożliwiający przejście od pomysłu do agenta gotowego do produkcji na platformie Microsoft Foundry. Można tworzyć agentów hostowanych na podstawie kodu i deklaratywnych agentów głosowych opartych na monitach. W tym artykule wyjaśniono podróż deweloperów, pliki definiujące agenta oraz podstawowe pojęcia, które napotykasz po drodze.
Ten artykuł jest przeznaczony dla deweloperów, którzy preferują przepływ pracy oparty przede wszystkim na terminalu i skryptach zamiast portalu Foundry lub zestawów SDK dla języków programowania.
Podróż dewelopera
Przepływ pracy azd ai przebiega według tego samego cyklu życia niezależnie od tego, czy tworzysz mały prototyp, czy agenta produkcyjnego. Raz tworzysz szkielet projektu, a potem w miarę jego rozwoju możesz dowolnie łączyć polecenia.
| Etapie | Co robisz | Gdzie dowiedzieć się więcej |
|---|---|---|
| Install | Zainstaluj azd i rozszerzenia Foundry. |
Konfigurowanie środowiska deweloperskiego |
| Rusztowanie | Zainicjuj hostowanego agenta na podstawie szablonu lub istniejącego kodu albo utwórz agenta głosowego opartego na monitach. | Szybki start: wdrażanie hostowanego agenta lub Szybki start: tworzenie agenta głosowego z monitem |
| Zdefiniować | Skonfiguruj agenta, zależności wdrażania modelu, protokoły, narzędzia i środowisko w programie azure.yaml. |
Utwórz plik azure.yaml dla hostowanych agentów |
| Develop | Napisz logikę agenta, dodaj narzędzia za pomocą zestawu narzędzi i testuj lokalnie. | Przegląd zestawu narzędzi |
| Zastosuj | Przygotuj infrastrukturę i wdróż do usługi Foundry. | Wdrażanie hostowanego agenta |
| Operate | Monitorowanie dzienników, zarządzanie wersjami i automatyzowanie przebiegów. | Zarządzanie hostowanymi agentami |
| Evaluate | Mierz jakość działania agenta i ulepszaj prompt. | Przeprowadzanie ocen agentów za pomocą narzędzia wiersza polecenia azd |
Typy agentów
Rozszerzenie azd ai agent obsługuje hostowanych, promptowych i głosowych agentów.
| Typ | Opis | Kiedy stosować |
|---|---|---|
| Hostowany agent | Aplikacja wdrażana jako kod źródłowy lub obraz kontenera. | Potrzebujesz niestandardowej logiki, integracji platformy lub pełnej kontroli nad zachowaniem. |
| Pobudzaj agenta | Agent zdefiniowany całkowicie za pomocą instrukcji i konfiguracji narzędzi bez kodu niestandardowego. | Potrzebujesz szybkiego, opartego na konfiguracji agenta bez pisania kodu aplikacji. |
| Agent głosowy | Deklaratywny agent głosowy typu prompt lub nakładka głosowa łącząca się z hostowanym agentem. | Potrzebujesz obsługi głosowej w czasie rzeczywistym za pośrednictwem klienta Voice Live. |
Agenci hostowani zapewniają pełną kontrolę nad środowiskiem uruchomieniowym, strukturą i integracją narzędzi, podczas gdy platforma Foundry obsługuje infrastrukturę, skalowanie i zarządzanie sesjami.
Agenty głosowe oparte na promptach nie wymagają niestandardowego kontenera. Jeśli musisz uruchomić niestandardowy potok przetwarzania mowy na mowę lub kaskadowy potok przetwarzania audio we własnym kontenerze, utwórz agenta głosowego przy użyciu hostowanego agenta i użyj protokołu invocations_ws.
Aby zachować logikę konwersacji w hostowanym agencie tekstowym, gdy usługa Voice Live obsługuje dźwięk, użyj workflow hostowanej otoki głosowej. Otoczka i element docelowy są oddzielnymi usługami w tym samym projekcie azure.yaml. Ten proces nie zastępuje istniejącego, niestandardowego invocations_ws procesu potoku audio.
Przed użyciem opcji CLI agenta głosowego dostępnych w publicznej wersji zapoznawczej sprawdź zainstalowane rozszerzenie zgodnie z opisem w wymaganiach wstępnych przewodnika Szybki start agenta głosowego.
Pliki konfiguracji
Projekt hostowanego agenta używa jednego azure.yaml pliku w katalogu głównym projektu, aby zadeklarować zarówno agenta, jak i jego model aprowizacji i wdrażania. Plik używa modelu usług rozdzielonych, w którym każda usługa o określonej nazwie ma wartość host, taką jak azure.ai.project, azure.ai.agent, azure.ai.connection, azure.ai.toolbox, azure.ai.skill lub azure.ai.routine.
| File | Purpose | Kto go utrzymuje |
|---|---|---|
azure.yaml |
Deklaruje projekt Foundry, wdrożenia modelu, hostowaną usługę agenta, zależności, protokoły, narzędzia, zmienne środowiskowe, zasoby kontenera i ustawienia wdrożenia. Tożsamość agenta, model, protokoły, narzędzia i wartości środowiska znajdują się w usłudze azure.ai.agent. |
Inicjalizacja generuje go. Dostosujesz go zgodnie z potrzebami. |
Usługa azure.ai.agent definiuje agenta w tekście lub za pośrednictwem jawnego elementu głównego $ref do bezpośredniej definicji YAML lub JSON. Użyj azd ai agent add <service> --file <path> do obsługi usługi opartej na plikach. Sparametryzowane opakowania AgentManifest nie są obsługiwane przez obecną inicjalizację. Lista odwołań usługi uses: zawiera odwołania do zależności, takich jak projekt, połączenia i przyborniki narzędzi.
W przypadku agenta głosowego opartego na promptach element azure.yaml przechowuje deklaratywną definicję agenta, w tym kind: prompt-voice, model, typ modelu i nazwę agenta. Nie obejmuje środowiska uruchomieniowego kontenera agenta hostowanego. Aby dostosować instrukcje, dźwięk, wykrywanie kolei, transkrypcję, wyjście głosowe, narzędzia i powitania, zobacz Konfigurowanie agenta głosowego.
W przypadku hostowanej otoczki głosowej element conversationEngine.name odnosi się do nazwy usługi hostowanego elementu docelowego. Zależność wrappera uses określa kolejność wdrażania, a conversationEngine.version domyślnie przyjmuje wersję wdrożoną w bieżącym środowisku. Zobacz dokumentację usługi głosowej dla pól konfiguracji.
Podstawianie zmiennych
Użyj elementu ${VAR_NAME} w azure.yaml dla wartości, które różnią się w zależności od azd środowiska. Symbol zastępczy jest rozwiązywany na podstawie .azure/<env>/.env podczas wdrażania lub uruchamiania, więc ten sam azure.yaml działa w różnych środowiskach, takich jak dev, staging i production.
Gdzie działa CLI
Polecenia azd ai działają zarówno wewnątrz, jak i poza katalogiem azd projektu:
- W projekcie
azdpolecenia ustalają punkt końcowy projektu Foundry na podstawie aktywnego środowiskaazd. - Poza projektem
azdustaw aktywny kontekst jednokrotnie za pomocąazd ai project set <endpoint>lub przekaż--project-endpointw pojedynczym poleceniu zasobu (connection,toolbox,skilllubroutine). Awaryjnieazd aiodczytuje zmienną środowiskowąFOUNDRY_PROJECT_ENDPOINT. - Niepusty punkt końcowy rozpoznany z aktywnego środowiska ma pierwszeństwo przed kontekstem globalnym. Aby zapoznać się z awaryjnym zachowaniem powłoki i zachowaniem specyficznym dla polecenia, zobacz Ustaw kontekst projektu.
Protocols
Protokół definiuje kontrakt HTTP między usługą Foundry i kontenerem agenta. Agent nasłuchuje na porcie 8088 i obsługuje sondę kondycji, niezależnie od protokołu.
| Protocol | Styl interfejsu API | Kiedy stosować |
|---|---|---|
responses |
API Responses OpenAI (POST /responses) |
Wybór standardowy zgodny z ekosystemem interfejsu API OpenAI. |
invocations |
Niestandardowy kontrakt JSON (POST /invocations) |
Gdy potrzebujesz pełnej kontroli nad treścią żądań i odpowiedzi. |
Pełną specyfikację znajdziesz w dokumencie Umowa dotycząca środowiska uruchomieniowego hostowanego agenta.
Te ustawienia protokołu dotyczą kontenerów agentów hostowanych. Agenci głosowi oparci na promptach nie konfigurują protokołu hostowanego agenta.
azd ai agent invoke nie obsługuje rozmów głosowych dla agentów głosowych opartych na promptach ani hostowanych nakładek głosowych. Aby uzyskać wskazówki dotyczące działania i testowania interfejsu wiersza polecenia, zobacz Ograniczenia agenta głosowego.
Sesje i konwersacje
| Pojęcie | Opis |
|---|---|
| Session | Izolowane środowisko wykonywania dla jednej interakcji z agentem. Każda sesja działa we własnym sandboxie z wydzielonymi zasobami. |
| Rozmowa | Historia komunikatów protokołu Responses. Wywołania nie zapisują automatycznie historii rozmów. |
Sesje są identyfikowane przez element session_id. Interfejs wiersza polecenia zapisuje wybór sesji dla każdego agenta i domyślnie ponownie go używa. Użyj --new-session, aby rozpocząć nową sesję, lub --session-id <id>, aby wskazać konkretną sesję. Pamięć podręczna nie jest indeksowana według delegowanego użytkownika; zachowaj jawne mapowanie typu użytkownik-sesja podczas korzystania z polecenia --user-identity.
Zasoby dotyczące projektu Foundry
Projekt Foundry zawiera więcej niż tylko agentów. Zawiera również zasoby współdzielone, do których agenci odwołują się w czasie wykonywania. CLI zarządza każdym z nich za pośrednictwem osobnej grupy poleceń.
| Resource | Co to jest | Zarządzane za pomocą |
|---|---|---|
| Connection | Łączy projekt Foundry z zasobem zewnętrznym, takim jak serwer MCP, Wyszukiwanie AI platformy Azure lub grounding z usługą Bing. |
azd ai connection polecenia |
| Skrzynka z narzędziami | Nazwany zbiór narzędzi używanych przez agentów w czasie działania. |
azd ai toolbox polecenia |
| Umiejętności | Wspólne zasady zachowania współdzielone między agentami w projekcie. |
azd ai skill polecenia |
| Procedura | Wyzwalacz oraz akcja, która wywołuje agenta. |
azd ai routine polecenia |
Te zasoby są współużytkowane przez deweloperów i agentów w tym samym projekcie. Ich polecenia różnią się: połączenia i rutyny mają update, umiejętności publikują nową wersję przez update, a zestawy narzędzi używają mutacji połączeń i umiejętności tworzących wersję, a następnie publish.
Ocenianie i ulepszanie agenta
Po uruchomieniu agenta dwa powiązane przepływy pracy pomagają zmierzyć i poprawić jego jakość:
- Szybka ocena agenta używa polecenia
azd ai agent evali lokalnegoeval.yaml, w tym przepływu pracy optymalizatora. Ocena projektu wykorzystuje oddzielnie zainstalowane rozszerzenieazd ai evalievals/azure.eval.yaml, ze źródłami śledzenia lub zbiorów danych oraz jawnymi bramami jakości CI. Dwa formaty konfiguracji nie są zamienne. - Optymalizacja iteracyjnie ponownie zapisuje monit agenta, aby podnieść sygnał oceny. Wykorzystuje ocenę jako funkcję celu i tworzy propozycję polecenia, które następnie przeglądasz i akceptujesz. Zarządzasz nim za pomocą polecenia
azd ai agent optimize.
Aby uzyskać szczegółowe informacje, zobacz Uruchamianie ocen agenta za pomocą interfejsu wiersza polecenia azd i Optymalizowanie monitów agenta.
Grupy poleceń według zadania programisty
Wybierz polecenie dla potrzebnego wyniku. Dodaj --help, aby sprawdzić jego flagi i obsługiwane formaty danych wyjściowych.
| Job | Commands | Guidance |
|---|---|---|
| Skonfiguruj projekt i zarządzane modele |
azd ai project add, azd ai project deployment add |
Konfiguracja projektu i kontekst |
| Wybierz lub sprawdź kontekst punktu końcowego |
azd ai project set, azd ai project show, azd ai project unset, azd ai project context |
Wybór globalnego punktu końcowego jest oddzielony od deklaracji infrastruktury. Dane wyjściowe kontekstu mogą zawierać sekrety. |
| Przeglądaj przykłady lub zainicjuj agenta |
azd ai agent sample list, azd ai agent init, azd ai agent add |
Inicjowanie hostowanych agentów, agentów promptów i agentów głosowych |
| Parsowanie, wyodrębnianie i klasyfikowanie dokumentów i zawartości dla agentów |
azd ai cu analyze, azd ai cu analyzer |
Szybki start dotyczący interfejsu CLI usługi Azure Content Understanding (wersja zapoznawcza) |
| Uruchom i sprawdź lokalnie |
azd ai agent run, azd ai inspector launch |
Programowanie lokalne |
| Wywoływanie, delegowanie tożsamości użytkownika lub wysyłanie nagłówków niestandardowych | azd ai agent invoke |
Opcje wywołania |
| Sprawdzanie, śledzenie lub anulowanie zadania |
azd ai agent invocations show, azd ai agent invocations follow, azd ai agent invocations cancel |
Długotrwałe wywołanie |
| Sprawdzanie lub aktualizowanie punktu końcowego |
azd ai agent endpoint show, azd ai agent endpoint update |
Aktualizacje endpointów i kart |
| Sprawdzanie stanu, diagnozowanie problemów lub odczytywanie dzienników |
azd ai agent show, azd ai agent doctor, azd ai agent monitor |
Diagnostyka i dzienniki |
| Utwórz, wyświetl listę, sprawdź, zatrzymaj lub usuń sandbox |
azd ai agent sessions create, azd ai agent sessions list, , azd ai agent sessions show, azd ai agent sessions stopazd ai agent sessions delete |
Zarządzanie sesjami |
| Tworzenie, pobieranie lub obsługa plików piaskownicy |
azd ai agent files upload, azd ai agent files download, azd ai agent files list, azd ai agent files mkdir, azd ai agent files stat, azd ai agent files delete |
Operacje na plikach sesji |
| Odzyskaj wdrożone źródło | azd ai agent code download |
Pobierz kod lub plik ZIP |
| Sprawdź trwałe magazyny danych i zarządzaj elementami współdzielonymi |
azd ai agent state-stores list, azd ai agent state-stores select, azd ai agent state-stores show, azd ai agent state-stores items |
Operacje i limity magazynu stanu |
| Dodawanie zależności agenta do konfiguracji wdrożenia |
azd ai agent connection add, azd ai agent toolbox add |
Obie usługi muszą już istnieć w azure.yaml; te polecenia dodają wpisy uses, a nie zasoby zdalne. |
| Zarządzanie poświadczeniami połączenia i metadanymi |
azd ai connection create, azd ai connection list, , azd ai connection show, azd ai connection updateazd ai connection delete |
Uwierzytelnianie połączeń i konserwacja |
| Twórz, wersjonuj lub pobieraj umiejętności wielokrotnego użytku |
azd ai skill add, azd ai skill create, , azd ai skill update, azd ai skill list, azd ai skill show, , azd ai skill downloadazd ai skill delete |
Przepływy pracy dla umiejętności |
| Twórz przyborniki i zarządzaj nimi |
azd ai toolbox add, azd ai toolbox create, , azd ai toolbox list, azd ai toolbox showazd ai toolbox delete |
Konfiguracja przybornika |
| Rozwijaj i promuj kolekcje narzędzi |
azd ai toolbox connection, azd ai toolbox skill, azd ai toolbox versions list, azd ai toolbox publish |
Mutacje wywodzą się z najnowszej wersji; promowanie jest jawne. |
| Planowanie, przydzielanie lub sprawdzanie zadań |
azd ai routine add, azd ai routine create, azd ai routine list, azd ai routine show, azd ai routine update, azd ai routine enable, azd ai routine disable, azd ai routine dispatch, azd ai routine run list, azd ai routine delete |
Rutynowe przepływy pracy |
| Wygeneruj i uruchom szybką ocenę |
azd ai agent eval generate, azd ai agent eval update, , azd ai agent eval run, azd ai agent eval listazd ai agent eval show |
Zasoby szybkiej oceny i optymalizatora |
| Ulepszanie i wdrażanie kandydata optymalizacji |
azd ai agent optimize, azd ai agent optimize status, azd ai agent optimize list, azd ai agent optimize cancel, azd ai agent optimize apply, azd ai agent optimize deploy |
Przepływ pracy optymalizacji |
| Spakuj lub opublikuj agenta Activity dla usługi Teams |
azd ai agent pack, azd ai agent publish |
Dystrybucja Teams |
| Usuń hostowaną wersję lub agenta | azd ai agent delete |
Usuwanie agenta |
| Oceń projekt i egzekwuj progi jakości |
azd ai eval init, azd ai eval generate, , azd ai eval create, azd ai eval run, azd ai eval dataset, , azd ai eval evaluatorazd ai eval job |
Project oceny; zainstaluj azure.ai.evaluations oddzielnie. |
| Rejestrowanie i przechowywanie zestawów danych wielokrotnego użytku | azd ai dataset |
Cykl życia zestawu danych; zainstaluj azure.ai.dataset oddzielnie. |
| Prześlij, wstrzymaj, wznów, anuluj lub wdroż zadania dostrajania |
azd ai finetuning init, azd ai finetuning jobs |
Dostrajanie; zainstaluj azure.ai.finetune oddzielnie. |
| Przesyłanie niestandardowych wag modelu i zarządzanie nimi | azd ai models |
Importowanie i konserwacja modelu niestandardowego; zainstaluj azure.ai.models oddzielnie. |
Każde rozszerzenie, które dodaje polecenia uwidacznia version; sprawdź pakiet za microsoft.foundry pomocą azd ext list polecenia . Połączenie, rutynowe i grupy umiejętności są również widoczne context dla lokalnego projektu i inspekcji środowiska; traktują dane wyjściowe jako potencjalnie wrażliwe.
Dystrybucja agenta działań
Po wdrożeniu agenta azd ai agent pack protokołu Activity tworzy appPackage.zip polecenie na potrzeby ładowania bezpośredniego. Użyj polecenia --output-dir, --display-namei --app-version , aby dostosować pakiet. Pakietowanie nie jest tym samym co publikowanie.
azd ai agent publish publikuje za pośrednictwem Microsoft 365. Agenci prostego działania są domyślnie dystrybuowani przez shared, chyba że skonfigurowano inaczej; --scope tenant wymaga zatwierdzenia przez administratora. Pracownicy cyfrowi wymagają zakresu tenanta. Użyj powtarzalnych --access-boundary wartości, --clear-access-boundaries aby usunąć istniejące ograniczenia i powtarzalnych --optional-permission-scope <resource-app-id>=<scope> wartości dla opcjonalnych uprawnień.
personal nie jest zakresem publikacji; użyj pack --scope personal i doładuj pakiet do testów dla pojedynczego użytkownika.
Cykl życia wdrożenia
Pełny cykl pracy dewelopera sprowadza się do krótkiej sekwencji poleceń. Wygeneruj szkielet projektu raz, a następnie używaj bezpośrednich komend w miarę rozwoju projektu.
Informacje o zarządzanej ścieżce dla agenta głosowego znajdziesz w artykule Szybki start: tworzenie agenta głosowego opartego na monicie.
# Scaffold a project from a template or your existing code
azd ai agent init
# Run locally and invoke
azd ai agent run
azd ai agent invoke --local "Hello, world!"
# Provision infrastructure and deploy the agent
azd up
# Extend the project with shared resources at any time
azd ai connection create my-search --kind cognitive-search --target https://... --auth-type api-key --key "..."
azd ai routine create daily-digest --trigger recurring --cron "0 7 * * *" --agent-name my-agent
# Evaluate quality
azd ai agent eval generate
azd ai agent eval run
# Tear down all Azure resources
azd down