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. Nastavení vývojového 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 pro prompty
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í. Správa hostovaných agentů
Evaluate Změřte kvalitu agenta a vylepšete prompt. Spuštění vyhodnocení agenta pomocí rozhraní příkazového řádku azd

Typy agentů

Rozšíření azd ai agent podporuje typy deklarativního agenta založené na kódu.

Typ Description Kdy ho použít
Hostovaný agent Kontejnerizovaná aplikace, kterou sestavíte v kódu, zabalíte jako image Dockeru a nasadíte ji do Foundry. 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 založený na promptu Deklarativní hlasový agent, který používá spravovaný nebo samostatně nasazený model bez vlastního kódu modulu runtime. Chcete konverzační hlasové prostředí v reálném čase bez vytváření a hostování zvukového kanálu.
Hostovaný hlasový agent se spravovanou vrstvou Hostovaný cíl zajišťuje logiku konverzace, zatímco samostatná hlasová služba na něj deleguje prostřednictvím conversationEngine. Voice Live zajišťuje zvukový zážitek. Potřebujete vlastní logiku agenta bez implementace rozpoznávání a syntézy řeči v hostované cílové oblasti.

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 ve verzi Public-Preview zkontrolujte nainstalované rozšíření, jak je popsáno v požadavcích rychlého startu 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 hostovaného agenta přímo v definici a používá uses: k odkazování na další služby, například projekt, připojení, sady nástrojů, dovednosti a rutiny. V aktuálním modelu projektu hostovaného agenta agent.yaml neexistuje samostatný soubor agent.manifest.yaml ani azd.

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.
  • Prostředí v rámci projektu má vždy přednost před globálním kontextem, takže po přepnutí do adresáře projektu se rozhraní příkazového řádku přesměruje na koncový bod daného 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é konverzace pro hlasové agenty založené na promptech ani pro hostované hlasové obalové vrstvy. 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 Posloupnost zpráv v rámci relace. Foundry spravuje historii konverzací a může ji hydratovat napříč požadavky.

Relace jsou identifikovány pomocí session_id. Když spustíte azd ai agent invokepříkaz Foundry, znovu použije relaci z posledního vyvolání ve výchozím nastavení. Pomocí --new-session můžete začít znovu nebo pomocí --session-id <id> cílit na konkrétní 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 zdrojem, jako je server MCP, Azure AI Vyhledávač nebo grounding s Bingem. 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. Každá skupina příkazů zpřístupňuje standardní příkazy create, update, delete, show a list.

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:

  • Vyhodnocení spustí agenta s datovou sadou, vyhodnotí odpovědi pomocí jednoho nebo více vyhodnocovačů a hlásí agregovaný signál kvality. Spravujete to pomocí azd ai agent eval.
  • 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.

Ž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

Související obsah

  • Poslední aktualizace v