Skapa värdbaserade agenter med Microsoft Foundry Toolkit för Visual Studio Code

Använd Microsoft Foundry Toolkit för Visual Studio Code för att skapa ett kodbaserat arbetsflöde från ett Microsoft Agent Framework-exempel. Kör den lokalt med Agent Inspector och distribuera sedan källkoden till Foundry Agent Service som en värdbaserad agent. Du underhåller koden och dess beroenden. Foundry hanterar värdinfrastrukturen och skalningen.

Hostade arbetsflöden samordnar agenter i kod. De skiljer sig från Foundrys utgående deklarativa arbetsflödestjänst. Andra skapandevägar finns i Skapa en agent.

Förutsättningar

  • Installera Microsoft Foundry Toolkit för Visual Studio Code.

  • Välj ett Foundry-projekt med en distribuerad modell. Använd en region för värdbaserad agent som stöds.

  • Behörighet att använda modellen och distribuera värdbaserade agenter. För distribution av källkod inkluderar rollen Foundry Project Manager på projektnivå åtgärder för agenter och behörighet att tilldela roller. Se Behörigheter för värdbaserad agent.

    Important

    Foundrys RBAC-roller har nyligen namnändrats. Foundry User, Foundry Owner, Foundry Account Owner och Foundry Project Manager hette tidigare Azure AI-användare, Azure AI-ägare, Azure AI-kontoägare och Azure AI Project Manager. Du kanske fortfarande ser de tidigare namnen på vissa platser medan namnbytet distribueras. Roll-ID:na och kärnbehörigheterna ändras inte av namnbytet.

  • Azure CLI för stegen för lokal autentisering i den här artikeln.

  • För distribution av containrar krävs den åtkomst till registret och avbildningen som konfigurationen av Azure Container Registry kräver. Dessa registerkrav gäller inte för en källkodsdistribution.

  • Python 3.13 för exemplets konfigurerade värdbaserade körning.
  • Python-tillägget för Visual Studio Code.

Huvuddistributionssökvägen använder Kod med fjärrpaketläge och kräver ingen lokal Docker-version. Lokal körning skickar fortfarande modellförfrågningar till Foundry och kan medföra avgifter. Granska tjänstbegränsningarna och tillgängligheten och viktig information om Toolkit för de funktioner som du använder.

Skapa ett arbetsflöde för värdbaserad agent

Välj ett Agent Framework-exempel som använder protokollet Svar. Du behöver inte skapa en separat promptagent först. Om du vill jämföra exempel, Agent Builder och kodning med Copilot, se Välj ett sätt att skapa.

Använd Multi-Agent Workflow (Agent Framework) som kedjar en skrivare, en granskare och en formaterare. Det slutliga svaret kommer från formateren. Granska det Python arbetsflödesexemplet för den fullständiga implementeringen och dess modellvägledning.

Använd Translation Workflow, som kedjar tre översättningsagenter: engelska till franska, franska till spanska och spanska till engelska. Granska C#-arbetsflödesexemplet för den fullständiga implementeringen.

  1. I vyn Foundry Toolkit väljer du Utvecklarverktyg>Skapa>agent.

  2. Under Koda en agent från exempel väljer du Bläddra bland alla exempel.

  3. I Skapa värdbaserad agent från exempel filtrerar du efter språk, ramverk = och protokolltyp = svar. Sök efter workflow.

    Följande skärmbild visar galleriet med Basic Hosted Agent valt som exempel. I den här guiden väljer du arbetsflödesexemplet för ditt språk i stället.

    Skärmbild av exempelgalleriet hosted-agent med Basic Hosted Agent valt, arbetsflödesexempel och språk, ramverk och protokollfilter.

  4. Välj arbetsflödesexemplet för ditt språk.

  5. Klicka på Nästa.

  6. Välj mappen Arbetsyta i Skapa. Om mappen redan innehåller filer anger du ett mappnamn för en ny underordnad mapp.

  7. Om miljökonfigurationen visas väljer du Installation med Microsoft Foundry och väljer sedan din prenumeration och ditt projekt. När ett standardprojekt redan har valts använder formuläret det projektet.

  8. Välj en befintlig kompatibel modelldistribution.

    Följande skärmbild visar exempel på projektinställningar med dolda lokala sökvägar. Använd ditt eget mål och den modelldistribution som exemplet kräver.

    Skärmbild av fliken Skapa som visar arbetsytemapp, mappnamn, modelldistribution och Skapa kontroller med dolda lokala sökvägar.

  9. Granska målet och välj sedan Skapa.

  10. Öppna det genererade projektet i Visual Studio Code och läs dess README.md.

Panelerna Agent Framework, Copilot SDK och LangGraph på Skapa agent öppnar fliken Skapa med en Hello World-startmall vald. Använd Bläddra bland alla mallar för att välja ett arbetsflöde i stället för en av dessa startmallar. Du kan också öppna galleriet från Minaresursagenter>>Värdbaserad agent>Lägg till värdbaserad agent.

Exempelnamn och innehåll kan ändras med katalogen. Vissa versioner etiketterar dessa exempel arbetsflöden. Använd exemplets GitHub länk för att bekräfta att du har valt det avsedda arbetsflödet.

Hoppa över för tillfället genererar koden utan att slutföra modellkonfigurationen. Om du väljer det konfigurerar du nödvändiga projekt- och modellvärden innan du kör exemplet. Distribuera och använd ny modell, när den erbjuds, etablerar en modelldistribution, inte den värdbaserade agenten. När du skapar de lokala projektfilerna distribueras inte agenten.

Konfigurera det lokala projektet

Behåll mappen som innehåller azure.yaml öppen som arbetsytans rot. Kontrollera sökvägen till den värdbaserade agenttjänsten project i filen för att hitta dess källkatalog.

Artifact Purpose
azure.yaml Deklarerar värdbaserad agenttjänst, källkatalog, körning, protokoll och distributionsinställningar.
main.py eller Program.cs i källkatalogen Implementerar arbetsflödet och startar svarsservern.
requirements.txt eller .csproj-filen Deklarerar beroenden för det valda språket.
.env i källkatalogen Innehåller lokala projekt- och modellvärden. Toolkit skapar den från .env.example när exemplet tillhandahåller filen.
.vscode/launch.json och .vscode/tasks.json Konfigurera den lokala servern, den bifogade felsökningsbilagan och agentkontrollanten.

Exempellayouter kan ändras. Använd den genererade README.md och azure.yaml i stället för att anta att koden och miljöfilen finns i arbetsytans rot.

Installera beroenden

Använd det genererade exemplets beroendefiler. Håll den valda tolken eller SDK:t konsekvent med dess körningskonfiguration.

  1. Kör Python: Skapa miljö... från kommandopaletten för att skapa en virtuell miljö eller Python: Välj Tolk för att välja en befintlig Python 3.13-miljö. Information om miljökonfiguration och val finns i Python miljöer i Visual Studio Code.

  2. Öppna en terminal med den miljön aktiv. Ändra till källkatalogen som innehåller main.py och requirements.txt.

  3. Installera exempelpaketen:

    python -m pip install -r requirements.txt

    Kraven omfattar debugpy, som den genererade F5-konfigurationen använder. Referens: Python arbetsflödesberoenden.

  1. Kör C#: Kontrollera arbetsytans krav från kommandopaletten.

  2. I en terminal ändrar du till källkatalogen .csproj som innehåller filen och återställer dess paket:

    dotnet restore

    Referens: dotnet restore.

Information om felsökningskontroller och konfiguration finns i C#-felsökning i Visual Studio Code.

Ange projektet och modellen

.env Granska filen i källkatalogen. Om den inte finns skapar du den med de värden som krävs av exemplet.

Variabel Value
FOUNDRY_PROJECT_ENDPOINT Ditt projekts slutpunkt, i formen https://<resource-name>.services.ai.azure.com/api/projects/<project-name>.
AZURE_AI_MODEL_DEPLOYMENT_NAME Namnet på modelldistributionen i projektet, inte bara modellens katalognamn.

Båda arbetsflödesexemplen läser in .env vid start. Projektslutpunkten är inte en Azure OpenAI-kontoslutpunkt. Håll filen borta från källkontrollen och placera inte autentiseringsuppgifterna i programkoden.

Autentisera lokalt

Exemplen använder DefaultAzureCredential. För Azure CLI-autentisering loggar du in med ett konto som kan få åtkomst till projektets modell:

az login

Referens: Logga in med Azure CLI.

Toolkit-inloggningen väljer projektet för tilläggsåtgärder. Den lokala agentprocessen kräver också en autentiseringsuppgift som stöds. Andra alternativ finns i StandardAzureCredential för Python- eller autentiseringskedjor för .NET.

Kör ditt värdbaserade arbetsflöde lokalt

Använd den genererade felsökningskonfigurationen för att starta HTTP-servern och öppna Agent Inspector. Att öppna Agent Inspector i sig startar inte servern.

Använd den här testbegäran: Create a slogan for a new electric SUV that is affordable and fun to drive. Arbetsflödet returnerar en formaterad slogan efter att författaren, granskaren och formatteraren har slutfört sina steg.

Använd den här testbegäran: The quick brown fox jumps over the lazy dog. Arbetsflödet kör sin översättningskedja och returnerar ett svar.

  1. Gå tillbaka till den genererade projektarbetsytan.
  2. Sätt en brytpunkt i koden för arbetsflödet om du vill granska körningen.
  3. Tryck på F5. Om du uppmanas till det väljer du Felsöka HTTP-server för lokal agent.
  4. Vänta tills servern startas och agentkontrollanten öppnas.
  5. Skicka testbegäran för ditt exempel.
  6. Inspektera svaret och upprepa med en annan begäran. Om du anger en brytpunkt kontrollerar du värdena och fortsätter körningen.

När exemplet har fungerat ändrar du arbetsflödet och upprepar det lokala testet. Om du lägger till verktyg skickar du en begäran som kräver ett verkligt verktygsresultat och inspekterar anropet. Ett svar med endast modell eller ett hånfullt svar bevisar inte att live-verktyget fungerar.

Skärmbilden visar en verktygsaktiverad lokal agent, inte något av arbetsflödesexemplet. Agent Inspector visar sina svar och verktygsanrop i ett svarstidsvattenfall och en körningstidslinje. Tillgänglig inspektionsinformation beror på den agent som körs och dess instrumentering.

Skärmbild av Agent Inspector ansluten till localhost på port 8088 med Responses-protokollet, verktygsanrop, ett latensvattenfall och en tidslinje för körningen.

Om du använder GitHub Copilot kan du köra /validate-microsoft-foundry-hosted-agent i Copilot Chat för att granska projektet mot Foundrys metodtips. Det här chattkommandot öppnar en rapport. Det är inte ett terminalkommando eller en ersättning för att köra arbetsflödet.

De genererade uppgifterna använder port 8088 för agentservern. Python felsökning använder också port 5679. Om uppstarten rapporterar en portkonflikt stoppar du den process som orsakar konflikten och som du äger, eller justerar den genererade uppgiftskonfigurationen konsekvent.

Kör utan felsökningsprogrammet

Om du vill köra manuellt öppnar du en terminal i exemplets källkatalog med dess beroenden, miljövärden och Azure tillgängliga autentiseringsuppgifter.

python main.py

Referens: Python startpunkt för arbetsflödet.

Ange HTTP-adressen för den lokala servern och kör den sedan:

$env:ASPNETCORE_URLS = "http://localhost:8088"
dotnet run

Referens: server-URL:er i ASP.NET Core och dotnet run.

Kör sedan Foundry Toolkit: Öppna Agent Inspector från kommandopaletten och anslut till den lokala servern på porten 8088. Kör ett exempel med python eller dotnet run startar en lokal process, inte en container.

Visualisera körning av värdbaserade agentarbetsflöden

Använd Agent Inspector för att granska de händelser, svar och verktygsanrop som agenten som körs genererar. När körmiljön skickar arbetsflödeshändelser använder du arbetsflödesvisualiseringen för att granska stegsekvensen.

Den tillgängliga informationen beror på exemplets instrumentation. Följ exemplets anvisningar för telemetrikonfiguration för körningsspecifika krav.

De här stegen använder protokollet Svar. Andra exempel kräver klienter som matchar deras protokoll: vyn för HTTP-anrop är inte en WebSocket-klient, och aktivitetsexempel i Python använder Microsoft 365 Agents Playground. Följ de valda exemplens lokala testinstruktioner. Om du ändrar ett protokollnamn i konfigurationen läggs inte det protokollet till på servern. Se Välj ett protokoll för värdbaserad agent.

Distribuera den värdbaserade agenten

När det lokala arbetsflödet fungerar som förväntat distribuerar du det från projektarbetsytan. Python och C# delar distributionsproceduren. Börja med kod- och fjärrpaketläget för att ladda upp källan och låt Foundry återställa beroenden.

Förbereda distributionskonfiguration

Granska och spara tjänsten hosted-agent i azure.yaml. Bevara exemplets protokollkonfiguration och deklarera modelldistributionen och andra nödvändiga körningsinställningar där.

Distributionen löser deklarerade miljövärden från källkatalogens .env eller processmiljön. Alla lokala .env inmatningar vidarebefordras inte. Plattformen tillhandahåller reserverade körningsvärden, till exempel FOUNDRY_PROJECT_ENDPOINT. Omdeklara dem inte som distributionsinställningar. Se Plattformsinmatade miljövariabler.

Granska källkatalogens ignorera regler innan du paketerar. Håll .env, autentiseringsuppgifter, virtuella miljöer och cacheminnen borta från paketet. För ZIP-distribution ersätter en källrot .agentignore reglerna i .gitignore och .dockerignore, så behåll de undantag som krävs om du lägger till filen.

Important

Lägg inte in eller paketera hemliga uppgifter. Lokal inloggning överför inte användarens behörigheter till den distribuerade agenten. Konfigurera åtkomst för agentens körningsidentitet och anslutningar som stöds. Se Behörigheter för värdbaserad agent.

Distribuera källa med fjärrpaketläge

Använd roten för den genererade arbetsytan så att Toolkit kan läsa tjänstkonfigurationen och leta upp dess källkatalog.

  1. Stoppa den lokala felsökningssessionen.

  2. Välj Utvecklarverktyg>Bygg>Distribuera till Microsoft Foundry. Du kan också köra Foundry Toolkit: Deploy Hosted Agent (Distribuera värdbaserad agent ) från kommandopaletten.

    Skärmbild av Distribuera till Microsoft Foundry under Skapa i avsnittet Foundry Toolkit Developer Tools.

  3. Om Foundry Project installationsprogrammet visas väljer du prenumerationen och project och väljer sedan Nästa. Annars kontrollerar du att standardprojektet är det avsedda målet.

  4. I Grunderna väljer du Kod som distributionsmetod och Fjärr som paketläge.

  5. Välj Ny agent och ange namnet på den värdbaserade agenten. Om du vill uppdatera en distribuerad agent väljer du Befintlig agent och väljer den agenten i stället.

    Skärmbild av Grundläggande med koddistribution, fjärrpaketläge och Ny agent markerad, med agentnamnet dolt.

  6. Klicka på Nästa.

  7. I Granska + distribuera kontrollerar du Language, Runtime Version, Entry Point och CPU och Memory mot exemplet. Bekräfta att källkatalogen matchar tjänstens project sökväg.

    Följande skärmbild visar ett exempel med Python 3.14 och dess startpunkt dold, inte inställningarna för dessa arbetsflödesexempel. För Python använder du Python 3.13 med python3 main.py. För C#använder du .NET 10 och den identifierade startpunkten för ditt genererade projekt.

    Skärmbild av Granska + distribuera som visar Python 3.14 som exempel, en dold startpunkt, CPU och minne och distribuera kontroller.

  8. Välj Distribuera. Följ förlopp i meddelanden och Utdata.

  9. Fortsätt att testa det distribuerade arbetsflödet.

Anpassa körmiljön till exempelkonfigurationen och den lokala miljön. Acceptera inte en annan körmiljö bara för att det är standardvalet i guiden.

Toolkit sparar distributionsalternativ när du skickar formuläret. De lokala inställningarna bevisar inte att molndistributionen lyckades. Om du uppdaterar en befintlig agent skapas en ny version i stället för att en tidigare version ändras på plats.

Välj ett annat ZIP-paketläge

Toolkit erbjuder följande paketeringsalternativ för källkod:

Paketläge Vad som händer Vad du ska förbereda
Fjärr Källan för Toolkit-paket. Foundry återställer Python krav eller .NET projektet under etableringen. Källa, beroendedeklarationer och en kompatibel startpunkt.
Paket Toolkit förbereder källan och kör Package Command lokalt innan ZIP-filen skapas. Foundry kör det förberedda paketet. Kompatibla Linux-beroenden och de lokala verktyg som krävs av kommandot. Standardkommandot Python installerar kompatibla beroenden i packages/. Kommandot .NET skapar publiceringsutdata.

De valbara ZIP-runtimerna är Python 3.13, Python 3.14 och .NET 10. Anpassa körmiljön till din kod och dina beroenden. Layouter, begränsningar och tjänstkrav finns i Distribuera från källkod. Information om principen för stöd för körningsmiljöer finns i Körningsmiljöer som stöds för värdagenter.

Distribuera en containeravbildning

Välj Container på Basics när du behöver en anpassad körningsavbildning eller redan har en kompatibel avbildning.

Val av register Verktygsuppsättningens beteende
Standard-ACR Skapar eller återanvänder ett register för det valda projektet och skapar och push-överför sedan avbildningen via Azure Container Registry (ACR).
Anpassad ACR Använder ett befintligt register som du väljer och skapar och push-överför sedan avbildningen via ACR.
Anpassad ACR-avbildning Använder en fördefinierad ACR-avbildningsreferens utan att skapa eller push-överföra källan.

För byggalternativen granskar du Dockerfile- och byggkontexten innan du distribuerar. Om du genererar en Dockerfile i guiden granskar du filen och väljer Fortsätt och distribuera. De här alternativen använder fjärranslutna ACR-versioner, inte lokala Docker-versioner.

Anpassade registeralternativ använder ett register i den valda prenumerationen. Buildsökvägen för anpassade register kräver åtkomst till publikt nätverk; sökvägen för färdigbyggda avbildningar har separata krav för privata nätverk. Om du väljer en avbildning konfigureras inte nätverksanslutningen.

Granska containerkraven och vägledningen för privata nätverk innan du använder ett anpassat register. Dessa distributioner riktar in sig på Foundry Agent Service, inte den tillbakadragna Azure Container Apps sökväg för värdbaserad agent. Om du vill flytta en äldre agent följer du Migrera från förhandsversionen av den värdbaserade agenten.

Testa det distribuerade arbetsflödet

En lyckad begäran om att skapa innebär inte att körmiljön är redo eller att dess modell och verktyg kan nås. Testa den exakta distribuerade versionen.

  1. Under Mina resurser>>Värdbaserad agent väljer du agentens namn.
  2. Välj den numrerade version som du precis har distribuerat.
  3. I Information väntar du tills distributionsstatusen anger att agenten körs. Om det misslyckas, granska distributionsresultatet innan du försöker igen.
  4. Öppna Playground och skicka samma begäran som du testade lokalt.
  5. Läs svaret. Om du har lagt till verktyg skickar du en begäran som kräver dessa verktyg och inspekterar anropen.

Lokala körningar och molnkörningar använder olika autentiseringsuppgifter, beroendemiljöer och nätverkssökvägar. Ett lyckat lokalt svar garanterar inte ett lyckat fjärrsvar.

Inspektera och uppdatera den distribuerade agenten

Använd fjärrlekplatsen för att testa och inspektera din distribuerade agent. Till skillnad från lokal testning med Agent Inspector körs förfrågningar i den här testmiljön mot agenten som körs i Foundry.

  1. I Foundry Toolkit väljer du Utvecklarverktyg>Skapa>Playground för hostad agent.

    Skärmbild av Hosted Agent Playground under Skapa i avsnittet Foundry Toolkit Developer Tools.

  2. I listrutan Värdbaserad agent väljer du din distribuerade agent och den version som ska kontrolleras. Öppna Playground för att skicka en begäran och visa svars- och sessionsinformationen.

    Följande skärmbild visar ett illustrativt svar från en distribuerad agent, inte de förväntade resultaten från något av de två arbetsflödesexemplen. Agent- och sessionsidentifierare är dolda.

    Skärmbild av den fjärranslutna lekplatsen för värdbaserade agenter med svar, sessionsinformation och kontrollflikar, med agent- och sessionsidentifierare dolda.

Använd dessa kontroller för att inspektera och uppdatera agenten. Vilka flikar som är tillgängliga beror på dess protokoll och anslutna tjänster.

Task Action
Granska distributionsinformation Öppna Information för status, konfiguration och den kopierbara slutpunkten.
Testa en version Välj en numrerad version för begäranden i Playground. Automatisk följer versionen som valts för tjänstslutpunkten, vilket inte nödvändigtvis är den senaste versionen. Väljaren ändrar inte routning för andra klienter.
Granska körningsloggar Öppna Sessioner, välj en session och visa loggarna. Körningsloggar kräver en session. build-utdata är separata. Att stoppa en loggström eller avbryta en begäran stoppar inte den värdbaserade agenten.
Hämta distribuerad kod Använd Ladda ned kodresurs för en ZIP-distribution. En distribution av en avbild visar referensen till avbilden i stället för ett nedladdningsbart källprojekt.
Uppdateringsbeteende Redigera och testa den lokala koden och upprepa sedan distributionsproceduren med Befintlig agent för att skapa en ny version.

Använd Spårningar och utvärdering när det är tillgängligt för undersökning och kvalitetsmätning utöver ett lyckat svar. Följ förutsättningarna för spårning av värdagent och utvärdering av värdagent.

Distribution ger agenten en slutpunkt för programmatisk användning. Ett separat publiceringssteg krävs inte för API-åtkomst. Publicering till Teams eller Microsoft 365 är en separat uppgift. Se den aktuella agentslutpunkten och publiceringsmodellen.

Troubleshooting

Använd det rapporterade felet och exempelkonfigurationen för att identifiera det misslyckade steget.

Symptom Action
Det går inte att starta lokalt eftersom ett paket saknas. Bekräfta den valda tolken eller SDK:t och installera sedan beroenden från exemplets källkatalog.
Det går inte att hitta projektslutpunkten eller modellen. Kontrollera FOUNDRY_PROJECT_ENDPOINT och AZURE_AI_MODEL_DEPLOYMENT_NAME. Ersätt inte en kontoslutpunkt eller ett modellkatalognamn.
Autentisering eller auktorisering misslyckas. Kontrollera lokala autentiseringsuppgifter och projektåtkomst. Granska behörigheter för värdbaserad agent för krav på identitet vid driftsättning och körning.
Agentinspektören kan inte ansluta. Bekräfta att servern har startats och att porten 8088 är tillgänglig. Att öppna Inspector ensam startar inte servern.
En distribution misslyckas. Granska distributionsfelet och skapa utdata. För kod, kontrollera körmiljön, startpunkten, paketläget och ignoreringsreglerna. Kontrollera avbildnings- och registerbehörigheterna för en container.
Det lokala svaret fungerar, men den distribuerade versionen misslyckas. Jämför den distribuerade miljön och identitetsbehörigheterna med den lokala konfigurationen. Testa den exakta distribuerade versionen igen.

Rensa resurser

Stoppa den lokala felsökningssessionen när du är klar. Om du inte längre behöver den distribuerade testagenten följer du Hantera värdbaserade agenter för att ta bort den.

Om du tar bort agenten tas dess versioner bort och aktiva sessioner avslutas. Den tar inte bort alla associerade Azure resurs.

Ta endast bort molnresurser som skapats för den här övningen som inga andra program använder. Ta inte bort ett delat Foundry-projekt, modelldistribution eller containerregister.

Relaterat innehåll

Använd dessa guider för att utöka arbetsflödet:

  • Last updated on