Programowanie agentów za pomocą 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.

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 azd polecenia ustalają punkt końcowy projektu Foundry na podstawie aktywnego środowiska azd.
  • Poza projektem azd ustaw aktywny kontekst jednokrotnie za pomocą azd ai project set <endpoint> lub przekaż --project-endpoint w pojedynczym poleceniu zasobu (connection, toolbox, skill lub routine). Awaryjnie azd ai odczytuje 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 eval i lokalnego eval.yaml, w tym przepływu pracy optymalizatora. Ocena projektu wykorzystuje oddzielnie zainstalowane rozszerzenie azd ai eval i evals/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