Erstellen von Workflows für gehostete Agent in Visual Studio Code (Vorschau)

• Python 3.12 oder höher.

• .NET 9 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 das folgende Paket:

   pip install azure-ai-agentserver-agentframework
   

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

   dotnet restore
   

Das Beispielworkflow-Projekt erstellt eine .env-Datei mit Umgebungsvariablen, die erforderlich sind. Erstellen oder aktualisieren Sie die env-Datei mit Ihren Foundry-Anmeldeinformationen:

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

MODEL_DEPLOYMENT_NAME=<your-model-deployment-name>

Authentifizieren Ihres gehosteten Agents

Das Beispiel des gehosteten Agents 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.

Führen Sie Ihren gehosteten Agenten im Agent Inspector aus

Wenn Sie Ihren gehosteten Agent lokal in Visual Studio Code ausführen möchten, wählen Sie den Schlüssel F5 aus. Dadurch wird der Agent Inspector geöffnet und Ihre Anwendung ausgeführt.

Dies bewirkt Folgendes:

1. Starten Sie den Agentserver: Die agentdev CLI umschließt Ihren Agent als HTTP-Server auf Port 8087, wobei debugpy an Port 5679 angefügt ist.
2. Agents entdecken: Die Benutzeroberfläche ruft verfügbare Agents/Workflows von /agentdev/entities.
3. Streamausführung: Chat-Eingaben werden an /v1/responses gesendet, der Ereignisse über SSE für die Echtzeitvisualisierung zurückstreamt.
4. Codenavigation aktivieren: Doppelklicken Sie auf Workflowknoten, um die entsprechende Quelldatei im Editor zu öffnen.
5. Aktivieren Sie den Chat mit dem lokalen Agenten und zeigen Sie Antworten an, setzen Sie Haltepunkte zum Debuggen und dergleichen.

Das Beispielworkflow-Projekt erstellt eine .env-Datei mit Umgebungsvariablen, die erforderlich sind. 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: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"
   

Authentifizieren Ihres gehosteten Agents

Das Beispiel des gehosteten Agents 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 Microsoft Foundry: 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 Agenten auf der Playground-Schnittstelle.

Visualisieren der Workflowausführung des gehosteten Agents

Die Foundry für Visual Studio Code-Erweiterung bietet ein Echtzeitausführungsdiagramm, das zeigt, wie Agents in Ihrem Workflow interagieren und zusammenarbeiten. Aktivieren Sie die Beobachtbarkeit 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 Ausführung ihres gehosteten Agent-Workflows in Echtzeit:

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

2. Führen Sie diesen Befehl aus: >Microsoft Foundry: 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 in den Foundry-Erweiterungseinstellungen festlegen. Um dies zu tun, befolgen Sie diese Schritte:

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 Visual Studio Code Befehlspalette, und führen Sie den Befehl Microsoft Foundry: Deploy Hosted Agent aus.
2. Konfigurieren Sie die Bereitstellungseinstellungen, indem Sie Ihren Zielarbeitsbereich auswählen, die Container-Agent-Datei (container.py) angeben und alle anderen Bereitstellungsparameter nach Bedarf definieren.
3. Nach erfolgreicher Bereitstellung wird der gehostete Agent im Abschnitt Hosted Agents (Preview) der Strukturansicht der Microsoft Foundry-Erweiterung angezeigt.
4. Wählen Sie den bereitgestellten Agenten aus, um auf detaillierte Informationen und Testfunktionen mithilfe der integrierten Spielwiese-Schnittstelle zuzugreifen.

1. Öffnen Sie die Visual Studio Code Befehlspalette, und führen Sie den Befehl Microsoft Foundry: Deploy Hosted Agent aus.
2. Konfigurieren Sie die Bereitstellungseinstellungen, indem Sie Ihren Zielarbeitsbereich auswählen, die Container-Agent-Datei (<your-project-name>.csproj) angeben und alle anderen Bereitstellungsparameter nach Bedarf definieren.
3. Nach erfolgreicher Bereitstellung wird der gehostete Agent im Abschnitt Hosted Agents (Preview) der Strukturansicht der Microsoft Foundry-Erweiterung angezeigt.
4. Wählen Sie den bereitgestellten Agenten aus, um auf detaillierte Informationen und Testfunktionen mithilfe der integrierten Spielwiese-Schnittstelle zuzugreifen.