Debugging Foundry hosted agents v2 with dotnet and Microsoft Agent Framework

Introduction

The new azd ai agent init command provisions a dotnet project using the Microsoft Agent Framework targeting Microsoft Foundry. Out of the box, this is a great way to get started quickly, but one friction point immediately emerges: pressing F5 in Visual Studio Code does not work. The project lacks the VS Code configuration files needed for debugging.

Thankfully, this is a quick fix.

The solution

Two configuration files need to be added to the .vscode folder at the root of your workspace.

tasks.json

This file tells VS Code how to build the project before launching it.

{
    "version": "2.0.0",
    "tasks": [
        {
            "type": "dotnet",
            "task": "build",
            "group": "build",
            "problemMatcher": [],
            "label": "dotnet: build"
        }
    ]
}

launch.json

This file configures the debugger itself. It sets up the launch configuration, points to the built assembly, and most importantly injects the environment variables needed to connect the agent to your Microsoft Foundry project.

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Agent Launch",
            "type": "coreclr",
            "request": "launch",
            "preLaunchTask": "dotnet: build",
            "program": "${workspaceFolder}/src/local-tools/bin/Debug/net10.0/local-tools.dll",
            "args": [],
            "cwd": "${workspaceFolder}",
            "stopAtEntry": false,
            "console": "internalConsole",
            "env": {
                "DOTNET_ENVIRONMENT": "Development",
                "FOUNDRY_PROJECT_ENDPOINT": "https://foundry-project.services.ai.azure.com/api/projects/environment-name"
            },
            "envFile": "${workspaceFolder}/.azure/environment-name/.env"
        }
    ]
}

Note: A few values in launch.json need to be updated to match your environment:

• environment-name: replace with the name of the environment azd created (this usually matches the resource group or agent name).
• foundry-project: replace with the name of your Microsoft Foundry project (visible in the portal under the project endpoints).
• local-tools.dll: replace with the actual assembly name of your project (determined by the AssemblyName property in your .csproj file, defaults to the project name).

Invoking the agent

Once the configuration is in place, set your breakpoints anywhere in the agent code and press F5 to start the debugger. The agent will launch locally and wait for a prompt.

To send a prompt to the locally running agent, use the following command:

azd ai agent invoke "my prompt" --local

The breakpoints will be hit as expected and you can inspect variables, step through the code, and diagnose any issue just as you would with any other dotnet application.

Conclusion

The lack of out-of-the-box VS Code debug support for the azd ai agent init templates is a minor inconvenience that is easily fixed with two configuration files. Once in place, the full debugging experience is available and you can iterate on your agent logic quickly. I hope this saves you some time!