Créer des flux de travail d’agent hébergés dans Visual Studio Code (préversion)

• Python 3,12 ou version ultérieure.

• .NET 9 SDK ou version ultérieure.

1. Créez un environnement virtuel.

    python -m venv .venv
   

2. Activez l’environnement virtuel.

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

3. Installez le package suivant :

   pip install azure-ai-agentserver-agentframework
   

1. Accédez au répertoire de votre projet et exécutez cette commande pour obtenir les packages NuGet nécessaires :

   dotnet restore
   

L’exemple de projet de flux de travail crée un fichier .env avec les variables d’environnement nécessaires. Créez ou mettez à jour le fichier .env avec vos informations d’identification Foundry :

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

MODEL_DEPLOYMENT_NAME=<your-model-deployment-name>

Authentifier votre agent hébergé

L’exemple d’agent hébergé s’authentifie à l’aide de DefaultAzureCredential. Configurez votre environnement de développement pour fournir des informations d’identification via l’une des sources prises en charge, par exemple :

• Azure CLI (az login)
• connexion au compte Visual Studio Code
• connexion au compte Visual Studio
• Variables d’environnement pour un principal de service (AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET)

Confirmez l’authentification localement en exécutant les commandes Azure CLI az account show ou az account get-access-token avant d’exécuter l’exemple.

Vous pouvez exécuter l’agent hébergé en mode interactif ou en mode conteneur.

Exécutez votre agent hébergé dans l'Inspecteur d'Agents

Pour exécuter votre agent hébergé localement dans Visual Studio Code, sélectionnez la clé F5. L'inspecteur d'agent s'ouvre et l'application est exécutée.

Cela va :

1. Démarrez le serveur d’agent : Le CLI met votre agent à disposition comme un serveur HTTP sur le port 8087, avec debugpy attaché sur le port 5679.
2. Découvrir les agents : L’interface utilisateur extrait les agents/workflows disponibles à partir de /agentdev/entities.
3. Exécution de flux : Les entrées du chat sont envoyées à /v1/responses, qui diffuse des événements via SSE pour la visualisation en temps réel.
4. Activez la navigation dans le code : Double-cliquez sur les nœuds de flux de travail pour ouvrir le fichier source correspondant dans l’éditeur.
5. Activez la conversation avec l’agent local et affichez les réponses, appuyez sur des points d’arrêt pour le débogage, et ainsi de suite.

L’exemple de projet de flux de travail crée un fichier .env avec les variables d’environnement nécessaires. Créez ou mettez à jour le fichier .env avec vos informations d’identification Foundry :

1. Configurez vos variables d’environnement en fonction de votre système d’exploitation :

   • Windows (PowerShell)
   • Windows (invite de commandes)
   • 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"
   

Authentifier votre agent hébergé

L’exemple d’agent hébergé s’authentifie à l’aide de DefaultAzureCredential. Configurez votre environnement de développement pour fournir des informations d’identification via l’une des sources prises en charge, par exemple :

• Azure CLI (az login)
• connexion au compte Visual Studio Code
• connexion au compte Visual Studio
• Variables d’environnement pour un principal de service (AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET)

Confirmez l’authentification localement en exécutant les commandes Azure CLI az account show ou az account get-access-token avant d’exécuter l’exemple.

Vous pouvez exécuter l’agent hébergé en mode interactif ou en mode conteneur.

Exécuter votre agent hébergé en mode interactif

Exécutez l’agent hébergé directement pour le développement et le test :

dotnet restore
dotnet build
dotnet run

Exécuter votre agent hébergé en mode conteneur

Pour exécuter l’agent en mode conteneur :

1. Ouvrez la palette de commandes Visual Studio Code et exécutez la commande Microsoft Foundry: Open Container Agent Playground Locally.
2. Utilisez la commande suivante pour initialiser l’agent hébergé conteneurisé.

   dotnet restore
   dotnet build
   dotnet run
   

3. Envoyez une demande à l’agent via l’interface de terrain de jeu. Par exemple, saisissez une phrase telle que : « Créez un slogan pour un nouveau SUV électrique, abordable et agréable à conduire ».
4. Passez en revue la réponse de l’agent dans l’interface de terrain de jeu.

Visualiser l’exécution du flux de travail de l’agent hébergé

Le Kit de ressources Foundry pour Visual Studio Code fournit un graphique d’exécution en temps réel qui montre comment les agents de votre flux de travail interagissent et collaborent. Activez l’observabilité dans votre projet pour utiliser cette visualisation.

Ajoutez la référence suivante à votre fichier csproj :

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

Mettez à jour votre programme pour inclure l’extrait de code suivant :

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

Surveiller et visualiser votre workflow d’agent hébergé

Pour surveiller et visualiser l’exécution du flux de travail de votre agent hébergé en temps réel :

1. Ouvrez la palette de commandes (Ctrl+Maj+P).

2. Exécutez cette commande : >Microsoft Foundry: Open Visualizer for Hosted Agents.

Un nouvel onglet s’ouvre dans VS Code pour afficher le graphique d’exécution. La visualisation se met à jour automatiquement à mesure que votre flux de travail progresse pour afficher le flux entre les agents et leurs interactions.

Conflits de ports

Pour les conflits de ports, vous pouvez modifier le port de visualisation en le définissant dans les paramètres d’extension Foundry. Pour ce faire, procédez comme suit :

1. Dans la barre latérale gauche de VS Code, sélectionnez l’icône d’engrenage pour ouvrir le menu paramètres.
2. Sélectionnez Extensions>Microsoft Foundry Configuration.
3. Recherchez le paramètre et remplacez-le Hosted Agent Visualization Port par un numéro de port disponible.
4. Redémarrez VS Code pour appliquer les modifications.

Modifier le port dans le code

Pour tout conflit de ports, modifiez le port de visualisation en définissant la variable d’environnement FOUNDRY_OTLP_PORT . Mettez à jour le point de terminaison OTLP dans votre programme en conséquence.

Par exemple, pour remplacer le port par 4318, utilisez cette commande :

  $env:FOUNDRY_OTLP_PORT="4318"

Dans votre programme, mettez à jour le point de terminaison OTLP pour utiliser le nouveau numéro de port :

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

1. Ouvrez la palette de commandes Visual Studio Code et exécutez la commande Microsoft Foundry: Deploy Hosted Agent.
2. Configurez les paramètres de déploiement en sélectionnant votre espace de travail cible, en spécifiant le fichier de l’agent de conteneur (container.py) et en définissant d’autres paramètres de déploiement si nécessaire.
3. Une fois le déploiement réussi, l’agent hébergé apparaît dans la section Hosted Agents (Preview) de l’arborescence de l’extension Microsoft Foundry.
4. Sélectionnez l’agent déployé pour accéder à des informations détaillées et tester les fonctionnalités à l’aide de l’interface de terrain de jeu intégrée.

1. Ouvrez la palette de commandes Visual Studio Code et exécutez la commande Microsoft Foundry: Deploy Hosted Agent.
2. Configurez les paramètres de déploiement en sélectionnant votre espace de travail cible, en spécifiant le fichier de l’agent de conteneur (<your-project-name>.csproj) et en définissant d’autres paramètres de déploiement si nécessaire.
3. Une fois le déploiement réussi, l’agent hébergé apparaît dans la section Hosted Agents (Preview) de l’arborescence de l’extension Microsoft Foundry.
4. Sélectionnez l’agent déployé pour accéder à des informations détaillées et tester les fonctionnalités à l’aide de l’interface de terrain de jeu intégrée.