Agentontwikkeling met de Azure Developer CLI

Important

Items die zijn gemarkeerd als voorbeeld in dit artikel, zijn momenteel beschikbaar als preview-versie. Deze preview wordt aangeboden zonder een service level agreement en Microsoft raadt dit niet aan voor productieworkloads. Bepaalde functies worden mogelijk niet ondersteund of hebben mogelijk beperkte mogelijkheden. Zie Aanvullende gebruiksvoorwaarden voor Microsoft Azure Previews voor meer informatie.

De Azure Developer CLI (azd) en azd ai agent de bijbehorende extensie geven u één opdrachtregelwerkstroom om van idee naar een productieklare agent op Microsoft Foundry te gaan. U kunt op code gebaseerde gehoste agents en declaratieve spraakagents ontwikkelen. In dit artikel worden de ontwikkeltrajecten uitgelegd, de bestanden die een agent definiëren en de belangrijkste concepten die u onderweg tegenkomt.

Dit artikel is bedoeld voor ontwikkelaars die de voorkeur geven aan een terminalgerichte, met scripts te automatiseren workflow in plaats van het Foundry-portal of taalspecifieke SDK's.

Het ontwikkelaarstraject

De azd ai werkstroom volgt dezelfde levenscyclus, ongeacht of u een klein prototype of een productieagent bouwt. U breidt een project eenmaal uit en combineert opdrachten naarmate uw project groeit.

Stage Wat u doet Waar vindt u meer informatie
Install Installeer azd en de Foundry-uitbreidingen. Uw ontwikkelomgeving instellen
Raamwerk Initialiseer een gehoste agent op basis van een sjabloon of uw bestaande code of maak een spraakagent op basis van prompts. Quickstart: Een gehoste agent implementeren of Quickstart: Een spraakagent met prompt maken
Definiëren Configureer de agent, modelimplementatieafhankelijkheden, protocollen, hulpprogramma's en omgeving in azure.yaml. azure.yaml maken voor gehoste agents
Develop Schrijf agentlogica, voeg hulpprogramma's toe met behulp van een werkset en test lokaal. Overzicht van de toolbox
Deploy Infrastructuur inrichten en implementeren in Foundry. Een gehoste agent implementeren
Bedienen Bewaak logboeken, beheer versies en automatiseer uitvoeringen. Gehoste agents beheren
Evaluate Meet de kwaliteit van de agent en verbeter de prompt. Agentevaluaties uitvoeren met de azd CLI

Agenttypen

De azd ai agent extensie ondersteunt op code gebaseerde en declaratieve agenttypen.

Typ Description Wanneer gebruiken
Gehoste agent Een gecontaineriseerde toepassing die u in code bouwt, verpakt als een Docker-image en implementeert naar Foundry. U hebt aangepaste logica, frameworkintegratie of volledige controle over gedrag nodig.
Agent vragen Een agent die volledig is gedefinieerd via instructies en hulpprogrammaconfiguraties, zonder aangepaste code. U wilt een snelle, configuratiegestuurde agent zonder toepassingscode te schrijven.
Spraakagent op basis van prompts Een declaratieve spraakagent die gebruikmaakt van een beheerd of zelf geïmplementeerd model zonder aangepaste runtimecode. U wilt een spraakervaring in realtime voor gesprekken zonder zelf een audiopijplijn te bouwen en te hosten.
Gehoste spraakagent met een beheerde wrapper Een gehoste doelservice handelt de conversatielogica af, terwijl een afzonderlijke spraakservice hieraan via conversationEngine delegeert. Voice Live verwerkt de audio-ervaring. U hebt aangepaste agentlogica nodig zonder spraakherkenning en synthese in het gehoste doel te implementeren.

Gehoste agents bieden u volledige controle over de integraties van runtime, framework en hulpprogramma's, terwijl Foundry infrastructuur, schaalaanpassing en sessiebeheer afhandelt.

Spraakagenten op basis van prompts hebben geen aangepaste container nodig. Als u een aangepaste spraak-naar-spraak- of trapsgewijze audiopijplijn in uw eigen container wilt uitvoeren, bouwt u een spraakagent met een gehoste agent en gebruikt u het invocations_ws protocol.

Als u de gesprekslogica in een gehoste tekstagent wilt houden terwijl Voice Live de audio afhandelt, gebruikt u de workflow voor de gehoste voice-wrapper. De wrapper en het doel zijn afzonderlijke services in hetzelfde azure.yaml project. Deze stroom vervangt niet de bestaande aangepaste invocations_ws audiopijplijnstroom.

Voordat u de CLI-opties voor de openbare previewversie van voice gebruikt, controleert u welke extensie u hebt geïnstalleerd, zoals beschreven in de vereisten voor de quickstart van de spraakagent.

Configuratiebestanden

Een gehost agentproject maakt gebruik van één azure.yaml bestand in de hoofdmap van het project om zowel de agent als het inrichtings- en implementatiemodel te declareren. Het bestand maakt gebruik van een split-servicemodel, waarbij elke benoemde service een host waarde heeft zoals azure.ai.project, azure.ai.agent, azure.ai.connection, azure.ai.toolbox, , of azure.ai.skillazure.ai.routine.

Bestand Purpose Wie onderhoudt het
azure.yaml Declareert het Foundry-project, modelimplementaties, gehoste agentservice, afhankelijkheden, protocollen, hulpprogramma's, omgevingsvariabelen, containerbronnen en implementatie-instellingen. Agentidentiteit, model, protocollen, hulpprogramma's en omgevingswaarden leven in de azure.ai.agent service. Initialisatie genereert deze. U kunt deze naar behoefte aanpassen.

De azure.ai.agent service definieert uw gehoste agent inline en gebruikt uses: om te verwijzen naar andere services, zoals het project, verbindingen, werksets, vaardigheden en routines. Er is geen zelfstandig agent.yaml bestand of agent.manifest.yaml bestand in het huidige projectmodel van de gehoste agent azd .

Voor een spraakagent op basis van prompts slaat azure.yaml u de definitie van de declaratieve agent op, waaronder kind: prompt-voice, het model, het modeltype en de naam van de agent. Het bevat geen containerruntime voor een gehoste agent. Zie Een spraakagent configureren als u instructies, audio, draaidetectie, transcriptie, spraakuitvoer, hulpmiddelen en begroetingen wilt aanpassen.

Voor een gehoste spraakwrapper verwijst conversationEngine.name naar de servicenaam van het gehoste doel. De afhankelijkheid van de wrapper uses bepaalt de implementatievolgorde, en conversationEngine.version is standaard ingesteld op de versie die door de huidige omgeving is geïmplementeerd. Zie de referentie voor de spraakservice voor de configuratievelden.

Variabele vervanging

Gebruik ${VAR_NAME} in azure.yaml voor waarden die per azd omgeving verschillen. De placeholder wordt tijdens het deployen of tijdens runtime opgelost vanuit .azure/<env>/.env, zodat dezelfde azure.yaml werkt in omgevingen zoals dev, staging en productie.

Waar de CLI wordt uitgevoerd

De azd ai commando's werken zowel binnen als buiten een azd projectmap:

  • Opdrachten binnen een azd project lossen het Foundry-projecteindpunt op vanuit de actieve azd omgeving.
  • Buiten een azd-project stelt u de actieve context één keer in met azd ai project set <endpoint>, of geeft u --project-endpoint mee aan een afzonderlijke resource-opdracht (connection, toolbox, skill of routine). Als alternatief leest azd ai de FOUNDRY_PROJECT_ENDPOINT omgevingsvariabele.
  • Een in-projectomgeving heeft altijd voorrang op de globale context, dus het wijzigen van mappen in een project hertarget de CLI op het eindpunt van dat project.

Protocols

Een protocol definieert het HTTP-contract tussen Foundry en uw agentcontainer. Uw agent luistert op poort 8088 en biedt een healthprobe, ongeacht het gebruikte protocol.

Protocol API-stijl Wanneer gebruiken
responses OpenAI-antwoorden-API (POST /responses) De standaardkeuze, compatibel met het OpenAI API-ecosysteem.
invocations Aangepast JSON-contract (POST /invocations) Wanneer u volledige controle nodig hebt over request- en responsepayloads.

Voor de volledige specificatie, zie het runtimecontract van de gehoste agent.

Deze protocolinstellingen zijn van toepassing op gehoste agentcontainers. Spraakagenten op basis van prompts configureren geen protocol voor gehoste agents.

azd ai agent invoke ondersteunt geen spraakconversaties voor promptgebaseerde voice agents of gehoste voice wrappers. Zie De beperkingen van de Voice-agent voor de CLI-gedrag en -tests.

Sessies en gesprekken

Concept Description
Session Een geïsoleerde uitvoeringsomgeving voor één agentinteractie. Elke sessie wordt uitgevoerd in een eigen sandbox met toegewezen resources.
Gesprek Een reeks berichten binnen een sessie. Foundry beheert de gespreksgeschiedenis en kan deze over meerdere aanvragen heen opnieuw laden.

Sessies worden geïdentificeerd door een session_id. Wanneer u azd ai agent invoke uitvoert, gebruikt Foundry standaard opnieuw de sessie van uw laatste aanroep. Gebruik --new-session dit om een nieuwe sessie te starten of --session-id <id> om een specifieke sessie aan te passen.

Bronnen voor een Foundry-project

Een Foundry-project host meer dan agents. Het bevat ook gedeelde resources waarnaar agents tijdens runtime verwijzen. De CLI beheert elke groep via een toegewezen opdrachtgroep.

Resource Wat het is Beheerd met
Connection Koppelt een Foundry-project aan een externe resource, zoals een MCP-server, Azure AI Zoeken of Grounding met Bing. azd ai connection opdrachten
Gereedschapskist Een benoemde verzameling hulpprogramma's die agents tijdens runtime gebruiken. azd ai toolbox opdrachten
Vaardigheid Een herbruikbare gedragsrichtlijn die wordt gedeeld tussen agents in het project. azd ai skill opdrachten
Routine Een trigger plus een actie die een agent aanroept. azd ai routine opdrachten

Deze resources worden gedeeld tussen ontwikkelaars en agents in hetzelfde project. Elke opdrachtgroep maakt de standaardcreate, update, , deleteen showlist werkwoorden beschikbaar.

Een agent evalueren en verbeteren

Nadat een agent heeft uitgevoerd, kunt u met twee verwante workflows de kwaliteit ervan meten en verbeteren:

  • Een evaluatie voert uw agent uit op een dataset, beoordeelt de antwoorden met een of meer beoordelaars en rapporteert een geaggregeerd kwaliteitssignaal. U beheert het met azd ai agent eval.
  • Optimalisatie herschrijft de prompt van je agent iteratief om het evaluatiesignaal te verbeteren. Het maakt gebruik van een evaluatie als objectieve functie en produceert een kandidaatprompt die u beoordeelt en accepteert. U beheert het met azd ai agent optimize.

Zie Agentevaluaties uitvoeren met de azd CLI en agentprompts optimaliseren voor meer informatie.

Levenscyclus van implementatie

De volledige ontwikkelaarslus wordt omgezet in een korte reeks opdrachten. Scaffold eenmaal, gebruik vervolgens de directe opdrachten naarmate uw project groeit.

Voor het traject voor beheerde spraakagenten, zie Quickstart: Een prompt-spraakagent maken.

# 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

Verwante inhoud

  • Laatst bijgewerkt om