Debugging Foundry hosted agents v2 with Python

Introduction

The new azd ai agent init command provisions a Python project 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 file needed for debugging.

Thankfully, this is a quick fix.

The solution

One configuration file needs to be added to the .vscode folder at the root of your workspace.

launch.json

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

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Python: Agent",
            "type": "debugpy",
            "request": "launch",
            "program": "${workspaceFolder}/src/seattle-hotel-agent/main.py",
            "console": "integratedTerminal",
            "cwd": "${workspaceFolder}/src/seattle-hotel-agent",
            "envFile": "${workspaceFolder}/.env",
            "justMyCode": true,
            "env": {
                "FOUNDRY_PROJECT_ENDPOINT": "https://foundry-project.services.ai.azure.com/api/projects/environment-name"
            }
        }
    ]
}

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

• seattle-hotel-agent: replace with the name of your agent.
• 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).

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 Python 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 one configuration file. 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!