Quickstart: Uw eerste gehoste agent implementeren

• Azure Developer CLI versie 1.23.0 of hoger

• Visual Studio Code
• Microsoft Foundry voor Visual Studio Code extensie

Stap 1: De voorbeeld-project instellen

Installeer de Azure Developer CLI-agentextensie en initialiseer een nieuw gehost agentproject.

1. Installeer de ai agent-extensie voor de Azure Developer CLI:

   azd ext install azure.ai.agents
   

   Voer de volgende opdracht uit om te controleren of de extensie is geïnstalleerd:

   azd ext list
   

2. Initialiseer een nieuw gehoste agent-project:

   azd ai agent init
   

   Wanneer u hierom wordt gevraagd, selecteert u Nieuw beginnen in een sjabloon. De interactieve stroom begeleidt u bij de volgende configuratie:

   • Omgevingsnaam : bepaalt de naam van uw resourcegroep (bijvoorbeeld my-hosted-agent maakt rg-my-hosted-agent).
   • Azure-abonnement: selecteer het abonnement waarin u de Foundry-resources wilt maken.
   • Locatie : selecteer een regio voor de resources.
   • Model-SKU : selecteer de SKU die beschikbaar is voor uw regio en abonnement.
   • Implementatienaam : voer een naam in voor de modelimplementatie.
   • Containergrootte : selecteer de CPU- en geheugentoewijzing of accepteer de standaardwaarden.

   Opmerking

   Als er al een resourcegroep met dezelfde naam bestaat, azd provision wordt de bestaande groep gebruikt. Als u conflicten wilt voorkomen, kiest u eerst een unieke omgevingsnaam of verwijdert u eerst de bestaande resourcegroep.

   Belangrijk

   Als u geen MCP-server gebruikt, maakt u commentaar of verwijdert u de volgende regels in het agent.yaml bestand:

   - name: AZURE_AI_PROJECT_TOOL_CONNECTION_ID
     value: <CONNECTION_ID_PLACEHOLDER>
   

3. Voorzie de vereiste Azure-middelen.

   Opmerking

   U hebt Contributor toegang nodig voor uw Azure-abonnement voor het inrichten van resources.

   azd provision
   

   Deze opdracht duurt ongeveer 5 minuten en maakt de volgende resources:

   Hulpbron	Doel	Kosten
   Bronnengroep	Hiermee worden alle gerelateerde resources in hetzelfde gebied ingedeeld	Geen kosten
   Modellenimplementatie	Model dat door de agent wordt gebruikt	Zie Foundry-prijzen
   Gieterijproject	Host uw agent en biedt AI-mogelijkheden	Op basis van verbruik; zie Foundry pricing
   Azure Container Registry	Slaat de containerafbeeldingen van uw agent op	Basic-laag; zie ACR-prijzen
   Log Analytics werkruimte	Alle logboekgegevens op één plek beheren	Geen directe kosten. Zie Log Analytics kosten
   Analyses van toepassingen	Bewaakt de prestaties en logboeken van de agent	Betalen naar gebruik; zie Azure Monitor-prijzen
   Beheerde identiteit	Verifieert uw agent voor Azure services	Geen kosten

   Aanbeveling

   Voer azd down uit wanneer u deze quickstart hebt voltooid om resources te verwijderen en geen kosten meer in rekening te brengen.

Stap 2: de agent lokaal testen

Controleer voordat u implementeert of de agent lokaal werkt.

1. Start de agent lokaal:

   azd ai agent run
   

   Met deze opdracht wordt automatisch de omgeving ingesteld, afhankelijkheden geïnstalleerd en de agent gestart. Hierbij wordt gebruikgemaakt van de startupCommand gedefinieerde in azure.yaml om uw agent te starten.

   Als de agent niet kan worden gestart, kunt u deze veelvoorkomende problemen controleren:

   Fout	Solution
   AuthenticationError of DefaultAzureCredential fout	Voer opnieuw uit azd auth login om uw sessie te vernieuwen.
   ResourceNotFound	Controleer of uw eindpunt-URL's overeenkomen met de waarden in de Foundry-portal.
   DeploymentNotFound	Controleer de implementatienaam in Build>Deployments.
   Connection refused	Zorg ervoor dat er geen ander proces gebruikmaakt van poort 8088.

2. Verzend in een afzonderlijke terminal een testbericht naar de lokale agent:

   azd ai agent invoke --local "What is Microsoft Foundry?"
   

   U zou een antwoord met zoekresultaten over Microsoft Foundry op internet moeten zien.

Stap 3: Implementeren in Foundry Agent Service

Aangezien u de infrastructuur al in stap 1 hebt ingericht, implementeert u de agentcode in Azure:

azd deploy

De agentcontainer wordt extern gebouwd, dus Docker Desktop is niet vereist op uw computer.

Wanneer u klaar bent, ziet u in de uitvoer een koppeling naar de Agent Playground en het eindpunt voor het programmatisch aanroepen van de agent:

Deploying services (azd deploy)

  (✓) Done: Deploying service af-agent-with-foundry-tools
  - Agent playground (portal): https://ai.azure.com/nextgen/.../build/agents/af-agent-with-foundry-tools/build?version=1 
  - Agent endpoint: https://ai-account-<name>.services.ai.azure.com/api/projects/<project>/agents/af-agent-with-foundry-tools/versions/1

Stap 1: Een Foundry-project maken

Gebruik de Microsoft Foundry-extensie in VS Code om een nieuwe Microsoft Foundry-Project-resource te maken.

1. Open het opdrachtpalet (Ctrl+Shift+P) en selecteer Microsoft Foundry: Create Project.

2. Selecteer uw Azure-abonnement.

3. Maak een nieuwe resourcegroep of selecteer een bestaande resourcegroep.

4. Voer een naam in voor de Foundry Project resource.

Zodra het project is gemaakt, gaat u verder met de volgende stap en implementeert u een model.

Stap 2: Een model implementeren

Gebruik de Microsoft Foundry-extensie in VS Code om een model te implementeren in Foundry.

1. Open het opdrachtpalet (Ctrl+Shift+P) en selecteer Microsoft Foundry: Open Model Catalog.

2. Blader door de modelcatalogus of zoek naar gpt-4.1 en selecteer de knop Implementeren .

3. Selecteer op de pagina Modelimplementatie de knop Deploy naar Microsoft Foundry.

Zodra het model is geïmplementeerd, gaat u verder met de volgende stap en maakt u een gehost agentproject

Stap 3: Een gehost agentproject maken

Gebruik de extensie Microsoft Foundry in VS Code om een nieuw gehost agentproject te maken.

1. Open het opdrachtpalet (Ctrl+Shift+P) en selecteer Microsoft Foundry: Nieuwe gehoste agent maken.

2. Selecteer de werkstroomsjabloon voor één agent of een werkstroom voor meerdere agents

3. Selecteer een programmeertaal, Python of C#.

4. Kies het bestaande gpt-4.1-model dat u in de vorige stap hebt geïmplementeerd.

5. Kies de map waarin u de projectbestanden wilt opslaan.

6. Voer een naam in voor de gehoste agent.

Er wordt een nieuw VS Code-venster geopend met de nieuwe agentprojectmap als de actieve werkruimte.

Stap 4: Afhankelijkheden installeren

Het is raadzaam om een virtuele omgeving te gebruiken om projectafhankelijkheden te isoleren:

macOS/Linux:

python -m venv .venv
source .venv/bin/activate

Windows (PowerShell):

python -m venv .venv
.\.venv\Scripts\Activate.ps1

Afhankelijkheden installeren

Installeer de vereiste Python afhankelijkheden met behulp van pip:

pip install -r requirements.txt

De vereiste pakketten zijn:

• azure-ai-agentserver-agentframework - Agent Framework en AgentServer SDK

Stap 5: de agent lokaal testen

Voer uw agent uit en test deze voordat u implementeert.

Optie 1: druk op F5 (aanbevolen)

Druk op F5 in VS Code om foutopsporing te starten. U kunt ook het menu voor foutopsporing in VS Code gebruiken:

1. Open de weergave Uitvoeren en foutopsporing (Ctrl+Shift+D/Cmd+Shift+D)
2. Selecteer 'Debug Local Workflow HTTP Server' in de vervolgkeuzelijst
3. Klik op de groene knop Foutopsporing starten (of druk op F5)

Dit doet het volgende:

1. De HTTP-server starten waarvoor foutopsporing is ingeschakeld
2. Open de Foundry Toolkit Agent Inspector voor interactieve tests
3. Hiermee kunt u onderbrekingspunten instellen en de werkstroom inspecteren

Optie 2: Uitvoeren in Terminal

Uitvoeren als HTTP-server (standaard):

python main.py

Hiermee wordt de gehoste agent lokaal gestart op http://localhost:8088/.

PowerShell (Windows):

$body = @{
   input = "I need a hotel in Seattle from 2025-03-15 to 2025-03-18, budget under `$200 per night"
    stream = $false
} | ConvertTo-Json

Invoke-RestMethod -Uri http://localhost:8088/responses -Method Post -Body $body -ContentType "application/json"

Bash/curl (Linux/macOS):

curl -sS -H "Content-Type: application/json" -X POST http://localhost:8088/responses \
   -d '{"input": "Find me hotels in Seattle for March 20-23, 2025 under $200 per night","stream":false}'

De agent gebruikt het get_available_hotels hulpprogramma om te zoeken naar beschikbare hotels die voldoen aan uw criteria.

Stap 6: Implementeren in Foundry Agent Service

Implementeer uw agent rechtstreeks vanuit VS Code.

1. Open het opdrachtpalet (Ctrl+Shift+P) en selecteer Microsoft Foundry: Hosted Agent implementeren.

2. Selecteer de CPU- en geheugenconfiguratie voor de gehoste agentcontainer.

3. Selecteer in het dialoogvenster dat wordt weergegeven de knop Bevestigen en Implementeren.

Ga naar de Microsoft Foundry Explorer door het pictogram aan de linkerkant te selecteren. De agent wordt weergegeven in de zijbalk van de structuurweergave gehoste agents (preview) nadat de implementatie is voltooid.

Agentstatus controleren

Controleer de status van uw agent om te bevestigen dat deze actief is.

1. Selecteer uw gehoste agent in de boomstructuur Gehoste Agents (Preview).

2. Selecteer een versie (v1) om de detailpagina te openen.

Op de detailpagina ziet u de status onder de sectie Containerdetails.

Testen in de speeltuin met behulp van VS Code

Microsoft Foundry voor VS Code bevat een geïntegreerde speeltuin om te chatten en te communiceren met uw agent.

1. Selecteer uw gehoste agent in de boomstructuur Gehoste Agents (Preview).

2. Selecteer een versie (v1) om de detailpagina te openen.

3. Selecteer de optie Playground en typ een bericht en verzend om uw agent te testen.

Agentstatus controleren

Controleer de status van uw gedeployeerde agent:

azd ai agent show

De geïmplementeerde agent testen

Een testbericht verzenden naar uw gedeployeerde agent.

azd ai agent invoke "What is Microsoft Foundry?"

De verwachting is dat u een antwoord met webzoekresultaten over Microsoft Foundry zult zien. Het antwoord kan enkele seconden duren wanneer de agent externe bronnen opvraagt.

Agentlogboeken weergeven

De livelogboeken van uw agent bewaken:

azd ai agent monitor

Als u een voorbeeld wilt bekijken van wat wordt verwijderd voordat u dit bevestigt:

azd down --preview

Wanneer u klaar bent om te verwijderen, voert u het volgende uit:

azd down

Het opschonen duurt ongeveer 2-5 minuten.

Als u uw resources wilt verwijderen, opent u de Azure-portal, gaat u naar de resourcegroep en verwijdert u deze samen met alle ingesloten resources.

De containerlogboeken van uw agent weergeven

U kunt de console- en systeemlogboeken van de container controleren om problemen op te lossen.

1. Selecteer uw gehoste agent in de boomstructuur Gehoste Agents (Preview).

2. Selecteer een versie (v1) om de detailpagina te openen.

3. Selecteer de knop Logboeken aan de rechterkant om de logboekviewer te openen.