How to install Foundry Dev Pack and deploy a first hosted agent

Foundry Dev Pack is the installer Microsoft documents for a machine that will build hosted agents. It puts the terminal tools on the machine in one setup, and it adds the VS Code toolkit or Foundry Canvas only when those apps are already installed. This walkthrough stays on that install and the Azure Developer CLI path in the hosted-agent quickstart: initialize the basic Agent Framework sample in code deploy mode, run it locally, then deploy and invoke it in Foundry Agent Service.

Install Foundry Dev Pack

The pack prepares a machine for Foundry work from a terminal, an IDE, or a coding agent. Depending on the environment, it can install:

Foundry Command Line Tools: Azure CLI (az), Azure Developer CLI (azd), and the Microsoft Foundry Extension for azd.
Microsoft Foundry Skill, for reusable guidance that coding agents can follow.
Microsoft Foundry Toolkit for Visual Studio Code, and only if VS Code is present.
Foundry Canvas (preview), and only if the GitHub Copilot App is present.

Windows:

winget install Microsoft.FoundryDevPack

macOS:

brew install --cask microsoft/foundry/devpack && foundry-devpack install

Linux:

curl -fsSL https://aka.ms/foundry-devpack-install.sh | bash

The quickstart’s Azure Developer CLI path expects that pack to have installed azd at version 1.27.1 or later, plus the Foundry extensions that path uses. The Dev Pack notes also say you can run azd ai agent init to create a first agent from a template. The command below is the quickstart’s full form, with the sample and code deploy mode set.

You need an Azure subscription. If the Foundry project already exists, you need Foundry Project Manager at project scope. If you will create a project, you need the Owner role at resource group scope.

The quickstart lists Python 3.13 or later beside the Azure Developer CLI sign-in. Use that version for this sample. After a project exists, the local-run guide lists Python 3.10 or later, .NET 8 or later, or Node.js as runtimes, and its troubleshooting table ties failed dependency installs to a missing Python 3.10 or later or .NET 8 or later. These pages do not say which pivot owns the 3.13 line exclusively, so meet the stricter quickstart figure.

azd auth login

Initialize the sample

In an empty directory, initialize from the basic Agent Framework sample:

azd ai agent init -m "https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/agent-framework/responses/01-basic/azure.yaml" --deploy-mode code

The interactive flow asks for:

Agent name. Accept the default, agent-framework-agent-basic-responses, or customize it.
Foundry project. Create a new project, or use an existing one.
Tenant, subscription, and location.
Model. The documented default is gpt-5.4-mini, or another model you can access.
Model version. The default option.
Model SKU. An option with quota that is not Batch, usually Standard or GlobalStandard.
Deployment capacity. The documented default is 10.
Deployment name. The documented default is gpt-5.4-mini.

On success the quickstart says you see AI agent definition added to your azd project successfully! Then change into the new folder:

cd agent-framework-agent-basic-responses

The deploy example later on the same page prints the service name basic-agent. That string is not the default folder name above. If your output uses different names, follow the output. These pages do not say which name is canonical when they differ.

Provision

Provision the resources defined in azure.yaml:

azd provision

Run locally

From the project directory:

azd ai agent run

On the quickstart path, this creates a virtual environment, installs dependencies, starts the agent with the startupCommand in azure.yaml, and opens the agent inspector in the browser so you can chat with it.

The local-run guide adds that the same command auto-detects Python, .NET, or Node.js, and starts the server on localhost:8088. It injects variables from the default azd environment — the one set with azd env select, or created during azd ai agent init — including FOUNDRY_PROJECT_ENDPOINT, AZURE_SUBSCRIPTION_ID, and values set with azd env set.

That guide also documents a custom port when the default is unavailable, and a way to name one agent when the project defines several. Copy the port example from that page rather than guessing a number. The multi-agent example there is not the basic sample’s default name:

azd ai agent run my-agent

To override startupCommand for that start, the guide shows the following. It also notes that startupCommand is the default command for local development and for container startup when deployed:

azd ai agent run --start-command "python app.py"

In a second terminal, send a prompt to the local server instead of a deployed endpoint:

azd ai agent invoke --local "Hello, what can you do?"

The same guide’s direct check is:

curl -X POST http://localhost:8088/responses \
     -H "Content-Type: application/json" \
     -d '{"input": "Hello, what can you do?"}'

If the local process needs a value such as an API key, set it on the active azd environment. The documented example:

azd env set OPENAI_KEY <value>

azd stores those values in .azure/<env>/.env, and .azure is gitignored by default. A local run reads the env map declared in the azure.ai.agent service in azure.yaml and resolves ${VAR} placeholders from the active environment. Copy that service block from the local-run guide rather than reconstructing it. For a secret that should not live in a local .env file, the guide says to store it in a Foundry project connection and reference it from the env map with the connections placeholder shown there. The platform resolves that placeholder at runtime.

The local-run table maps common failures this way: AuthenticationError means run azd auth login; ResourceNotFound means endpoint URLs do not match Foundry portal values; DeploymentNotFound means check the deployment name in azure.yaml; connection refused on port 8088 means another process is using the port; dependencies that fail to install mean Python 3.10 or later or .NET 8 or later is missing.

Deploy and invoke

Deploy after the local chat looks right. azd packages the source as a ZIP file and uploads it to Foundry. Foundry resolves dependencies, builds the hosted agent remotely, and deploys it:

azd deploy

Finished output in the quickstart includes a playground link and an agent endpoint. Copy those from your own run. The documented example uses placeholders and the service name basic-agent:

Deploying services (azd deploy)

  Done: Deploying service basic-agent
  - Agent playground (portal): https://ai.azure.com/.../build/agents/basic-agent/build?version=1
  - Agent endpoint: https://ai-account-<name>.services.ai.azure.com/api/projects/<project>/agents/basic-agent/versions/1

Send the quickstart prompt to the deployed agent:

azd ai agent invoke "Write a haiku about deploying cloud applications."

The quickstart says you should see a haiku within a few seconds. To stream container logs while you interact with the agent:

azd ai agent monitor --follow

What to try next

Run azd ai agent run, then the local invoke, before azd deploy. If port 8088 is already taken, use the custom-port example on the local-run page. If the project defines more than one agent, pass that agent name on the run command, as in the example above. If invoke must send a custom body, or the agent uses the invocations protocol instead of the default responses protocol, the local-run guide shows these commands. For an invocations agent, that guide says to check the sample README or the handler to learn the payload shape. It does not publish that payload here.

azd ai agent invoke --local -f request.json

azd ai agent invoke --local --protocol invocations -f request.json

Keep the playground and endpoint URLs from your own azd deploy output, and reread the local-run guide before you change startupCommand or the env map.