Creare flussi di lavoro dell'agente ospitato in Visual Studio Code (anteprima)

• Python 3.12 o versione successiva.

• .NET 9 SDK o versione successiva.

1. Creare un ambiente virtuale.

    python -m venv .venv
   

2. Attivare l'ambiente virtuale.

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

3. Installare il pacchetto seguente:

   pip install azure-ai-agentserver-agentframework
   

1. Passare alla directory del progetto ed eseguire questo comando per ottenere i pacchetti NuGet necessari:

   dotnet restore
   

Il progetto flusso di lavoro di esempio crea un file con estensione env con le variabili di ambiente necessarie. Creare o aggiornare il file .env con le credenziali Foundry:

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

MODEL_DEPLOYMENT_NAME=<your-model-deployment-name>

Autenticare l'agente ospitato

L'esempio dell'agente ospitato esegue l'autenticazione usando DefaultAzureCredential. Configurare l'ambiente di sviluppo per fornire le credenziali tramite una delle origini supportate, ad esempio:

• interfaccia della riga di comando di Azure (az login)
• Accesso all'account di Visual Studio Code
• Accesso all'Account di Visual Studio
• Variabili di ambiente per un'entità servizio (AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET)

Verificare l'autenticazione in locale eseguendo i comandi interfaccia della riga di comando di Azure az account show o az account get-access-token prima di eseguire l'esempio.

È possibile eseguire l'agente ospitato in modalità interattiva o in modalità contenitore.

Esegui l'agente ospitato in Agent Inspector

Per eseguire l'agente ospitato in locale in Visual Studio Code, selezionare la chiave F5. Si apre l'Agent Inspector ed esegue la tua applicazione.

In questo modo:

1. Avvia il server agente: L'interfaccia della riga di comando incapsula il tuo agente agentdev come server HTTP sulla porta 8087, con debugpy collegato sulla porta 5679.
2. Individuare gli agenti: L'interfaccia utente recupera agenti/flussi di lavoro disponibili da /agentdev/entities.
3. Esecuzione del flusso: Gli input di chat passano a /v1/responses, che trasmette gli eventi tramite SSE per la visualizzazione in tempo reale.
4. Abilitare lo spostamento nel codice: Fare doppio clic sui nodi del flusso di lavoro per aprire il file di origine corrispondente nell'editor.
5. Abilitare la chat con l'agente locale e visualizzare le risposte, raggiungere i punti di interruzione per il debug e così via.

Il progetto flusso di lavoro di esempio crea un file con estensione env con le variabili di ambiente necessarie. Creare o aggiornare il file .env con le credenziali Foundry:

1. Configurare le variabili di ambiente in base al sistema operativo:

   • Windows (PowerShell)
   • Windows (Prompt dei comandi)
   • 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"
   

Autenticare l'agente ospitato

L'esempio dell'agente ospitato esegue l'autenticazione usando DefaultAzureCredential. Configurare l'ambiente di sviluppo per fornire le credenziali tramite una delle origini supportate, ad esempio:

• interfaccia della riga di comando di Azure (az login)
• Accesso all'account di Visual Studio Code
• Accesso all'Account di Visual Studio
• Variabili di ambiente per un'entità servizio (AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET)

Verificare l'autenticazione in locale eseguendo i comandi interfaccia della riga di comando di Azure az account show o az account get-access-token prima di eseguire l'esempio.

È possibile eseguire l'agente ospitato in modalità interattiva o in modalità contenitore.

Eseguire l'agente ospitato in modalità interattiva

Eseguire l'agente ospitato direttamente per lo sviluppo e il test:

dotnet restore
dotnet build
dotnet run

Eseguire l'agente ospitato in modalità contenitore

Per eseguire l'agente in modalità contenitore:

1. Aprire il riquadro comandi Visual Studio Code ed eseguire il comando Microsoft Foundry: Open Container Agent Playground Locally.
2. Usare il comando seguente per inizializzare l'agente ospitato in contenitori.

   dotnet restore
   dotnet build
   dotnet run
   

3. Invia una richiesta all'agente tramite l'interfaccia playground. Ad esempio, immettere un prompt come: "Crea uno slogan per un nuovo SUV elettrico che è conveniente e divertente da guidare".
4. Esaminare la risposta dell'agente nell'interfaccia del playground.

Visualizzare l'esecuzione del flusso di lavoro dell'agente ospitato

Foundry Toolkit for Visual Studio Code fornisce un grafico di esecuzione in tempo reale che mostra come gli agenti nel flusso di lavoro interagiscono e collaborano. Abilitare l'osservabilità nel progetto per usare questa visualizzazione.

Aggiungere il riferimento seguente al file 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>

Aggiornare il programma per includere il frammento di codice seguente:

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

Monitorare e visualizzare il flusso di lavoro dell'agente ospitato

Per monitorare e visualizzare l'esecuzione del flusso di lavoro dell'agente ospitato in tempo reale:

1. Aprire il riquadro comandi (CTRL+MAIUSC+P).

2. Eseguire questo comando: >Microsoft Foundry: Open Visualizer for Hosted Agents.

Viene aperta una nuova scheda in VS Code per visualizzare il grafico di esecuzione. La visualizzazione viene aggiornata automaticamente man mano che il flusso di lavoro avanza, per mostrare il flusso tra gli agenti e le relative interazioni.

Conflitti di porta

Per i conflitti di porta, è possibile modificare la porta di visualizzazione impostandola nelle impostazioni dell'estensione Foundry. A tale scopo, seguire questa procedura:

1. Nella barra laterale sinistra di VS Code selezionare l'icona a forma di ingranaggio per aprire il menu delle impostazioni.
2. Selezionare Extensions>Microsoft Foundry Configuration.
3. Individuare l'impostazione Hosted Agent Visualization Port e modificarla in un numero di porta disponibile.
4. Riavviare VS Code per applicare le modifiche.

Modificare la porta nel codice

Per eventuali conflitti di porta, modificare la porta di visualizzazione impostando la FOUNDRY_OTLP_PORT variabile di ambiente. Aggiorna l'endpoint OTLP nel programma di conseguenza.

Ad esempio, per modificare la porta in 4318, usare questo comando:

  $env:FOUNDRY_OTLP_PORT="4318"

Nel programma aggiornare l'endpoint OTLP per usare il nuovo numero di porta:

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

1. Aprire il riquadro comandi Visual Studio Code ed eseguire il comando Microsoft Foundry: Deploy Hosted Agent.
2. Configurare le impostazioni di distribuzione selezionando l'area di lavoro di destinazione, specificando il file dell'agente contenitore (container.py) e definendo eventuali altri parametri di distribuzione in base alle esigenze.
3. Al termine della distribuzione, l'agente ospitato viene visualizzato nella sezione Hosted Agents (Preview) della visualizzazione albero dell'estensione Microsoft Foundry.
4. Selezionare l'agente distribuito per accedere a informazioni dettagliate e funzionalità di test usando l'interfaccia del playground integrato.

1. Aprire il riquadro comandi Visual Studio Code ed eseguire il comando Microsoft Foundry: Deploy Hosted Agent.
2. Configurare le impostazioni di distribuzione selezionando l'area di lavoro di destinazione, specificando il file dell'agente contenitore (<your-project-name>.csproj) e definendo eventuali altri parametri di distribuzione in base alle esigenze.
3. Al termine della distribuzione, l'agente ospitato viene visualizzato nella sezione Hosted Agents (Preview) della visualizzazione albero dell'estensione Microsoft Foundry.
4. Selezionare l'agente distribuito per accedere a informazioni dettagliate e funzionalità di test usando l'interfaccia del playground integrato.