Snabbstart: Distribuera din första värdbaserade agent

• Azure Developer CLI version 1.24.0 eller senare

• Visual Studio Code
• Microsoft Foundry Toolkit för Visual Studio Code-tillägget

Nödvändig behörighet

Du behöver Azure AI Project Manager vid projektets omfattning för att skapa och distribuera hostade agenter. Den här rollen omfattar både behörigheterna för dataplanet för att skapa agenter och möjligheten att tilldela Azure AI-användarrollen till den plattformsskapade agentidentiteten. Agentidentiteten behöver Azure AI-användare i projektet för att få åtkomst till modeller och artefakter vid körning.

Om du använder azd- eller VS Code-tillägget hanterar verktygen de flesta RBAC-tilldelningar automatiskt, inklusive:

Kontrollera att Foundry Projects hanterade identitet har ACR-pullrollen på den Azure Container Registry som du använder. Om du föredrar, och har åtkomst som Ägare eller "Användaråtkomstadministratör", kan verktygen azd/vscode utföra denna tilldelning åt dig. Azure AI-användare för agentidentiteten skapad av plattformen (körningsmodell och åtkomst till verktyg)

Steg 1: Konfigurera exempelprojektet

Installera cli-agenttillägget Azure Developer och initiera ett nytt värdbaserat agentprojekt.

1. Installera ai agent-tillägget för Azure Developer CLI:

   azd ext install azure.ai.agents
   

   Kontrollera att tillägget är installerat genom att köra:

   azd ext list
   

2. Initiera ett nytt värdbaserat agentprojekt i en tom katalog:

   azd ai agent init
   

   Det interaktiva flödet vägleder dig genom följande konfiguration:

   • Language – Välj vilket programmeringsspråk du vill ha exempelkod för, antingen C# eller Python.
   • Agentmall – Välj ett exempel att börja med.
   • Model Configuration – Välj om du vill distribuera en ny modell i Foundry eller använda en befintlig från en befintlig Foundry-Project.
   • Azure prenumeration – välj den prenumeration där du vill att Foundry-resurserna ska skapas.
   • Plats – välj en region för resurserna.
   • Modell-SKU – välj den SKU som är tillgänglig för din region och prenumeration.
   • Distributionsnamn – ange ett namn för modelldistributionen.
   • Containerstorlek – välj processor- och minnesallokering eller acceptera standardinställningarna.

   Viktigt

   Om du har valt ett exempel med verktyg och inte använder en MCP-server kan du kommentera ut eller ta bort följande rader i agent.yaml filen:

   - name: AZURE_AI_PROJECT_TOOL_CONNECTION_ID
     value: <CONNECTION_ID_PLACEHOLDER>
   

   Tips

   Om du kör i en icke-interaktiv miljö, till exempel en CI/CD-pipeline eller en SSH-session, använder du --no-prompt flaggan med azd ai agent init. Du måste också ange alla nödvändiga värden som kommandoradsflaggor i stället för att svara på interaktiva frågor.

3. Etablera nödvändiga Azure resurser:

   Observera

   Du behöver Contributor åtkomst på din Azure-prenumeration för resursprovisionering.

   azd provision
   

   Det här kommandot tar några minuter och skapar följande resurser:

   Resurs	Syfte	Kostnad
   Resursgrupp	Ordnar alla relaterade resurser i samma område	Ingen kostnad
   Modellimplementering	Modell som används av agenten	Se Foundry-priser
   Foundry-projekt	Är värd för din agent och tillhandahåller AI-funktioner	Förbrukningsbaserad; se Foundry-priser
   Azure Container Registry	Lagrar dina agentcontaineravbildningar	Basic-nivå; se priser för ACR
   Log Analytics arbetsyta	Hantera alla loggdata på ett ställe	Ingen direkt kostnad. Se kostnader för Log Analytics
   Application Insights	Övervakar agentens prestanda och loggar	Betala per användning; se prissättningen för Azure Monitor
   Hanterad identitet	Autentiserar din agent till Azure tjänster	Ingen kostnad

   Tips

   Kör azd down när du är klar med den här snabbstarten för att ta bort resurser och sluta debiteras.

Steg 2: Testa agenten lokalt

Kontrollera att agenten fungerar lokalt innan du distribuerar den.

1. Starta agenten lokalt:

   azd ai agent run
   

   Det här kommandot konfigurerar automatiskt miljön, installerar beroenden och startar agenten. Den använder startupCommand som definieras i azure.yaml för att starta din agent.

   Observera

   Förhandsversionspaket kan orsaka varningar om versionskonflikter av pip-beroenden under installationen. Dessa varningar är icke-blockerande – agenten startar och svarar korrekt trots dem.

   Om agenten inte startar kontrollerar du följande vanliga problem:

   Fel	Lösning
   AuthenticationError eller DefaultAzureCredential fel	Kör azd auth logout och uppdatera sedan azd auth login sessionen.
   ResourceNotFound	Kontrollera att slutpunkts-URL:erna matchar värdena i Foundry-portalen.
   DeploymentNotFound	Kontrollera distributionsnamnet i Build>Deployments.
   Connection refused	Se till att ingen annan process använder port 8088.

2. Skicka ett testmeddelande till den lokala agenten i en separat terminal.

   För agenter som använder svars-API:et kan du skicka en sträng som nyttolast:

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

   För agenter som använder API:et för anrop kontrollerar du den README.md förväntade nyttolasten. Exemplen kräver vanligtvis en JSON-nyttolast, men granska vad som finns i README.md exemplet för ett specifikt exempel:

   Du bör se ett svar från agenten.

Steg 3: Distribuera till Foundry Agent Service

Eftersom du redan har etablerat infrastrukturen i steg 1 distribuerar du agentkoden till Azure:

azd deploy

Agentcontainern skapas via fjärranslutning, så Docker Desktop krävs inte på datorn.

När du är klar visar resultatet en länk till Agent Playground och slutpunkt för att anropa agenten programmatiskt.

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

Steg 1: Skapa ett Foundry-projekt

Använd tillägget Microsoft Foundry Toolkit i VS Code för att skapa en ny Microsoft Foundry Project resurs.

1. Öppna kommandopaletten (Ctrl+Skift+P) och välj Microsoft Foundry: Create Project.

2. Välj din Azure prenumeration.

3. Skapa en ny resursgrupp eller välj en befintlig.

4. Ange ett namn för resursen Foundry Project.

När projektet har skapats fortsätter du till nästa steg och distribuerar en modell.

Steg 2: Distribuera en modell

Använd tillägget Microsoft Foundry Toolkit i VS Code för att distribuera en modell till Foundry.

1. Öppna kommandopaletten (Ctrl+Skift+P) och välj Microsoft Foundry: Open Model Catalog.

2. Bläddra i modellkatalogen eller sök efter gpt-4.1 och välj knappen Distribuera .

3. På sidan Modelldistribution väljer du knappen Deploy till Microsoft Foundry.

När modellen har distribuerats går du vidare till nästa steg och skapar ett värdbaserat agentprojekt

Steg 3: Skapa ett värdbaserat agentprojekt

Använd tillägget Microsoft Foundry Toolkit i VS Code för att skapa ett nytt värdbaserat agentprojekt.

1. Öppna kommandopaletten (Ctrl+Skift+P) och välj Microsoft Foundry: Create new Hosted Agent.

2. Välj det ramverk som du vill använda.

3. Välj ett programmeringsspråk, Python eller C#.

4. Välj antingen Svars-API eller Anropa API.

5. Välj den exempelkod som du vill använda.

6. Välj den mapp där du vill att dina projektfiler ska sparas.

7. Ange ett namn för den värdbaserade agenten.

Ett nytt VS Code-fönster startas med den nya agentprojektmappen som den aktiva arbetsytan.

Steg 4: Installera beroenden

Vi rekommenderar att du använder en virtuell miljö för att isolera projektberoenden:

macOS/Linux:

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

Windows (PowerShell):

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

Installera beroenden

Installera nödvändiga Python beroenden med pip:

pip install -r requirements.txt

En lista över nödvändiga paket finns i requirement.txt.

Steg 5: Testa agenten lokalt

Kör och testa din agent innan du distribuerar.

Alternativ 1: Tryck på F5 (rekommenderas)

Tryck på F5 i VS Code för att börja felsöka. Du kan också använda felsökningsmenyn för VS Code:

1. Öppna vyn Kör och felsök (Ctrl+Skift+D/Cmd+Skift+D)
2. Välj "Felsöka HTTP-server för lokalt arbetsflöde" i listrutan
3. Klicka på den gröna knappen Starta felsökning (eller tryck på F5)

Detta kommer att:

1. Starta HTTP-servern med felsökning aktiverat
2. Öppna Foundry Toolkit Agent Inspector för interaktiv testning
3. Gör att du kan ange brytpunkter och inspektera arbetsflödet

Alternativ 2: Kör i terminalen

Kör som HTTP-server (standard):

python main.py

Detta startar den värdbaserade agenten lokalt på 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}'

Agenten get_available_hotels använder verktyget för att söka efter tillgängliga hotell som matchar dina kriterier.

Steg 6: Distribuera till Foundry Agent Service

Distribuera din agent direkt från VS Code.

1. Öppna kommandopaletten (Ctrl+Skift+P) och välj Microsoft Foundry: Deploy Hosted Agent.

2. Välj "Standard-ACR"

3. Välj cpu- och minneskonfigurationen för hostad agent-container.

Växla till utforskaren Microsoft Foundry Toolkit genom att välja ikonen till vänster. Agenten visas i trädvy-sidofältet Hosted Agents (förhandsversion) när distributionen har slutförts.

Kontrollera agentstatus

Kontrollera statusen för din agent för att bekräfta att den körs.

1. Välj din värdbaserade agent i trädvyn Värdbaserade agenter (förhandsversion).

2. Välj den agent som du precis har distribuerat

På detaljsidan visas Status under avsnittet Containerinformation.

Testa på lekplatsen med VS Code

Microsoft Foundry Toolkit för VS Code innehåller en integrerad lekplats för att chatta och interagera med din agent.

1. Välj din värdbaserade agent i trädvyn Värdbaserade agenter (förhandsversion).

2. Välj alternativet Playground och skriv ett meddelande och skicka för att testa din agent.

Verifiera agentstatus

Kontrollera statusen för din distribuerade agent:

azd ai agent show

Så här visar du utdata i tabellformat:

azd ai agent show --output table

Om projektet har flera agenttjänster anger du agentnamnet som ett positionellt argument:

azd ai agent show <agent-name>

Testa den utplacerade agenten

Skicka ett testmeddelande till din distribuerade agent med samma invoke kommando som användes tidigare, men utan --local flaggan:

För agenter som använder svars-API:et kan du skicka en sträng som nyttolast:

azd ai agent invoke <payload>

Du bör se ett svar från agenten efter några sekunder.

Visa agentloggar

Övervaka agentens liveloggar:

# 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

Om projektet har flera agenttjänster anger du agentnamnet som ett positionellt argument:

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

Om du vill förhandsgranska vad som ska tas bort kör down du kommandot:

azd down

När du är klar azd visas alla resurser som ska tas bort och du uppmanas att bekräfta. Välj om du yes vill fortsätta eller no avbryta.

Rensningsprocessen tar cirka 2–5 minuter.

Om du vill ta bort dina resurser öppnar du Azure-portalen, navigerar till resursgruppen och tar bort den tillsammans med alla inneslutna resurser.

Visa containerloggarna för din agent

Du kan kontrollera containerns konsol- och systemloggar för att felsöka problem.

1. Välj din värdbaserade agent i trädvyn Värdbaserade agenter (förhandsversion).

2. Välj fliken "Playground" för din värdbaserade agent

3. Välj avsnittet "Loggar" i sessionsinformationen.

Visa sessionsfilerna för din agent

Du kan visa alla filer som lagras i hemkatalogen för din ADC-baserade agent

1. Välj din värdbaserade agent från trädvyn Värdbaserade agenter (förhandsversion).

2. Välj fliken "Playground" för din värdbaserade agent

3. Välj avsnittet "filer" i sessionsinformationen.

Du kan ladda ned, ladda upp och skapa mappar i den aktuella mappen. Om du klickar på en mapp kommer du att gå in i mappen, och om du klickar på det övre navigeringsfältet går du tillbaka till den mappen.