Creación de flujos de trabajo del agente hospedado en Visual Studio Code (versión preliminar)

• Python 3.12 o superior.

• .NET 9 SDK o posterior.

1. Cree un entorno virtual.

    python -m venv .venv
   

2. Active el entorno virtual.

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

3. Instale el siguiente paquete:

   pip install azure-ai-agentserver-agentframework
   

1. Vaya al directorio project y ejecute este comando para obtener los paquetes NuGet necesarios:

   dotnet restore
   

El proyecto de flujo de trabajo de ejemplo crea un archivo .env con las variables de entorno necesarias. Cree o actualice el archivo .env con las credenciales de Foundry:

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

MODEL_DEPLOYMENT_NAME=<your-model-deployment-name>

Autenticación del agente hospedado

El ejemplo del agente hospedado se autentica mediante DefaultAzureCredential. Configure el entorno de desarrollo para proporcionar credenciales a través de uno de los orígenes admitidos, por ejemplo:

• CLI de Azure (az login)
• Inicio de sesión de cuenta de Visual Studio Code
• inicio de sesión en la cuenta de Visual Studio
• Variables de entorno para una entidad de servicio (AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET)

Confirme la autenticación localmente ejecutando los comandos Azure CLI az account show o az account get-access-token antes de ejecutar el ejemplo.

Puede ejecutar el agente hospedado en modo interactivo o en modo contenedor.

Gestiona tu agente alojado en el Inspector de Agentes

Para ejecutar el agente hospedado localmente en Visual Studio Code, seleccione la clave F5. Esto abre el Inspector Agente y ejecuta tu solicitud.

Esto hará lo siguiente:

1. Inicie el servidor del agente: La CLI envuelve el agentdev agente como un servidor HTTP en el puerto 8087, con debugpy adjunto en el puerto 5679.
2. Detectar agentes: La interfaz de usuario captura los agentes o flujos de trabajo disponibles de /agentdev/entities.
3. Ejecución de flujo: Entradas de chat se envían a /v1/responses, que transmite eventos a través de SSE para la visualización en tiempo real.
4. Habilitación de la navegación de código: Haga doble clic en nodos de flujo de trabajo para abrir el archivo de código fuente correspondiente en el editor.
5. Habilitar el chat con el agente local y ver las respuestas, marcar puntos de interrupción para depurar, y así sucesivamente.

El proyecto de flujo de trabajo de ejemplo crea un archivo .env con las variables de entorno necesarias. Cree o actualice el archivo .env con las credenciales de Foundry:

1. Configure las variables de entorno en función del sistema operativo:

   • Windows (PowerShell)
   • Windows (símbolo del sistema)
   • 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"
   

Autenticación del agente hospedado

El ejemplo del agente hospedado se autentica mediante DefaultAzureCredential. Configure el entorno de desarrollo para proporcionar credenciales a través de uno de los orígenes admitidos, por ejemplo:

• CLI de Azure (az login)
• Inicio de sesión de cuenta de Visual Studio Code
• inicio de sesión en la cuenta de Visual Studio
• Variables de entorno para una entidad de servicio (AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET)

Confirme la autenticación localmente ejecutando los comandos Azure CLI az account show o az account get-access-token antes de ejecutar el ejemplo.

Puede ejecutar el agente hospedado en modo interactivo o en modo contenedor.

Ejecución del agente hospedado en modo interactivo

Ejecute el agente hospedado directamente para desarrollo y pruebas:

dotnet restore
dotnet build
dotnet run

Ejecución del agente hospedado en modo contenedor

Para ejecutar el agente en modo contenedor:

1. Abra la paleta de comandos Visual Studio Code y ejecute el comando Microsoft Foundry: Open Container Agent Playground Locally.
2. Use el siguiente comando para inicializar el agente hospedado en contenedor.

   dotnet restore
   dotnet build
   dotnet run
   

3. Envíe una solicitud al agente a través de la interfaz del área de juegos. Por ejemplo, escriba un mensaje como: "Crear un eslogan para un nuevo SUV eléctrico que sea asequible y divertido para conducir".
4. Revise la respuesta del agente en la interfaz del área de juegos.

Visualización de la ejecución del flujo de trabajo del agente hospedado

La extensión Foundry para Visual Studio Code proporciona un gráfico de ejecución en tiempo real que muestra cómo interactúan y colaboran los agentes del flujo de trabajo. Active la observabilidad en su proyecto para usar esta visualización.

Agregue la siguiente referencia al archivo 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>

Actualice el programa para incluir el siguiente fragmento de código:

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

Supervisión y visualización del flujo de trabajo del agente hospedado

Para supervisar y visualizar la ejecución del flujo de trabajo del agente hospedado en tiempo real:

1. Abra la paleta de comandos (Ctrl+Mayús+P).

2. Ejecute este comando: >Microsoft Foundry: Open Visualizer for Hosted Agents.

Se abre una nueva pestaña en VS Code para mostrar el gráfico de ejecución. La visualización se actualiza automáticamente a medida que avanza el flujo de trabajo, para mostrar el flujo entre los agentes y sus interacciones.

Conflictos de puertos

Para los conflictos de puertos, puede cambiar el puerto de visualización estableciendolo en la configuración de la extensión Foundry. Para hacer eso, siga estos pasos:

1. En la barra lateral izquierda de VS Code, seleccione el icono de engranaje para abrir el menú de configuración.
2. Seleccione Extensions>Microsoft Foundry Configuration.
3. Busque la Hosted Agent Visualization Port configuración y cámbiela a un número de puerto disponible.
4. Reinicie VS Code para aplicar los cambios.

Cambio del puerto en el código

Para cualquier conflicto de puertos, cambie el puerto de visualización estableciendo la variable de FOUNDRY_OTLP_PORT entorno. Actualice el punto de conexión de OTLP en el programa en consecuencia.

Por ejemplo, para cambiar el puerto a 4318, use este comando:

  $env:FOUNDRY_OTLP_PORT="4318"

En el programa, actualice el punto de conexión de OTLP para usar el nuevo número de puerto:

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

1. Abra la paleta de comandos Visual Studio Code y ejecute el comando Microsoft Foundry: Deploy Hosted Agent.
2. Configure las opciones de implementación seleccionando el área de trabajo de destino, especificando el archivo del agente de contenedor (container.py) y definiendo cualquier otro parámetro de implementación según sea necesario.
3. Tras una implementación correcta, el agente hospedado aparece en la sección Hosted Agents (Preview) de la vista de árbol de extensión Microsoft Foundry.
4. Seleccione el agente implementado para access información detallada y probar la funcionalidad mediante la interfaz de área de juegos integrada.

1. Abra la paleta de comandos Visual Studio Code y ejecute el comando Microsoft Foundry: Deploy Hosted Agent.
2. Configure las opciones de implementación seleccionando el área de trabajo de destino, especificando el archivo del agente de contenedor (<your-project-name>.csproj) y definiendo cualquier otro parámetro de implementación según sea necesario.
3. Tras una implementación correcta, el agente hospedado aparece en la sección Hosted Agents (Preview) de la vista de árbol de extensión Microsoft Foundry.
4. Seleccione el agente implementado para access información detallada y probar la funcionalidad mediante la interfaz de área de juegos integrada.