Vývoj agentů pomocí rozhraní příkazového řádku pro vývojáře Azure

Important

Položky označené jako náhled v tomto článku jsou aktuálně ve verzi Preview. Tato verze Preview se poskytuje bez smlouvy o úrovni služeb a Microsoft ji nedoporučuje pro produkční úlohy. Některé funkce nemusí být podporované nebo můžou mít omezené možnosti. Další informace najdete v dodatečných podmínkách použití pro verze Preview v Microsoft Azure.

Azure Developer CLI (azd) a jeho rozšíření azd ai agent vám poskytují jednotný pracovní postup v příkazovém řádku, který vás dovede od nápadu k agentovi připravenému pro produkční nasazení v Microsoft Foundry. Můžete vyvíjet hostované agenty založené na kódu a deklarativní hlasové agenty založené na výzvách. Tento článek vysvětluje cestu vývojáře, soubory, které definují agenta, a základní koncepty, se kterými se setkáte.

Tento článek je určený pro vývojáře, kteří upřednostňují terminálový a skriptovatelný pracovní postup prostřednictvím portálu Foundry nebo sad SDK jazyků.

Cesta vývojáře

Pracovní azd ai postup se řídí stejným životním cyklem bez ohledu na to, jestli vytváříte malý prototyp nebo produkčního agenta. Základ projektu vytvoříte jen jednou a pak příkazy libovolně kombinujete podle toho, jak se projekt rozrůstá.

Stage Co děláte Kde se dozvědět více
Install Nainstalujte azd a rozšíření Foundry. Nastavte si vývojové prostředí
Kostra Inicializace hostovaného agenta ze šablony nebo existujícího kódu nebo vytvoření hlasového agenta založeného na příkazovém řádku Rychlý start: Nasazení hostovaného agenta nebo Rychlý start: Vytvoření hlasového agenta na základě promptu
Definovat Nakonfigurujte agenta, závislosti nasazení modelu, protokoly, nástroje a prostředí v azure.yaml. Vytvořit azure.yaml pro hostované agenty
Develop Napište logiku agenta, přidejte nástroje pomocí sady nástrojů a otestujte místně. Přehled panelu nástrojů
Deploy Zřiďte infrastrukturu a nasaďte ji do Foundry. Nasazení hostovaného agenta
Provozovat Monitorujte protokoly, spravujte verze a automatizujte spuštění. Spravovat hostované agenty
Evaluate Změřte kvalitu agenta a vylepšete prompt. Spusťte evaluace agenta pomocí rozhraní příkazového řádku azd

Typy agentů

Rozšíření azd ai agent podporuje hostované agenty, agenty založené na výzvách a hlasové agenty.

Typ Description Kdy ho použít
Hostovaný agent Aplikace, kterou nasadíte jako zdrojový kód nebo image kontejneru. Potřebujete vlastní logiku, integraci architektury nebo úplnou kontrolu nad chováním.
Rychlý agent Agent definovaný výhradně prostřednictvím instrukcí a konfigurací nástrojů bez vlastního kódu. Chcete rychlého agenta řízeného konfigurací bez psaní kódu aplikace.
Hlasový agent Hlasový agent s deklarativním promptem nebo hlasový wrapper, který se připojuje k hostovanému agentovi. Potřebujete hlasový zážitek v reálném čase prostřednictvím klienta Voice Live.

Hostovaní agenti poskytují úplnou kontrolu nad integrací modulu runtime, architektury a nástrojů, zatímco Foundry zpracovává infrastrukturu, škálování a správu relací.

Hlasoví agenti založení na promptech nevyžadují vlastní kontejner. Pokud potřebujete ve vlastním kontejneru spustit vlastní kanál řeč na řeč nebo kaskádový audio kanál, vytvořte hlasového agenta pomocí hostovaného agenta a použijte protokol invocations_ws.

Chcete-li zachovat logiku konverzace v hostovaném textovém agentovi, zatímco Voice Live zpracovává zvuk, použijte pracovní postup hostovaného hlasového wrapperu. Obálka a cíl jsou samostatné služby ve stejném azure.yaml projektu. Tento tok nenahrazuje stávající vlastní invocations_ws tok zpracování zvuku.

Před použitím možností hlasového rozhraní příkazového řádku zkontrolujte nainstalované rozšíření, jak je popsáno v předpokladech pro rychlý start hlasového agenta.

Konfigurační soubory

Projekt hostovaného agenta používá jeden azure.yaml soubor v kořenovém adresáři projektu k deklaraci agenta i jeho modelu zřizování a nasazení. Soubor používá model rozdělené služby, kde každá pojmenovaná služba má host hodnotu, například azure.ai.project, azure.ai.agent, azure.ai.connection, azure.ai.toolbox, azure.ai.skillnebo azure.ai.routine.

File Purpose Kdo ho udržuje
azure.yaml Deklaruje projekt Foundry, nasazení modelu, službu hostovaného agenta, závislosti, protokoly, nástroje, proměnné prostředí, prostředky kontejneru a nastavení nasazení. Identita agenta, model, protokoly, nástroje a hodnoty prostředí jsou v provozu ve službě azure.ai.agent . Inicializace ji vygeneruje. Podle potřeby ho přizpůsobíte.

Služba azure.ai.agent definuje vašeho agenta vloženě nebo prostřednictvím explicitního kořenového prvku $ref pro přímou definici YAML nebo JSON. Používá se azd ai agent add <service> --file <path> pro službu založenou na souboru. Parametrizované AgentManifest obaly nejsou podporovány aktuální inicializací. Seznam uses: služby odkazuje na závislosti, jako je projekt, připojení a sady nástrojů.

V případě hlasového agenta azure.yaml založeného na příkazovém řádku uloží definici deklarativního agenta, včetně kind: prompt-voicemodelu, typu modelu a názvu agenta. Nezahrnuje kontejnerové prostředí běhu pro hostovaného agenta. Pokud chcete přizpůsobit pokyny, zvuk, rozpoznávání zvuku, přepis, hlasový výstup, nástroje a pozdravy, přečtěte si téma Konfigurace hlasového agenta.

U hostovaného hlasového obalu conversationEngine.name odkazuje na název služby hostovaného cíle. Závislost obálky uses určuje pořadí nasazení a conversationEngine.version ve výchozím nastavení používá verzi nasazenou v aktuálním prostředí. Informace o konfiguračních polích najdete v referenčních informacích ke službě Voice Service .

Nahrazení proměnných

Použijte ${VAR_NAME} v azure.yaml pro hodnoty, které se liší v závislosti na prostředí azd. Zástupný symbol se vyhodnocuje pomocí .azure/<env>/.env při nasazení nebo za běhu, takže stejné azure.yaml funguje napříč prostředími, jako jsou dev, staging a produkce.

Kde běží rozhraní příkazového řádku

Příkazy azd ai fungují uvnitř i mimo azd adresář projektu:

  • V projektu azd příkazy určí koncový bod projektu Foundry na základě aktivního prostředí azd.
  • Mimo projekt azd nastavte aktivní kontext jednou pomocí příkazu azd ai project set <endpoint> nebo předejte --project-endpoint jednotlivému příkazu pro prostředky (connection, toolbox, skill nebo routine). Jako záložní možnost azd ai načte proměnnou prostředí FOUNDRY_PROJECT_ENDPOINT.
  • Neprázdný endpoint vyřešený z aktivního prostředí má přednost před globálním kontextem. Informace o záložním shellu a chování specifickém pro příkazy najdete v tématu Nastavte kontext projektu.

Protocols

Protokol definuje kontrakt HTTP mezi Foundry a kontejnerem vašeho agenta. Váš agent naslouchá na portu 8088 a poskytuje kontrolu stavu nezávisle na protokolu.

Protocol Styl rozhraní API Kdy ho použít
responses Responses API od OpenAI (POST /responses) Standardní volba kompatibilní s ekosystémem rozhraní OpenAI API.
invocations Vlastní kontrakt JSON (POST /invocations) Pokud potřebujete úplnou kontrolu nad payloady požadavků a odpovědí.

Úplnou specifikaci najdete v dokumentu Hosted agent runtime contract.

Tato nastavení protokolu platí pro kontejnery hostovaného agenta. Hlasoví agenti založení na promtech nekonfigurují protokol hostovaného agenta.

azd ai agent invoke nepodporuje hlasové hovory pro hlasové agenty založené na promtech ani hostované hlasové wrapery. Pokyny k chování a testování rozhraní příkazového řádku najdete v tématu Omezení hlasového agenta.

Sezení a konverzace

Concept Description
Session Izolované spouštěcí prostředí pro interakci s jedním agentem. Každá relace probíhá ve vlastním sandboxu s vyhrazenými prostředky.
Konverzace Historie zpráv pro protokol Responses. Volání automaticky neuchovávají historii konverzací.

Relace jsou identifikovány pomocí session_id. CLI uloží výběr relace pro každého agenta a ve výchozím nastavení ho znovu použije. Pomocí --new-session můžete začít znovu nebo pomocí --session-id <id> cílit na konkrétní relaci. Mezipaměť není indexována podle delegovaného uživatele. Při použití --user-identity zachovejte explicitní mapování uživatele na relaci.

Zdroje v projektu Foundry

Projekt Foundry hostuje více než agenty. Obsahuje také sdílené zdroje, na které agenti za běhu odkazují. Rozhraní příkazového řádku spravuje každý z nich prostřednictvím vyhrazené skupiny příkazů.

Resource Co to je Spravováno pomocí
Connection Propojuje projekt Foundry s externím prostředkem, například serverem MCP, Foundry IQ (Azure AI Vyhledávač) nebo Grounding with Bing. azd ai connection příkazy
Skříňka na nářadí Pojmenovaná sada nástrojů, které agenti používají za běhu. azd ai toolbox příkazy
Dovednost Opakovaně použitelné pokyny k chování sdílené mezi agenty v projektu. azd ai skill příkazy
Rutina Spouštěč a akce, která spustí agenta. azd ai routine příkazy

Tyto prostředky se sdílejí mezi vývojáři a agenty ve stejném projektu. Jejich příkazy se liší: připojení a rutiny mají update, dovednosti publikují novou verzi prostřednictvím update a toolboxy používají mutace připojení a dovedností vytvářející verze, po nichž následuje publish.

Vyhodnotit a vylepšit agenta

Po spuštění agenta vám dva související pracovní postupy pomohou měřit a zlepšit jeho kvalitu:

  • Rychlé vyhodnocení agenta používá azd ai agent eval a místní eval.yaml, včetně pracovního postupu optimalizátoru. Vyhodnocení projektu používá samostatně nainstalované rozšíření azd ai eval a evals/azure.eval.yaml, se zdroji trasování nebo datovými sadami a explicitními branami kvality CI. Tyto dva formáty konfigurace nejsou vzájemně zaměnitelné.
  • Optimalizace iterativně přepisuje prompt agenta s cílem zlepšit hodnoticí signál. Používá hodnocení jako cílovou funkci a vytvoří návrh promptu, který zkontrolujete a schválíte. Spravujete to pomocí azd ai agent optimize.

Podrobnosti najdete v tématech Spuštění vyhodnocení agenta pomocí rozhraní příkazového řádku azd a Optimalizace promptů agenta.

Skupiny příkazů podle role vývojáře

Zvolte příkaz pro požadovaný výsledek. Přidejte --help pro kontrolu příznaků a podporovaných výstupních formátů.

Job Commands Guidance
Nakonfigurujte projekt a spravované modely azd ai project add, azd ai project deployment add Konfigurace a kontext projektu Project
Vyberte nebo zkontrolujte kontext koncového bodu azd ai project set, azd ai project show, azd ai project unset, azd ai project context Globální výběr koncového bodu probíhá odděleně od deklarací infrastruktury. Kontextový výstup může obsahovat citlivé informace.
Procházejte ukázky nebo inicializujte agenta azd ai agent sample list, azd ai agent init, azd ai agent add Inicializujte hostované, promptové a hlasové agenty
Analyzujte, extrahujte a klasifikujte dokumenty a obsah pro agenty azd ai cu analyze, azd ai cu analyzer Azure Content Understanding CLI: rychlý start (preview)
Místní spuštění a kontrola azd ai agent run, azd ai inspector launch Místní vývoj
Vyvolání, delegování identity uživatele nebo odesílání vlastních hlaviček azd ai agent invoke Možnosti vyvolání
Zkontrolujte, sledujte nebo zrušte práci azd ai agent invocations show, azd ai agent invocations follow, azd ai agent invocations cancel Dlouhotrvající volání
Zkontrolovat nebo aktualizovat koncový bod azd ai agent endpoint show, azd ai agent endpoint update Aktualizace endpointu a karty
Kontrola stavu, diagnostika problémů nebo čtení protokolů azd ai agent show, azd ai agent doctor, azd ai agent monitor Diagnostika a protokoly
Vytvořit, vypsat, zkontrolovat, zastavit nebo odstranit sandbox azd ai agent sessions create, azd ai agent sessions list, azd ai agent sessions show, azd ai agent sessions stop, azd ai agent sessions delete Správa relací
Vytvořit, načíst nebo udržovat soubory sandboxu azd ai agent files upload, azd ai agent files download, azd ai agent files mkdir, azd ai agent files stat, azd ai agent files list, azd ai agent files delete Operace se soubory relací
Obnovit nasazený zdroj azd ai agent code download Stáhnout kód nebo soubor ZIP
Zkontrolujte perzistentní úložiště a udržujte sdílené položky azd ai agent state-stores list, azd ai agent state-stores select, azd ai agent state-stores show, azd ai agent state-stores items Operace a limity úložiště stavu
Přidání závislostí agenta do konfigurace nasazení azd ai agent connection add, azd ai agent toolbox add Obě služby už musí existovat v azure.yaml. Tyto příkazy přidávají položky uses, nikoli vzdálené prostředky.
Spravovat přihlašovací údaje a metadata připojení azd ai connection create, azd ai connection list, azd ai connection show, azd ai connection update, azd ai connection delete Ověřování a údržba připojení
Vytváření, verze nebo stahování opakovaně použitelných dovedností 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 Postupy dovedností
Vytváření a správa nástrojů azd ai toolbox add, azd ai toolbox create, azd ai toolbox list, azd ai toolbox show, azd ai toolbox delete Konfigurace panelu nástrojů
Rozvíjejte a propagujte kolekce nástrojů azd ai toolbox connection, azd ai toolbox skill, azd ai toolbox versions list, azd ai toolbox publish Mutační větev z nejnovější verze; povýšení je explicitní.
Plánování, odesílání nebo kontrola rutin 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 Rutinní pracovní postupy
Generování a spuštění rychlého vyhodnocení azd ai agent eval generate, azd ai agent eval update, azd ai agent eval run, azd ai agent eval list, azd ai agent eval show Rychlé vyhodnocení a prostředky optimalizátoru
Vylepšete a nasaďte kandidáta na optimalizaci azd ai agent optimize, azd ai agent optimize status, azd ai agent optimize cancel, azd ai agent optimize apply, azd ai agent optimize list, azd ai agent optimize deploy Pracovní postup optimalizace
Zabalte nebo publikujte Activity agent pro Teams azd ai agent pack, azd ai agent publish Distribuce Teams
Odstranit hostovanou verzi nebo agenta azd ai agent delete Odstranění agenta
Vyhodnocení projektu a vynutit kvalitativní brány 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 Vyhodnocení Project; nainstalujte azure.ai.evaluations samostatně.
Registrovat a verzovat znovu použitelné datové sady azd ai dataset životní cyklus datové sady; nainstalujte azure.ai.dataset samostatně.
Odeslat, pozastavit, obnovit, zrušit nebo nasadit úlohy jemného ladění azd ai finetuning init, azd ai finetuning jobs Jemné ladění; nainstalujte azure.ai.finetune samostatně.
Nahrávání a správa vah vlastních modelů azd ai models Import a údržba vlastních modelů; nainstalujte azure.ai.models samostatně.

Každé rozšíření, které přidává příkazy version, zpřístupňuje version; místo toho zkontrolujte microsoft.foundry sadu azd ext list. Skupiny propojení, rutiny a dovedností také zpřístupňují context pro místní kontrolu projektu a prostředí; považujte výstup za potenciálně citlivý.

Distribuce agenta aktivit

Po nasazení agenta protokolu aktivit azd ai agent pack vytvoří appPackage.zip pro boční načítání. Použijte --output-dir, --display-name a --app-version k přizpůsobení balíčku. Vytváření balíčku není stejné jako publikování.

azd ai agent publishpublikuje prostřednictvím Microsoft 365. Agenti Simple Activity ve výchozím nastavení používají distribuci shared, pokud není nakonfigurováno jinak; --scope tenant vyžaduje schválení správce. Digitální pracovníci vyžadují rozsah tenanta. Použijte opakovatelné hodnoty --access-boundary, --clear-access-boundaries pro odebrání existujících hranic a opakovatelné hodnoty --optional-permission-scope <resource-app-id>=<scope> pro volitelná oprávnění. personal není rozsah publikování; použijte pack --scope personal a nahrajte balíček bokem pro testování jednotlivých uživatelů.

Životní cyklus nasazení

Úplná smyčka vývojáře kondenzuje do krátké posloupnosti příkazů. Jednou vygenerujte základní strukturu a pak používejte přímé příkazy, jak se projekt rozrůstá.

Postup pro spravovaného hlasového agenta najdete v článku Rychlý start: Vytvoření hlasového agenta s výzvou.

# 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