Create hosted agent workflows in the Microsoft Foundry Toolkit for Visual Studio Code extension

• Python 3.13 or higher.

• .NET 10 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 required packages:

   pip install -r requirements.txt
   

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:

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

AZURE_AI_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

Press F5 to start the local HTTP server with debugging enabled. The Foundry Toolkit Agent Inspector opens for interactive testing, and you can set breakpoints in your code.

To run the server without debugging:

python main.py

The agent listens on http://localhost:8088/. Send a test prompt with curl (or any HTTP client):

curl -sS -H "Content-Type: application/json" -X POST http://localhost:8088/responses \
    -d '{"input": "Write a haiku about deploying cloud applications.", "stream": false}'

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:FOUNDRY_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 Foundry Toolkit: 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 Microsoft Foundry Toolkit 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: >Foundry Toolkit: 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 Microsoft Foundry Toolkit for Visual Studio Code 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 Command Palette and select Foundry Toolkit: Deploy Hosted Agent. A deployment webview will open.
2. For "Deployment Method", select Code or Container.
3. If deploying with "Code", for "Package Mode", select Remote or Local.
4. If deploying with "Container", select either Default ACR, Custom ACR, or Customer ACR Image.
5. The "Agent Name" should auto-populate.
6. Select the "Next" button.
7. This "Review and Deploy" page should all auto-populate.
8. Select the "Deploy" button.
9. Open the Visual Studio Code Command Palette and run the Foundry Toolkit: Deploy Hosted Agent command.

1. Open the Visual Studio Code Command Palette and run the Foundry Toolkit: Deploy Hosted Agent command.
2. For "Deployment Method", select Code or Container.
3. If deploying with "Code", for "Package Mode", select Remote or Local.
4. If deploying with "Container", select either Default ACR, Custom ACR, or Customer ACR Image.
5. The "Agent Name" should auto-populate.
6. Select the "Next" button.
7. This "Review and Deploy" page should all auto-populate.
8. Select the "Deploy" button.