Quickstart: Uw eerste gehoste agent implementeren

• Azure Developer CLI versie 1.24.0 of hoger

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

Vereiste machtiging

U hebt Azure AI Project Manager nodig op project bereik om gehoste agents te maken en te implementeren. Deze rol omvat zowel de machtigingen voor het gegevensvlak voor het maken van agents als de mogelijkheid om de Azure AI-gebruikersrol toe te wijzen aan de door het platform gemaakte agentidentiteit. De agentidentiteit heeft Azure AI-gebruiker in het project nodig om tijdens runtime toegang te krijgen tot modellen en artefacten.

Als u azd of de VS Code-extensie gebruikt, verwerkt de tooling automatisch de meeste RBAC-toewijzingen, waaronder:

Zorg ervoor dat de beheerde identiteit van het Foundry Project de ACR pull-rol heeft op de Azure Container Registry die u gebruikt. Als u de voorkeur heeft en eigenaarstoegang of 'Beheerder voor gebruikers toegang' hebt, kan de tool azd/vscode deze toewijzing ook voor u uitvoeren. Azure AI-gebruiker voor de door het platform gemaakte agentidentiteit (runtimemodel en toegang tot hulpprogramma's)

Stap 1: Het voorbeeldproject 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 gehost agentproject in een lege map:

   azd ai agent init
   

   De interactieve stroom begeleidt u bij de volgende configuratie:

   • Language — Selecteer de programmeertaal waarvoor u voorbeeldcode wilt gebruiken, C# of Python.
   • Agentsjabloon : selecteer een voorbeeld om mee te beginnen.
   • Modelconfiguratie : selecteer deze optie om een nieuw model te implementeren in Foundry of gebruik een bestaand model uit een bestaande Foundry-Project.
   • 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.

   Belangrijk

   Als u een voorbeeld met hulpprogramma's hebt geselecteerd en u geen MCP-server gebruikt, voert u de volgende regels in het agent.yaml bestand uit commentaar of verwijdert u deze.

   - name: AZURE_AI_PROJECT_TOOL_CONNECTION_ID
     value: <CONNECTION_ID_PLACEHOLDER>
   

   Tip

   Als u in een niet-interactieve omgeving werkt, zoals een CI/CD-pijplijn of een SSH-sessie, gebruikt u de --no-prompt vlag met azd ai agent init. U moet ook alle vereiste waarden opgeven als opdrachtregelvlagmen in plaats van te reageren op interactieve prompts.

3. Richt de vereiste Azure-middelen in.

   Opmerking

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

   azd provision
   

   Deze opdracht duurt enkele minuten en maakt de volgende resources:

   Bron	Purpose	Kosten
   Resourcegroep	Hiermee worden alle gerelateerde resources in hetzelfde gebied ingedeeld	Geen kosten
   Modelimplementatie	Model dat door de agent wordt gebruikt	Bekijk Foundry-prijzen
   Gieterijproject	Host uw agent en biedt AI-mogelijkheden	Op basis van verbruik; zie Foundry-prijzen
   Azure Container Registry	Slaat de containerbeelden 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
   Application Insights	Bewaakt de prestaties en logboeken van de agent	Betaal naar gebruik; zie prijsoverzicht van Azure Monitor
   Beheerde identiteit	Verifieert uw agent voor Azure services	Geen kosten

   Tip

   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.

   Opmerking

   Preview-pakketten kunnen pip-afhankelijkheidsconflictwaarschuwingen produceren tijdens de installatie. Deze waarschuwingen worden niet geblokkeerd. De agent wordt gestart en reageert correct ondanks deze waarschuwingen.

   Als de agent niet start, controleer deze veelvoorkomende problemen:

   Fout	Oplossing
   AuthenticationError of DefaultAzureCredential fout	Voer azd auth logout uit en voer daarna azd auth login uit om je 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.

   Voor agents die de Responses-API gebruiken, kunt u een tekenreeks verzenden als payload:

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

   Voor agents die gebruikmaken van de API voor aanroepen, controleert u de verwachte payload in README.md. Voor de voorbeelden is doorgaans een JSON-payload vereist, maar bekijk de inhoud van README.md voor een specifiek voorbeeld daarvan.

   U zou een antwoord van de agent 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 extensie Microsoft Foundry Toolkit 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 extensie Microsoft Foundry Toolkit 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 Toolkit 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 het framework dat u wilt gebruiken.

3. Selecteer een programmeertaal, Python of C#.

4. Selecteer de antwoorden-API of de API aanroepen.

5. Selecteer de voorbeeldcode die u wilt gebruiken.

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

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

Zie de requirement.txt voor een lijst met vereiste pakketten.

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 Standaard-ACR

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

Schakel over naar de Microsoft Foundry Toolkit 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 structuurweergave Gehoste agents (Preview).

2. Selecteer de agent die u zojuist hebt geïmplementeerd

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

Testen in de speeltuin met behulp van VS Code

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

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

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

Agentstatus controleren

Controleer de status van je gedeployeerde agent:

azd ai agent show

De uitvoer weergeven in tabelindeling:

azd ai agent show --output table

Als uw project meerdere agentservices heeft, geeft u de naam van de agent op als een positioneel argument:

azd ai agent show <agent-name>

De geplaatste agent testen

Verzend een testbericht naar uw geïmplementeerde agent met dezelfde invoke opdracht die u eerder hebt gebruikt, maar zonder de --local vlag:

Voor agenten die de Antwoorden-API gebruiken, kunt u een tekenreeks als payload verzenden.

azd ai agent invoke <payload>

U ziet na enkele seconden een reactie van de agent.

Agentlogboeken weergeven

De livelogboeken van uw agent bewaken:

# Fetch recent container console logs
azd ai agent monitor

# Fetch the last N lines of console logs
azd ai agent monitor --tail 20

# Fetch system event logs (container start and stop events)
azd ai agent monitor --type system

# Stream session logs in real time
azd ai agent monitor --session <session-id> --follow

Als uw project meerdere agentservices heeft, geeft u de naam van de agent op als een positioneel argument:

azd ai agent monitor <agent-name> --follow

Voer de opdracht uit om een down voorbeeld te bekijken van wat er wordt verwijderd:

azd down

Als u klaar bent, azd ziet u alle resources die worden verwijderd en wordt u gevraagd om te bevestigen. Selecteer yes deze optie om door te gaan of no om te annuleren.

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 het tabblad 'Speeltuin' van uw gehoste agent

3. Selecteer de sectie Logboeken in de sessiedetails.

De sessiebestanden van uw agent weergeven

U kunt alle bestanden weergeven die zijn opgeslagen in de basismap van uw ADC-agent

1. Selecteer uw gehoste agent in de structuurweergave Gehoste agents (preview).

2. Selecteer het tabblad 'Speeltuin' van uw gehoste agent

3. Selecteer het gedeelte "Bestanden" in de sessiedetails.

U kunt mappen in de huidige map downloaden, uploaden en maken, door op een map te klikken, stapt u in de map en klikt u op de bovenste navigatiebalk terug naar die map.