Gehoste agentwerkstromen maken in de Microsoft Foundry Toolkit voor Visual Studio Code-extensie

Maak, test en implementeer hosted Foundry Agent-werkstromen met behulp van de Microsoft Foundry Toolkit voor Visual Studio Code-extensie. 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 Microsoft Foundry Toolkit voor Visual Studio Code-extensie geïnstalleerd.

  • De beheerde identiteit van het project waaraan de rollen Foundry User en AcrPull zijn toegewezen. Wijs ook de acrPull rol toe aan de beheerde identiteit van het Foundry-project waar u de gehoste agent wilt implementeren.

    Belangrijk

    De rollen Foundry RBAC zijn onlangs hernoemd. Foundry User, Foundry Owner, Foundry Account Owner en Foundry Project Manager zijn eerder benoemd Azure AI-gebruiker, Azure AI-eigenaar Azure AI-accounteigenaar en Azure AI Project Manager. Het kan zijn dat u op sommige plekken nog steeds de vorige namen ziet terwijl de naamswijziging wordt doorgevoerd. De rol-id's en basismachtigingen worden niet gewijzigd door de naamswijziging.

  • Een ondersteunde regio voor gehoste agents.

  • Python 3,13 of hoger.

Een gehoste agentwerkstroom maken

U kunt de Microsoft Foundry Toolkit voor Visual Studio Code-extensie gebruiken om gehoste agentwerkstromen te maken. Een werkstroom voor gehoste agents 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: >Foundry Toolkit: Create a New Hosted Agent.

  3. Een programmeertaal selecteren

  4. Kies een framework, Copilot SDK, Microsoft Agent Framework of Bring Your Own.

  5. Kies een protocol, de Antwoord-API of de API voor aanroepen.

  6. Kies een sjabloon in de lijst.

  7. Selecteer de knop Volgende.

  8. Selecteer een map waarin u de nieuwe gehoste agent wilt opslaan.

  9. Bij Omgevingsinstellingen zorgt het selecteren van 'Nu overslaan' ervoor dat de configuratie van het Foundry-project en -model wordt overgeslagen, waardoor u deze later handmatig in de code moet configureren. Als u Configureren met Microsoft Foundry selecteert, worden uw project en modelgegevens automatisch ingevuld met de bestaande Foundry-Project.

De bestanden voor uw 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 de vereiste pakketten:

    pip install -r requirements.txt

  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:

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

FOUNDRY_MODEL_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 voor een gehoste agent verifieert zich 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.

Druk op F5 om de lokale HTTP-server te starten waarvoor foutopsporing is ingeschakeld. De Foundry Toolkit Agent Inspector wordt geopend voor interactief testen en u kunt onderbrekingspunten instellen in uw code.

De server uitvoeren zonder foutopsporing:

python main.py

De agent luistert.http://localhost:8088/ Een testprompt verzenden met curl (of een HTTP-client):

curl -sS -H "Content-Type: application/json" -X POST http://localhost:8088/responses \
    -d '{"input": "Write a haiku about deploying cloud applications.", "stream": false}'

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:FOUNDRY_PROJECT_ENDPOINT="https://<your-resource-name>.services.ai.azure.com/api/projects/<your-project-name>"
$env:FOUNDRY_MODEL_NAME="your-deployment-name"

Authenticeer uw gehoste agent

Het voorbeeld voor een gehoste agent verifieert zich 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 Foundry Toolkit: 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 Microsoft Foundry Toolkit voor Visual Studio Code-extensie 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

Werkstroomuitvoering van gehoste agents bewaken en visualiseren in realtime:

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

  2. Voer deze opdracht uit: >Foundry Toolkit: 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 Microsoft Foundry Toolkit voor Visual Studio Code extensie-instellingen. 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 geeft 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 opdrachtenpalet en selecteer Foundry Toolkit: Hosted Agent implementeren. Er wordt een implementatiewebweergave geopend.
  2. Selecteer code of container bij Implementatiemethode.
  3. Als u implementeert met 'Code', selecteert u Extern of Lokaal als 'Pakketmodus'.
  4. Als u implementeert met 'Container', selecteert u Standaard ACR, Aangepaste ACR of Aangepaste ACR-image van de klant.
  5. De naam van de agent moet automatisch worden ingevuld.
  6. Selecteer de knop Volgende.
  7. Deze pagina 'Controleren en implementeren' zou automatisch volledig ingevuld moeten worden.
  8. Selecteer de knop Implementeren.
  9. Open het Visual Studio Code opdrachtpalet en voer de opdracht Foundry Toolkit: Deploy Hosted Agent uit.
  1. Open het Visual Studio Code opdrachtpalet en voer de opdracht Foundry Toolkit: Deploy Hosted Agent uit.
  2. Selecteer code of container bij Implementatiemethode.
  3. Als u implementeert met 'Code', selecteert u Extern of Lokaal als 'Pakketmodus'.
  4. Als u implementeert met 'Container', selecteert u Standaard ACR, Aangepaste ACR of Aangepaste ACR-image van de klant.
  5. De naam van de agent moet automatisch worden ingevuld.
  6. Selecteer de knop Volgende.
  7. Deze pagina 'Controleren en implementeren' zou automatisch volledig ingevuld moeten worden.
  8. Selecteer de knop Implementeren.

Verwante inhoud

  • Last updated on