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

Erstellen, Testen und Bereitstellen hosted Foundry Agent-Workflows mithilfe des Foundry Toolkits für Visual Studio Code. Das Toolkit unterstützt die Agenterstellung aus Vorlagen, lokale Tests und das Debugging mit dem Agent Inspector, welcher sowohl die Visualisierung als auch die Unterstützung bei der Ablaufverfolgung ermöglicht, sowie die direkte Bereitstellung zum Foundry-Agent-Service aus VS Code. In gehosteten Workflows können mehrere Agents sequenziert zusammenarbeiten, jeweils mit einem eigenen Modell, tools und Anweisungen.

Bevor Sie beginnen, erstellen Sie einen Agent im Foundry Agent Service mithilfe der Erweiterung. Anschließend können Sie diesem Agent gehostete Workflows hinzufügen.

Dieser Artikel behandelt das Erstellen eines Workflow-Projekts, dessen lokale Ausführung, die Visualisierung der Ausführung und die Bereitstellung in Ihrem Foundry-Arbeitsbereich.

Voraussetzungen

  • Ein Foundry-Projekt mit einem bereitgestellten Modell oder einer Azure OpenAI-Ressource.
  • Das Foundry Toolkit für Visual Studio Code wurde installiert.
  • Die verwaltete Identität des Projekts mit den zugewiesenen Rollen Azure>AZURE AI User und AcrPull zugewiesen. Weisen Sie außerdem der verwalteten Identität des Foundry-Projekts die acrPull Rolle zu, in der Sie den gehosteten Agent bereitstellen möchten.
  • Eine unterstützte Region für gehostete Agents.
  • Python 3.12 oder höher.

Erstellen eines gehosteten Agent-Workflows

Sie können das Foundry Toolkit für Visual Studio Code verwenden, um gehostete Agent-Workflows zu erstellen. Ein gehosteter Agent-Workflow ist eine Abfolge von Agents, die zusammenarbeiten, um eine Aufgabe auszuführen. Jeder Agent im Workflow kann über ein eigenes Modell, tools und Anweisungen verfügen.

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

  2. Führen Sie diesen Befehl aus: >Microsoft Foundry: Create a New Hosted Agent.

  3. Wählen Sie ein Framework aus, entweder Microsoft Agent Framework oder LangGraph.

  4. Wählen Sie eine Vorlage aus, entweder den Einzelagent-Hotelassistenten oder den Writer-Reviewer-Agent-Workflow (Mehragenten).

  5. Wählen Sie eine Programmiersprache aus.

  6. Wählen Sie ein Modell aus, entweder ein Modell, das Sie bereits in Ihrem Projekt bereitgestellt haben, oder durchsuchen Sie den Modellkatalog.

  7. Wählen Sie einen Ordner aus, in dem Sie Den neuen Workflow speichern möchten.

Die Dateien für Ihr gehostetes Agent-Projekt werden in Ihrem ausgewählten Ordner basierend auf dem Framework, der Vorlage und der Sprache generiert, die Sie für die ersten Schritte ausgewählt haben. Sie können diesen Code nach Bedarf entfernen oder ändern.

Abhängigkeiten installieren

Installieren Sie die erforderlichen Abhängigkeiten für Ihr gehostetes Agent-Projekt. Die Abhängigkeiten variieren je nach der Programmiersprache, die Sie beim Erstellen des Projekts ausgewählt haben.

  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 Projektverzeichnis, und führen Sie diesen Befehl aus, um die erforderlichen NuGet-Pakete abzurufen:

    dotnet restore

Lokales Ausführen des gehosteten Workflows

Das Beispielworkflowprojekt erstellt eine env-Datei mit den erforderlichen Umgebungsvariablen. 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>

Wichtig

Übernehmen Sie die Datei niemals in die .env Versionsverwaltung. Fügen Sie sie Zu Ihrer .gitignore Datei hinzu.

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 Agenteninspektor 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 geschieht wie folgt:

  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: Chateingaben gehen zu /v1/responses, das Ereignisse über SSE für eine Echtzeitvisualisierung streamt.
  4. Codenavigation aktivieren: Doppelklicken Sie auf Workflowknoten, um die entsprechende Quelldatei im Editor zu öffnen.
  5. Aktivieren Sie das Chatten mit dem lokalen Agenten, und Sie können Antworten anzeigen, Haltepunkte für das Debuggen setzen usw.

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:

    $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

Tipp

Öffnen Sie den lokalen Playground, bevor Sie den Container-Agent starten, um sicherzustellen, dass die Visualisierung ordnungsgemäß funktioniert.

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 Agents auf der Playground-Schnittstelle.

Visualisieren der Workflowausführung des gehosteten Agents

Das Foundry Toolkit für Visual Studio Code 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 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. 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";

Bereitstellen des gehosteten Agents

Nachdem Sie Ihren gehosteten Agent lokal getestet haben, stellen Sie ihn in Ihrem Foundry-Arbeitsbereich bereit, damit andere Teammitglieder und Anwendungen sie verwenden können.

Wichtig

Stellen Sie sicher, dass Sie die erforderlichen Berechtigungen zum Bereitstellen gehosteter Agents in Ihrem Foundry-Arbeitsbereich erteilen, wie in den Voraussetzungen angegeben. Möglicherweise müssen Sie mit Ihrem Azure Administrator zusammenarbeiten, um die erforderlichen Rollenzuweisungen zu erhalten.

  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 Agent aus, um auf detaillierte Informationen und Testfunktionen mithilfe der integrierten Playground-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 Agent aus, um auf detaillierte Informationen und Testfunktionen mithilfe der integrierten Playground-Schnittstelle zuzugreifen.

Verwandte Inhalte

  • Last updated on