I'm going to save you the afternoon I lost the first time I tried to get an agent from my laptop to a live endpoint on Microsoft Foundry.
The official docs are thorough. They're also scattered across six different pages, three blog posts and a GitHub repo where the README was updated mid-week without anyone mentioning it. What I wanted was one page with every command, every config file, every gotcha, in order, that actually worked when I ran it.
This is that page.
By the end of this tutorial you'll have a working AI agent deployed to Microsoft Foundry with a live endpoint you can invoke from your terminal. The whole process takes two commands once you understand the setup. The setup is where people lose time, so that's where I'm going to be annoyingly specific.
What you're building
A hosted AI agent running on Microsoft Foundry, deployed through the Azure Developer CLI. The agent gets its own endpoint, managed identity, RBAC configuration and monitoring pipeline. You'll be able to invoke it from the terminal, test it in the Foundry portal playground and connect a frontend chat app to it.
The infrastructure is defined as code, Bicep templates generated in your repo that you own, version control and customize.
Prerequisites (check these before starting the clock)
Don't skip this section. Every "it doesn't work" message I've seen in GitHub issues traces back to a missing prerequisite.
You need an Azure subscription with permission to create resource groups and Foundry resources. Contributor access on the subscription is what you need for provisioning.
Install the Azure Developer CLI if you haven't already. On macOS: brew tap azure/azd && brew install azd. On Windows: winget install microsoft.azd. On Linux: curl -fsSL https://aka.ms/install-azd.sh | bash. Verify with azd version, you need 1.23.7 or later.
Install the Azure CLI as well: az --version to check. The AZD agent extension uses it under the hood for certain operations.
Sign in to Azure:
azd auth login
This opens a browser for authentication. If you're working in a headless environment or SSH session, use azd auth login --use-device-code instead.
One critical gotcha before you start: region availability. Hosted agents on Foundry currently operate in North Central US. If you deploy to a different region, provisioning will succeed but your agent won't run. This isn't a warning you'll see in the CLI output, it just silently doesn't work. Use northcentralus as your location. Save yourself the debugging session.
Step 1: Initialize the agent project
Create an empty directory and initialize the starter template:
mkdir my-first-agent && cd my-first-agent
azd init -t Azure-Samples/azd-ai-starter-basic --location northcentralus
When prompted, enter an environment name. This becomes the name prefix for your Azure resources. Keep it short and lowercase, something like my-agent-dev.
This command does two things that matter. First, it installs the azd ai agent extension automatically if you don't have it. You don't need to run azd extension install azure.ai.agents separately, though you can if you prefer being explicit. Second, it scaffolds the full infrastructure definition in your repo.
After init completes, look at what was generated:
ls infra/
You'll see main.bicep, the entry point that wires together all resources. This creates a Foundry account (the top-level container), a Foundry project (where your agent lives), model deployment configuration (GPT-4o by default), managed identity with RBAC role assignments and an Azure Container Registry for hosting the agent container.
The other critical file is azure.yaml, the AZD service map that ties your agent code to the Foundry host. Open it and familiarize yourself with the structure. This is where you define services, model deployments and connections declaratively.
Step 2: Deploy everything with one command
azd up
That's it. This single command orchestrates the entire deployment workflow. It provisions the infrastructure defined in the Bicep files, builds your container image, pushes it to Azure Container Registry, creates the Foundry project, deploys model endpoints, creates and starts your hosted agent and configures managed identity with the correct RBAC roles.
First run takes 4–6 minutes. Subsequent deployments are faster because the infrastructure already exists.
When it finishes, azd up prints a direct link to your agent in the Foundry portal. It also outputs several environment values you'll need later, agent name, version, account name, resource group and the Foundry endpoint URL. Save these or know that you can retrieve them later with azd env get-values.
Step 3: Test your agent
You have three ways to test and I'd suggest doing all three because they each catch different problems.
From the terminal:
azd ai agent invoke --message "What suites are available at the downtown Seattle hotel?"
This sends a prompt to your remote agent endpoint directly from the CLI. It preserves conversation context across turns, so you can have a multi-turn conversation. If you get a coherent response about hotel availability, your agent is live and serving.
From the Foundry portal, click the link from the azd up output. Navigate to your project, open the Agents section, find your deployed agent and launch the playground. Type a test query and confirm the response.
From a frontend chat app and this is where it gets interesting for anyone building something real:
git clone https://github.com/puicchan/chat-app-foundry
cd chat-app-foundry
Set the environment variables that wire the app to your published agent:
azd env set AZURE_AI_AGENT_NAME "seattle-hotel-agent"
azd env set AZURE_AI_AGENT_VERSION "<version-from-azd-output>"
azd env set AI_ACCOUNT_NAME "<your-ai-account-name>"
azd env set AI_ACCOUNT_RESOURCE_GROUP "<your-resource-group>"
azd env set AZURE_AI_FOUNDRY_ENDPOINT "<your-foundry-endpoint>"
Replace the placeholders with values from your azd up output. Run azd env get-values in your agent project directory if you didn't save them.
Step 4: Local development loop
This is the part that makes the workflow actually productive for daily development. You don't want to redeploy every time you change a prompt or adjust tool logic.
azd ai agent run
This starts your agent locally, connecting to the remote Azure resources defined in your environment. Edit code, restart, invoke, repeat. The invoke command is smart about routing, when a local agent is running, it targets that automatically.
Pair it with invoke in a second terminal:
azd ai agent invoke --message "Test my latest changes"
This is your tight feedback loop. Local execution with remote resource connectivity.
Step 5: Monitor in production
Once your agent is handling real traffic, you'll need logs:
# Recent container console logs
azd ai agent monitor
# Last 20 lines
azd ai agent monitor --tail 20
# System events (container start/stop)
azd ai agent monitor --type system
# Stream session logs in real time
azd ai agent monitor --session <session-id> --follow
The platform automatically injects an Application Insights connection string into your agent container, enabling OpenTelemetry tracing by default. Open the Application Insights resource in the Azure portal and navigate to Transaction Search or Performance for distributed traces.
The gotchas that will waste your time
I'm listing these because each one cost me or someone on our team real debugging time.
The region thing bears repeating. North Central US only for hosted agents as of May 2026. The docs mention this but the CLI doesn't enforce it at init time.
If you're on a Mac M4, you might hit Docker image build issues. The container image needs to target the correct architecture. Check the GitHub issues on the azure-dev repo, there are active threads with workarounds.
If you selected a sample template that includes tools and you aren't using an MCP server, comment out or remove the AZURE_AI_PROJECT_TOOL_CONNECTION_ID placeholder in your agent.yaml. Leaving it in causes a provisioning error that's not immediately obvious from the error message.
RBAC role names were recently renamed. Foundry User, Foundry Owner, Foundry Account Owner and Foundry Project Manager were previously named Azure AI User, Azure AI Owner, Azure AI Account Owner and Azure AI Project Manager. If you're cross-referencing older docs or Stack Overflow answers, the old names might not resolve. The role IDs and permissions are unchanged, just the display names.
The Microsoft Agent Framework hit v1.0 in late April 2026. If you're following tutorials written before that date, credential handling, session patterns and several response types have been renamed. Earlier beta code will break without migration.
Cleaning up
When you're done experimenting:
azd down
This removes the resource group and all provisioned resources so you avoid ongoing charges. Do this every time you finish a session unless you're running a persistent deployment.
Where this fits in the bigger picture
This tutorial gets you from zero to a live agent endpoint. That's the starting line, not the finish. For production deployments you'll want retry logic and fallback models, evaluation pipelines that gate deployment on passing automated tests, multi-agent architectures where specialized agents handle different aspects of a workflow and proper CI/CD integration using the --no-prompt flag for non-interactive environments.
The deploy AI agent Microsoft Foundry AZD guide covers how we extend beyond this basic deployment into production-hardened agent systems.
Azure Foundry is one deployment target. If you're evaluating which agentic framework to build on before choosing your deployment infrastructure, we benchmarked the top agentic AI frameworks 2026, covering where each one shines, where it breaks down and which deployment patterns they support. Worth reading before you commit to an architecture.
Published by Dextra Labs, AI Consulting and Enterprise Agent Development
Top comments (0)