Create hosted agent workflows in Visual Studio Code (preview)

• Python 3.12 or higher.

• .NET 9 SDK or later.

1. Create virtual environment.

    python -m venv .venv
   

2. Activate the virtual environment.

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

3. Install the following package:

   pip install azure-ai-agentserver-agentframework
   

1. Go to your project directory and run this command to get the necessary NuGet packages:

   dotnet restore
   

The sample workflow project creates an .env file with the necessary environment variables. Create or update the .env file with your Foundry credentials:

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

MODEL_DEPLOYMENT_NAME=<your-model-deployment-name>

Authenticate your hosted agent

The hosted agent sample authenticates using DefaultAzureCredential. Configure your development environment to provide credentials via one of the supported sources, for example:

• Azure CLI (az login)
• Visual Studio Code account sign-in
• Visual Studio account sign-in
• Environment variables for a service principal (AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET)

Confirm authentication locally by running either the Azure CLI az account show or az account get-access-token commands before running the sample.

You can run the hosted agent in interactive mode or container mode.

Run your hosted agent in the Agent Inspector

To run your hosted agent locally in Visual Studio Code, select the F5 key. This opens the Agent Inspector and executes your application.

This will:

1. Start the agent server: The agentdev CLI wraps your agent as an HTTP server on port 8087, with debugpy attached on port 5679.
2. Discover agents: The UI fetches available agents/workflows from /agentdev/entities.
3. Stream execution: Chat inputs go to /v1/responses, which streams back events via SSE for real-time visualization.
4. Enable code navigation: Double-click workflow nodes to open the corresponding source file in the editor.
5. Enable chatting with the local agent and viewing responses, hitting breakpoints for debugging, and so on.

The sample workflow project creates an .env file with the necessary environment variables. Create or update the .env file with your Foundry credentials:

1. Set up your environment variables based on your operating system:

   • Windows (PowerShell)
   • Windows (command prompt)
   • 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"
   

Authenticate your hosted agent

The hosted agent sample authenticates using DefaultAzureCredential. Configure your development environment to provide credentials via one of the supported sources, for example:

• Azure CLI (az login)
• Visual Studio Code account sign-in
• Visual Studio account sign-in
• Environment variables for a service principal (AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET)

Confirm authentication locally by running either the Azure CLI az account show or az account get-access-token commands before running the sample.

You can run the hosted agent in interactive mode or container mode.

Run your hosted agent in interactive mode

Run the hosted agent directly for development and testing:

dotnet restore
dotnet build
dotnet run

Run your hosted agent in container mode

To run the agent in container mode:

1. Open the Visual Studio Code Command Palette and execute the Microsoft Foundry: Open Container Agent Playground Locally command.
2. Use the following command to initialize the containerized hosted agent.

   dotnet restore
   dotnet build
   dotnet run
   

3. Submit a request to the agent through the playground interface. For example, enter a prompt such as: "Create a slogan for a new electric SUV that's affordable and fun to drive."
4. Review the agent's response in the playground interface.

Visualize hosted agent workflow execution

The Foundry for Visual Studio Code extension provides a real-time execution graph that shows how agents in your workflow interact and collaborate. Enable observability in your project to use this visualization.

Add the following reference to your csproj file:

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

Update your program to include the following code snippet:

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

Monitor and visualize your hosted agent workflow

To monitor and visualize your hosted agent workflow execution in real time:

1. Open the command palette (Ctrl+Shift+P).

2. Run this command: >Microsoft Foundry: Open Visualizer for Hosted Agents.

A new tab opens in VS Code to display the execution graph. The visualization updates itself automatically as your workflow progresses, to show the flow between agents and their interactions.

Port conflicts

For port conflicts, you can change the visualization port by setting it in the Foundry extension settings. To do that, follow these steps:

1. In the left sidebar of VS Code, select the gear icon to open the settings menu.
2. Select Extensions > Microsoft Foundry Configuration.
3. Locate the Hosted Agent Visualization Port setting and change it to an available port number.
4. Restart VS Code to apply the changes.

Change port in code

For any port conflicts, change the visualization port by setting the FOUNDRY_OTLP_PORT environment variable. Update the OTLP endpoint in your program accordingly.

For example, to change the port to 4318, use this command:

  $env:FOUNDRY_OTLP_PORT="4318"

In your program, update the OTLP endpoint to use the new port number:

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

1. Open the Visual Studio Code Command Palette and run the Microsoft Foundry: Deploy Hosted Agent command.
2. Configure the deployment settings by selecting your target workspace, specifying the container agent file (container.py), and defining any other deployment parameters as needed.
3. Upon successful deployment, the hosted agent appears in the Hosted Agents (Preview) section of the Microsoft Foundry extension tree view.
4. Select the deployed agent to access detailed information and test functionality using the integrated playground interface.

1. Open the Visual Studio Code Command Palette and run the Microsoft Foundry: Deploy Hosted Agent command.
2. Configure the deployment settings by selecting your target workspace, specifying the container agent file (<your-project-name>.csproj), and defining any other deployment parameters as needed.
3. Upon successful deployment, the hosted agent appears in the Hosted Agents (Preview) section of the Microsoft Foundry extension tree view.
4. Select the deployed agent to access detailed information and test functionality using the integrated playground interface.