Erstellen Sie Workflows für gehostete Agenten in der Microsoft Foundry Toolkit-Erweiterung für Visual Studio Code

• Python 3.13 oder höher.

• .NET 10 SDK oder höher.

1. Erstellen Sie virtuelle Umgebung.

    python -m venv .venv
   

2. Aktivieren Sie die virtuelle Umgebung.

   # PowerShell
   ./.venv/Scripts/Activate.ps1
   
   # Windows cmd
   .venv\Scripts\activate.bat
   
   # Unix/MacOS
   source .venv/bin/activate
   

3. Installieren Sie die erforderlichen Pakete:

   pip install -r requirements.txt
   

1. Wechseln Sie zu Ihrem Projektverzeichnis, und führen Sie diesen Befehl aus, um die erforderlichen NuGet-Pakete abzurufen:

   dotnet restore
   

Das Beispielworkflowprojekt erstellt eine env-Datei mit den erforderlichen Umgebungsvariablen. Erstellen oder aktualisieren Sie die env-Datei mit Ihren Foundry-Anmeldeinformationen:

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

AZURE_AI_MODEL_DEPLOYMENT_NAME=<your-model-deployment-name>

Authentifizieren Ihres gehosteten Agents

Das Beispiel für den gehosteten Agent authentifiziert sich mit DefaultAzureCredential. Konfigurieren Sie Ihre Entwicklungsumgebung so, dass Anmeldeinformationen über eine der unterstützten Quellen bereitgestellt werden, z. B.:

• Azure CLI (az login)
• Visual Studio Code Kontoanmeldung
• Visual Studio Kontoanmeldung
• Umgebungsvariablen für einen Dienstprinzipal (AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET)

Bestätigen Sie die Authentifizierung lokal, indem Sie entweder die Befehle Azure CLI az account show oder az account get-access-token ausführen, bevor Sie das Beispiel ausführen.

Sie können den gehosteten Agent im interaktiven Modus oder im Containermodus ausführen.

Gehosteten Agent im Agent Inspector ausführen

Drücken Sie F5 , um den lokalen HTTP-Server mit aktivierter Debuggingfunktion zu starten. Der Foundry Toolkit Agent Inspector wird für interaktive Tests geöffnet, und Sie können Haltepunkte in Ihrem Code festlegen.

So führen Sie den Server ohne Debugging aus:

python main.py

Der Agent wartet auf http://localhost:8088/. Senden sie eine Testaufforderung mit curl (oder einem beliebigen 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}'

Das Beispielworkflowprojekt erstellt eine env-Datei mit den erforderlichen Umgebungsvariablen. Erstellen oder aktualisieren Sie die env-Datei mit Ihren Foundry-Anmeldeinformationen:

1. Richten Sie Ihre Umgebungsvariablen basierend auf Ihrem Betriebssystem ein:

   • Windows (PowerShell)
   • Windows (Eingabeaufforderung)
   • macOS/Linux (Bash)

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

Authentifizieren Ihres gehosteten Agents

Das Beispiel für den gehosteten Agent authentifiziert sich mit DefaultAzureCredential. Konfigurieren Sie Ihre Entwicklungsumgebung so, dass Anmeldeinformationen über eine der unterstützten Quellen bereitgestellt werden, z. B.:

• Azure CLI (az login)
• Visual Studio Code Kontoanmeldung
• Visual Studio Kontoanmeldung
• Umgebungsvariablen für einen Dienstprinzipal (AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET)

Bestätigen Sie die Authentifizierung lokal, indem Sie entweder die Befehle Azure CLI az account show oder az account get-access-token ausführen, bevor Sie das Beispiel ausführen.

Sie können den gehosteten Agent im interaktiven Modus oder im Containermodus ausführen.

Ausführen Ihres gehosteten Agents im interaktiven Modus

Führen Sie den gehosteten Agent direkt für Entwicklung und Tests aus:

dotnet restore
dotnet build
dotnet run

Ausführen Ihres gehosteten Agents im Containermodus

So führen Sie den Agent im Containermodus aus:

1. Öffnen Sie die Visual Studio Code Befehlspalette, und führen Sie den Befehl Foundry Toolkit: Open Container Agent Playground Locally aus.
2. Verwenden Sie den folgenden Befehl, um den containerisierten gehosteten Agent zu initialisieren.

   dotnet restore
   dotnet build
   dotnet run
   

3. Senden Sie eine Anforderung an den Agent über die Playground-Schnittstelle. Geben Sie beispielsweise eine Eingabeaufforderung ein, z. B.: "Erstellen Sie einen Slogan für einen neuen elektrischen SUV, der erschwinglich ist und Spaß macht, zu fahren."
4. Überprüfen Sie die Antwort des Agents auf der Playground-Schnittstelle.

Visualisieren der Workflowausführung des gehosteten Agents

Das Microsoft Foundry Toolkit für Visual Studio Code Erweiterung bietet ein Echtzeitausführungsdiagramm, das zeigt, wie Agents in Ihrem Workflow interagieren und zusammenarbeiten. Aktivieren Sie die Observability in Ihrem Projekt, um diese Visualisierung zu verwenden.

Fügen Sie der csproj-Datei den folgenden Verweis hinzu:

<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>

Aktualisieren Sie Ihr Programm so, dass er den folgenden Codeausschnitt enthält:

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();

Überwachen und Visualisieren Ihres gehosteten Agent-Workflows

So überwachen und visualisieren Sie die Workflowausführung des gehosteten Agents in Echtzeit:

1. Öffnen Sie die Befehlspalette (STRG+UMSCHALT+P).

2. Führen Sie diesen Befehl aus: >Foundry Toolkit: Open Visualizer for Hosted Agents.

Eine neue Registerkarte wird in VS Code geöffnet, um das Ausführungsdiagramm anzuzeigen. Die Visualisierung wird automatisch aktualisiert, wenn Ihr Workflow fortschreitet, um den Fluss zwischen Agents und deren Interaktionen anzuzeigen.

Portkonflikte

Bei Portkonflikten können Sie den Visualisierungsport ändern, indem Sie ihn im Microsoft Foundry Toolkit für Visual Studio Code Erweiterungseinstellungen festlegen. Führen Sie dazu die folgenden Schritte aus:

1. Wählen Sie in der linken Randleiste von VS Code das Zahnradsymbol aus, um das Einstellungsmenü zu öffnen.
2. Wählen Sie Extensions>Microsoft Foundry Configuration aus.
3. Suchen Sie die Hosted Agent Visualization Port Einstellung, und ändern Sie sie in eine verfügbare Portnummer.
4. Starten Sie VS Code neu, um die Änderungen anzuwenden.

Ändern des Ports im Code

Ändern Sie bei Portkonflikten den Visualisierungsport, indem Sie die FOUNDRY_OTLP_PORT Umgebungsvariable festlegen. Aktualisieren Sie den OTLP-Endpunkt in Ihrem Programm entsprechend.

Um beispielsweise den Port in 4318 zu ändern, verwenden Sie den folgenden Befehl:

  $env:FOUNDRY_OTLP_PORT="4318"

Aktualisieren Sie in Ihrem Programm den OTLP-Endpunkt so, dass die neue Portnummer verwendet wird:

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

1. Öffnen Sie die Befehlspalette, und wählen Sie Foundry Toolkit: Deploy Hosted Agent. Eine Bereitstellungswebansicht wird geöffnet.
2. Wählen Sie für "Bereitstellungsmethode" Code oder Container aus.
3. Wählen Sie bei der Bereitstellung mit "Code" für "Paketmodus" die Option "Remote " oder "Lokal" aus.
4. Wenn Sie mit "Container" bereitstellen, wählen Sie entweder "Standard-ACR", "Custom ACR" oder "Customer ACR Image" aus.
5. Der „Agent Name“ sollte automatisch ausgefüllt werden.
6. Wählen Sie die Schaltfläche "Weiter" aus.
7. Diese Seite „Überprüfen und bereitstellen“ sollte automatisch vollständig ausgefüllt werden.
8. Wählen Sie die Schaltfläche "Bereitstellen" aus.
9. Öffnen Sie die Visual Studio Code Befehlspalette, und führen Sie den Befehl Foundry Toolkit: Deploy Hosted Agent aus.

1. Öffnen Sie die Visual Studio Code Befehlspalette, und führen Sie den Befehl Foundry Toolkit: Deploy Hosted Agent aus.
2. Wählen Sie für "Bereitstellungsmethode" Code oder Container aus.
3. Wählen Sie bei der Bereitstellung mit "Code" für "Paketmodus" die Option "Remote " oder "Lokal" aus.
4. Wenn Sie mit "Container" bereitstellen, wählen Sie entweder "Standard-ACR", "Custom ACR" oder "Customer ACR Image" aus.
5. Der „Agent Name“ sollte automatisch ausgefüllt werden.
6. Wählen Sie die Schaltfläche "Weiter" aus.
7. Diese Seite „Überprüfen und bereitstellen“ sollte automatisch vollständig ausgefüllt werden.
8. Wählen Sie die Schaltfläche "Bereitstellen" aus.