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

Important

Položky označené (Preview) v tomto článku jsou aktuálně ve verzi Public Preview. Tato verze Preview je poskytována bez smlouvy o úrovni služeb a nedoporučujeme ji 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.

Rozhraní příkazového řádku pro vývojáře Azure (azd) a jeho azd ai agent rozšíření poskytují jeden pracovní postup příkazového řádku, který vám umožní přejít z nápadu na hostovaného agenta připraveného pro produkční prostředí v Microsoft Foundry. 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 projektu ze šablony nebo existujícího kódu Rychlý start: Nasazení hostovaného agenta
Definovat Nakonfigurujte agenta, závislosti nasazení modelu, protokoly, nástroje a prostředí v azure.yaml. Vytvořit azure.yaml pro hostované agenty
Develop Pište logiku agenta, přidejte nástroje a otestujte místně. Přehled 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 se zaměřuje na hostované agenty.

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.

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í.

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 azd neexistuje samostatný soubor agent.yaml ani agent.manifest.yaml.

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.

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á.

# 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

  • Last updated on