Gehoste agentwerkstromen maken in Visual Studio Code (preview)

Maak, test en implementeer hosted Foundry Agent-werkstromen met behulp van de Foundry Toolkit voor Visual Studio Code. De toolkit ondersteunt het maken van agents vanuit sjablonen, lokaal testen en foutopsporing met agentcontrole voor ondersteuning voor visualisatie en tracering, en directe implementatie naar Foundry Agent Service vanuit VS Code. Met gehoste werkstromen kunnen meerdere agents op volgorde samenwerken, elk met een eigen model, hulpprogramma's en instructies.

Voordat u begint, bouwt u een agent in Foundry Agent Service met behulp van de extensie. Vervolgens kunt u gehoste werkstromen toevoegen aan die agent.

Dit artikel bevat informatie over het maken van een werkstroomproject, het lokaal uitvoeren, het visualiseren van de uitvoering en het implementeren ervan in uw Foundry-werkruimte.

Voorwaarden

  • Een Foundry-project met een geïmplementeerd model of een Azure OpenAI-resource.
  • De Foundry Toolkit voor Visual Studio Code is geïnstalleerd.
  • De beheerde identiteit van het project met de rollen Azure AI User en AcrPull toegewezen. Wijs ook de acrPull rol toe aan de beheerde identiteit van het Foundry-project waar u de gehoste agent wilt implementeren.
  • Een ondersteunde regio voor gehoste agents.
  • Python 3,12 of hoger.

Een gehoste agentwerkstroom maken

U kunt de Foundry Toolkit voor Visual Studio Code gebruiken om gehoste agentwerkstromen te maken. Een gehoste agentwerkstroom is een reeks agents die samenwerken om een taak uit te voeren. Elke agent in de werkstroom kan een eigen model, hulpprogramma's en instructies hebben.

  1. Open het opdrachtenpalet (Ctrl+Shift+P).

  2. Voer deze opdracht uit: >Microsoft Foundry: Create a New Hosted Agent.

  3. Kies een framework, Microsoft Agent Framework of LangGraph.

  4. Kies een sjabloon: de Single Agent Hotel Assistent, of de Writer-Reviewer Agent Workflow (multi-agent).

  5. Selecteer een programmeertaal.

  6. Kies een model, een model dat u al in uw project hebt geïmplementeerd of blader door de modelcatalogus.

  7. Selecteer een map waarin u de nieuwe werkstroom wilt opslaan.

De bestanden voor het gehoste agentproject worden gegenereerd in de geselecteerde map op basis van het framework, de sjabloon en de taal die u hebt geselecteerd om u op weg te helpen. U kunt die code indien nodig verwijderen of wijzigen.

Afhankelijkheden installeren

Installeer de vereiste afhankelijkheden voor uw gehoste agentproject. De afhankelijkheden variëren afhankelijk van de programmeertaal die u hebt geselecteerd toen u het project maakte.

  1. Maak een virtuele omgeving.

     python -m venv .venv

  2. Activeer de virtuele omgeving.

    # PowerShell
./.venv/Scripts/Activate.ps1

# Windows cmd
.venv\Scripts\activate.bat

# Unix/MacOS
source .venv/bin/activate

  3. Installeer het volgende pakket:

    pip install azure-ai-agentserver-agentframework

  1. Ga naar uw projectmap en voer deze opdracht uit om de benodigde NuGet-pakketten op te halen:

    dotnet restore

Uw gehoste werkstroom lokaal uitvoeren

Het voorbeeldwerkstroomproject maakt een .env-bestand met de benodigde omgevingsvariabelen. Maak of werk het .env-bestand bij met uw Foundry-referenties:

PROJECT_ENDPOINT=https://<your-resource-name>.services.ai.azure.com/api/projects/<your-project-name>

MODEL_DEPLOYMENT_NAME=<your-model-deployment-name>

Belangrijk

Voer het .env bestand nooit door naar versiebeheer. Voeg het toe aan uw .gitignore bestand.

Authenticeer uw gehoste agent

Het voorbeeld van de gehoste agent authenticeert met DefaultAzureCredential. Configureer uw ontwikkelomgeving om referenties op te geven via een van de ondersteunde bronnen, bijvoorbeeld:

  • Azure CLI (az login)
  • aanmelding bij Visual Studio Code account
  • aanmelding bij Visual Studio account
  • Omgevingsvariabelen voor een service-principal (AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET)

Bevestig de verificatie lokaal door de opdrachten Azure CLI az account show of az account get-access-token uit te voeren voordat u het voorbeeld uitvoert.

U kunt de gehoste agent uitvoeren in de interactieve modus of containermodus.

Voer uw gehoste agent uit in de Agent Inspector.

Als u de gehoste agent lokaal wilt uitvoeren in Visual Studio Code, selecteert u de sleutel F5. Hiermee opent u de Agent Inspector en voert u uw toepassing uit.

Dit doet het volgende:

  1. Start de agentserver: De agentdev CLI verpakt uw agent als een HTTP-server op poort 8087, met foutopsporing die is gekoppeld aan poort 5679.
  2. Agents detecteren: De gebruikersinterface haalt beschikbare agents/werkstromen op van /agentdev/entities.
  3. Streaming-uitvoering: Chatinvoer gaat naar /v1/responses, waarmee gebeurtenissen worden gestreamd via SSE voor realtime visualisatie.
  4. Codenavigatie inschakelen: Dubbelklik op werkstroomknooppunten om het bijbehorende bronbestand in de editor te openen.
  5. Schakel chatten met de lokale agent in en antwoorden weergeven, onderbrekingspunten bereiken voor foutopsporing, enzovoort.

Het voorbeeldwerkstroomproject maakt een .env-bestand met de benodigde omgevingsvariabelen. Maak of werk het .env-bestand bij met uw Foundry-referenties:

  1. Stel uw omgevingsvariabelen in op basis van uw besturingssysteem:

    $env:AZURE_AI_PROJECT_ENDPOINT="https://<your-resource-name>.services.ai.azure.com/api/projects/<your-project-name>"
$env:AZURE_AI_MODEL_DEPLOYMENT_NAME="your-deployment-name"

Authenticeer uw gehoste agent

Het voorbeeld van de gehoste agent authenticeert met DefaultAzureCredential. Configureer uw ontwikkelomgeving om referenties op te geven via een van de ondersteunde bronnen, bijvoorbeeld:

  • Azure CLI (az login)
  • aanmelding bij Visual Studio Code account
  • aanmelding bij Visual Studio account
  • Omgevingsvariabelen voor een service-principal (AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET)

Bevestig de verificatie lokaal door de opdrachten Azure CLI az account show of az account get-access-token uit te voeren voordat u het voorbeeld uitvoert.

U kunt de gehoste agent uitvoeren in de interactieve modus of containermodus.

Uw gehoste agent uitvoeren in de interactieve modus

Voer de gehoste agent rechtstreeks uit voor ontwikkeling en testen:

dotnet restore
dotnet build
dotnet run

Uw gehoste agent uitvoeren in de containermodus

Tip

Open de lokale speeltuin voordat u de containeragent start om ervoor te zorgen dat de visualisatie correct werkt.

Om de agent uit te voeren in de containermodus:

  1. Open het Visual Studio Code opdrachtpalet en voer de opdracht Microsoft Foundry: Open Container Agent Playground Locally uit.
  2. Gebruik de volgende opdracht om de gehoste containeragent te initialiseren. 
    dotnet restore
dotnet build
dotnet run
  3. Dien een aanvraag in bij de agent via de speeltuininterface. Voer bijvoorbeeld een prompt in zoals: "Creëer een slogan voor een nieuwe elektrische SUV die betaalbaar en leuk is om te rijden."
  4. Bekijk het antwoord van de agent in de speeltuininterface.

Uitvoering van gehoste agentwerkstroom visualiseren

De Foundry Toolkit voor Visual Studio Code biedt een realtime uitvoeringsgrafiek die laat zien hoe agents in uw werkstroom communiceren en samenwerken. Schakel waarneembaarheid in uw project in om deze visualisatie te gebruiken.

Voeg de volgende verwijzing toe aan uw csproj-bestand:

<ItemGroup>
    <PackageReference Include="OpenTelemetry" Version="1.12.0" />
    <PackageReference Include="OpenTelemetry.Exporter.Console" Version="1.12.0" />
    <PackageReference Include="OpenTelemetry.Exporter.OpenTelemetryProtocol" Version="1.12.0" />
    <PackageReference Include="System.Diagnostics.DiagnosticSource" Version="9.0.10" />
</ItemGroup>

Werk uw programma bij om het volgende codefragment op te nemen:

using System.Diagnostics;
using OpenTelemetry;
using OpenTelemetry.Logs;
using OpenTelemetry.Metrics;
using OpenTelemetry.Resources;
using OpenTelemetry.Trace;

var otlpEndpoint =
    Environment.GetEnvironmentVariable("OTLP_ENDPOINT") ?? "http://localhost:4319";

var resourceBuilder = OpenTelemetry
    .Resources.ResourceBuilder.CreateDefault()
    .AddService("WorkflowSample");

var s_tracerProvider = OpenTelemetry
    .Sdk.CreateTracerProviderBuilder()
    .SetResourceBuilder(resourceBuilder)
    .AddSource("Microsoft.Agents.AI.*") // All agent framework sources
    .SetSampler(new AlwaysOnSampler()) // Ensure all traces are sampled
    .AddOtlpExporter(options =>
    {
        options.Endpoint = new Uri(otlpEndpoint);
        options.Protocol = OpenTelemetry.Exporter.OtlpExportProtocol.Grpc;
    })
    .Build();

Uw gehoste agentwerkstroom bewaken en visualiseren

De uitvoering van uw gehoste agentwerkstroom in realtime bewaken en visualiseren:

  1. Open het opdrachtenpalet (Ctrl+Shift+P).

  2. Voer deze opdracht uit: >Microsoft Foundry: Open Visualizer for Hosted Agents.

Er wordt een nieuw tabblad geopend in VS Code om de uitvoeringsgrafiek weer te geven. De visualisatie wordt automatisch bijgewerkt naarmate uw werkstroom vordert, om de stroom tussen agents en hun interacties weer te geven.

Poortconflicten

Voor poortconflicten kunt u de visualisatiepoort wijzigen door deze in te stellen in de instellingen van de Foundry-extensie. Voer hiervoor de volgende stappen uit:

  1. Selecteer in de linkerzijbalk van VS Code het tandwielpictogram om het instellingenmenu te openen.
  2. Selecteer Extensions>Microsoft Foundry Configuration.
  3. Zoek de Hosted Agent Visualization Port instelling en wijzig deze in een beschikbaar poortnummer.
  4. Start VS Code opnieuw om de wijzigingen toe te passen.

Poort in code wijzigen

Voor poortconflicten wijzigt u de visualisatiepoort door de FOUNDRY_OTLP_PORT omgevingsvariabele in te stellen. Werk het OTLP-eindpunt in uw programma dienovereenkomstig bij.

Als u bijvoorbeeld de poort wilt wijzigen in 4318, gebruikt u deze opdracht:

  $env:FOUNDRY_OTLP_PORT="4318"

Werk in uw programma het OTLP-eindpunt bij om het nieuwe poortnummer te gebruiken:

var otlpEndpoint =
    Environment.GetEnvironmentVariable("OTLP_ENDPOINT") ?? "http://localhost:4318";

De gehoste agent implementeren

Nadat u de gehoste agent lokaal hebt getest, implementeert u deze in uw Foundry-werkruimte, zodat andere teamleden en toepassingen deze kunnen gebruiken.

Belangrijk

Zorg ervoor dat u de benodigde machtigingen verleent voor het implementeren van gehoste agents in uw Foundry-werkruimte, zoals vermeld in de vereisten. Mogelijk moet u samenwerken met uw Azure-beheerder om de vereiste roltoewijzingen op te halen.

  1. Open het Visual Studio Code opdrachtpalet en voer de opdracht Microsoft Foundry: Deploy Hosted Agent uit.
  2. Configureer de implementatie-instellingen door uw doelwerkruimte te selecteren, het containeragentbestand (container.py) op te geven en indien nodig andere implementatieparameters te definiëren.
  3. Na een geslaagde implementatie wordt de gehoste agent weergegeven in de sectie Hosted Agents (Preview) van de structuurweergave van de Microsoft Foundry-extensie.
  4. Selecteer de geïmplementeerde agent voor toegang tot gedetailleerde informatie en testfunctionaliteit met behulp van de geïntegreerde speeltuininterface.
  1. Open het Visual Studio Code opdrachtpalet en voer de opdracht Microsoft Foundry: Deploy Hosted Agent uit.
  2. Configureer de implementatie-instellingen door uw doelwerkruimte te selecteren, het containeragentbestand (<your-project-name>.csproj) op te geven en indien nodig andere implementatieparameters te definiëren.
  3. Na een geslaagde implementatie wordt de gehoste agent weergegeven in de sectie Hosted Agents (Preview) van de structuurweergave van de Microsoft Foundry-extensie.
  4. Selecteer de geïmplementeerde agent voor toegang tot gedetailleerde informatie en testfunctionaliteit met behulp van de geïntegreerde speeltuininterface.

Verwante inhoud

  • Last updated on