Köra en värdbaserad agent lokalt med cli:et Azure Developer

Använd azd ai agent run för att starta din Microsoft Foundry-värdbaserad agent på den lokala datorn och azd ai agent invoke --local för att testa den utan att distribuera den till Azure. Du får också lära dig hur du anger portar, väljer en agent i ett projekt med flera agenter, åsidosätter startkommandon och skickar lokala körningshemligheter.

Om du använder en kodningsagent som GitHub Copilot kan Microsoft Foundry Skill hjälpa dig att konfigurera lokala start-, portar, hemligheter och testkommandon innan du distribuerar.

Förutsättningar

  • Ett initierat värdbaserat agentprojekt. Information om hur du skapar ett finns i Initiera ett agentprojekt.
  • azd Foundry-tilläggen har installerats. Installationssteg finns i Installera azd Foundry-tilläggen.
  • En autentiserad CLI-session för Azure utvecklare. Kör azd auth login om det behövs.
  • Obligatoriska språkkörmiljöer för din agent, till exempel Python 3.10+, .NET 8+ eller Node.js.

Starta agenten

  • Starta agenten från projektkatalogen:

    azd ai agent run

    Det här kommandot identifierar automatiskt projekttypen (Python, .NET, Node.js), installerar beroenden och startar agentservern på localhost:8088. Startkommandot läses från egenskapen startupCommand i azure.yaml.

Tip

azd ai agent run matar automatiskt in miljövariabler från din standardmiljö azd, den som du anger med azd env select eller skapade under azd ai agent init. Det innebär att variabler som FOUNDRY_PROJECT_ENDPOINT, AZURE_SUBSCRIPTION_IDoch alla värden som du anger med azd env set är tillgängliga för din agent utan manuell konfiguration.

Se Konfigurera miljövariabler för en värdbaserad agent för den fullständiga listan.

Starta på en anpassad port

  • Skicka --port när standardporten inte är tillgänglig:

    azd ai agent run --port 9090

Starta en specifik agent

  • Om projektet definierar flera agenter anger du vilken som ska köras:

    azd ai agent run my-agent

Åsidosätt startkommandot

  • Skicka --start-command för att åsidosätta kommandot i azure.yaml:

    azd ai agent run --start-command "python app.py"

    Det här kommandot åsidosätter den startupCommand som definierats i din azure.yaml tjänstkonfiguration. startupCommand är standardkommandot som används både för lokal utveckling (azd ai agent run) och för containerstart när det distribueras. Mer information finns i azure.yaml-tjänstkonfiguration.

Skicka miljövariabler och hemligheter

En lokal körning läser env-mappningen som deklarerats i tjänsten azure.ai.agent i azure.yaml och ersätter eventuella platshållare av typen ${VAR} i den aktiva azd-miljön. Ange ett värde, till exempel en API-nyckel, genom att ange det som en azd miljövariabel och referera till det i azure.yaml.

  1. Ange värdet i den aktiva azd miljön:

    azd env set OPENAI_KEY <value>

    azd lagrar miljövärden i .azure/<env>/.env. Katalogen .azure är gitignored som standard, så dessa värden håller sig borta från källkontrollen.

  2. Referera till variabeln azure.ai.agent i tjänsten i azure.yaml så att den lokala körningen matar in den:

    services:
  my-agent:
    host: azure.ai.agent
    env:
      OPENAI_KEY: ${OPENAI_KEY}

För hemligheter som inte ska finnas i en lokal .env fil alls lagrar du dem i en Foundry-projektanslutning och refererar till dem med en ${{connections.<name>.credentials.<field>}} platshållare på env kartan. Plattformen löser platshållaren vid körning. Mer information finns i Konfigurera miljövariabler för en värdbaserad agent.

Testa med invoke

  • Öppna en separat terminal och skicka ett meddelande till din körande agent:

    azd ai agent invoke --local "Hello, what can you do?"

    Flaggan --local styr begäran till localhost:8088 i stället för den distribuerade slutpunkten.

Testa protokoll med invoke

Protokollet som agenten protocols använder definieras i fältet för azure.ai.agent tjänsten i azure.yaml. Om din agent implementerar protokollet responses skickar invoke en standardbegäran till Responses API. Om din agent använder invocations protokollet är nyttolasten vad agentkoden förväntar sig. Använd --input-file (-f) för att skicka en anpassad JSON-brödtext:

azd ai agent invoke --local -f request.json

För agenter av typen invocations finns information i exemplets README-fil, eller så kan du granska hanteraren eller ingångspunkten för att förstå den förväntade nyttolastens struktur.

Om din agent implementerar flera protokoll invoke använder du responses protokollet som standard. Skicka -p (--protocol) med responses eller invocations för att välja en explicit:

azd ai agent invoke --local --protocol invocations -f request.json

Testa med curl

  • Testa direkt med curl:

    curl -X POST http://localhost:8088/responses \
   -H "Content-Type: application/json" \
   -d '{"input": "Hello, what can you do?"}'

Felsök lokal utveckling

Problem Lösning
AuthenticationError Kör azd auth login för att uppdatera autentiseringsuppgifter.
ResourceNotFound Kontrollera att slutpunkts-URL:er matchar foundry-portalvärden.
DeploymentNotFound Kontrollera distributionsnamnet i .azure.yaml
Anslutning nekad på port 8088 Se till att ingen annan process använder porten.
Beroenden kan inte installeras Kontrollera att Python 3.10+ eller .NET 8+ är installerat.

Relaterat innehåll

  • Last updated on