Poznámka:
Přístup k této stránce vyžaduje autorizaci. Můžete se zkusit přihlásit nebo změnit adresáře.
Přístup k této stránce vyžaduje autorizaci. Můžete zkusit změnit adresáře.
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
azdpříkazy určí koncový bod projektu Foundry na základě aktivního prostředíazd. - Mimo projekt
azdnastavte aktivní kontext jednou pomocí příkazuazd ai project set <endpoint>nebo předejte--project-endpointjednotlivému příkazu pro prostředky (connection,toolbox,skillneboroutine). Jako záložní možnostazd ainač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 evala místníeval.yaml, včetně pracovního postupu optimalizátoru. Vyhodnocení projektu používá samostatně nainstalované rozšířeníazd ai evalaevals/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