Quickstart: Deploy your first hosted agent

Learn how to deploy a containerized AI agent to Foundry Agent Service using the VS Code Foundry extension or Azure Developer CLI.

Quickstart: Deploy your first hosted agent using Azure Developer CLI

In this quickstart, you deploy a containerized AI agent with Foundry tools to Foundry Agent Service. The sample agent uses web search and optionally MCP tools to answer questions. By the end, you have a running hosted agent that you can interact with through the Foundry playground.

In this quickstart, you:

Set up an agent sample project with Foundry tools

Test the agent locally

Deploy to Foundry Agent Service

Interact with your agent in the playground

Clean up resources

Prerequisites

Before you begin, you need:

• An Azure subscription - Create one for free
• A Microsoft Foundry project with:
  • An Azure OpenAI model deployment (for example gpt-5)
    • This example uses gpt-5, you may need to use another model (such as gpt-4.1) depending on your quotas and limits.
  • (Optional) An MCP tool, if you have one you want to use.
• An Azure OpenAI resource
• Azure Developer CLI version 1.23.0 or later
• (Optional) Azure CLI version 2.80 or later
• Docker Desktop installed and running
• Python 3.10 or later

Hosted agents are currently in preview.

Step 1: Set up the sample project

Initialize a new project with the Foundry starter template and configure it with the agent-with-foundry-tools sample.

1. Initialize the starter template:

   azd init -t https://github.com/Azure-Samples/azd-ai-starter-basic
   

   This interactive command prompts you for an environment name (for example, my-hosted-agent). The environment name determines your resource group name (rg-my-hosted-agent).

If a resource group with the same name already exists, azd provision uses the existing group. To avoid conflicts, choose a unique environment name or delete the existing resource group first.

1. Initialize the agent sample:

   azd ai agent init -m https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/agent-framework/agent-with-foundry-tools/agent.yaml
   

   This interactive command prompts you for the following configuration values:

   • Azure subscription - select the Azure subscription where you want the Foundry resources to be created.
   • Location - select a region for the resources
   • Model SKU - select the SKU available for your region and subscription
   • Deployment name - enter a name for the model deployment
   • Container memory - enter a value for the memory allocation of the container or accept the defaults
   • Container CPU - enter a value for the CPU allocation of the container or accept the defaults
   • Minimum replicas - enter a value for the minimum replicas of the container
   • Max replicas - enter a value for the maximum replicas of the container

If you aren’t using an MCP server, comment out or remove the following lines in the agent.yaml file:

- name: AZURE_AI_PROJECT_TOOL_CONNECTION_ID
value: <CONNECTION_ID_PLACEHOLDER>

1. Provision the required Azure resources:

You need Contributor access on your Azure subscription for resource provisioning.

azd provision

This command takes about 5 minutes and creates the following resources:

Resource	Purpose	Cost
Resource group	Organizes all related resources in the same area	No cost
Model deployment	Model used by the agent	See Foundry pricing
Foundry project	Hosts your agent and provides AI capabilities	Consumption-based; see Foundry pricing
Azure Container Registry	Stores your agent container images	Basic tier; see ACR pricing
Log Analytics Workspace	Manage all log data in one place	No direct cost. See Log Analytics cost
Application Insights	Monitors agent performance and logs	Pay-as-you-go; see Azure Monitor pricing
Managed identity	Authenticates your agent to Azure services	No cost

Run azd down when you finish this quickstart to delete resources and stop incurring charges.

Step 2: Test the agent locally

Before deploying, verify the agent works locally.

1. Create and activate a Python virtual environment:

   Bash:

   python -m venv .venv
   source .venv/bin/activate
   

   PowerShell:

   python -m venv .venv
   .venv\Scripts\Activate.ps1
   

2. Install dependencies:

   pip install -r ./src/af-agent-with-foundry-tools/requirements.txt
   

3. Copy the required environment variables used in the agent code to a local .env file:

   Bash:

   azd env get-values > .env
   

   PowerShell:

   azd env get-values > .env
   

4. Add the AZURE_OPENAI_CHAT_DEPLOYMENT_NAME variable to your .env file with the name of the model deployment:

   AZURE_OPENAI_CHAT_DEPLOYMENT_NAME="gpt-5"

5. Run the agent locally:

   python ./src/af-agent-with-foundry-tools/main.py
   

   If the agent fails to start, check these common issues:

   Error	Solution
   AuthenticationError or DefaultAzureCredential failure	Run azd auth login again to refresh your session.
   ResourceNotFound	Verify your endpoint URLs match the values in the Foundry portal.
   DeploymentNotFound	Check the deployment name in Build > Deployments.
   Connection refused	Ensure no other process is using port 8088.

6. Test with a REST client. The agent runs on localhost:8088:

   Bash:

   curl -X POST http://localhost:8088/responses \
       -H "Content-Type: application/json" \
       -d '{"input": "What is Microsoft Foundry?"}'
   

   PowerShell:

   Invoke-RestMethod -Method Post `
       -Uri "http://localhost:8088/responses" `
       -ContentType "application/json" `
       -Body '{"input":"What is Microsoft Foundry?"}'
   

   You should see a response with web search results about Microsoft Foundry.

7. Stop the local server with Ctrl+C.

Step 3: Deploy to Foundry Agent Service

The azd up command combines three steps into one: provisioning infrastructure, packaging your application, and deploying it to Azure. This is equivalent to running azd provision, azd package, and azd deploy separately.

Before you begin, verify that Docker Desktop is running:

docker info

If this command fails, start Docker Desktop and wait for it to initialize before continuing.

Deploy your agent:

azd up

The first deployment will take longer because Docker needs to build the image.

Your hosted agent incurs charges while deployed. After you finish testing, complete Step 5: Clean up resources to delete resources and stop charges.

When finished, you will see a link to the Agent Playground and the endpoint for the agent which can be used to invoke the agent programmatically.

Deploying services (azd deploy)
                                                                                                                                                                     
  (✓) Done: Deploying service af-agent-with-foundry-tools
  - Agent playground (portal): https://ai.azure.com/nextgen/.../build/agents/af-agent-with-foundry-tools/build?version=1 
  - Agent endpoint: https://ai-account-<name>.services.ai.azure.com/api/projects/<project>/agents/af-agent-with-foundry-tools/versions/1

Step 4: Verify and test your agent

After deployment completes, verify your agent is running.

Test in the Foundry playground

Use the link provided in the output from the azd up command, or navigate to the agent in the portal:

1. Open the Foundry portal and sign in with your Azure account.

2. Select your project from the Recent projects list, or select All projects to find it.

3. In the left navigation, select Build to expand the menu, then select Agents.

4. In the agents list, find your deployed agent (it matches the agent name from your deployment).

5. Select the agent name to open its details page, then select Open in playground in the top toolbar.

6. In the chat interface, type a test message like “What is Microsoft Foundry?” and press Enter.

7. Verify that the agent responds with information from web search results. The response might take a few seconds as the agent queries external sources.

If the playground doesn’t load or the agent doesn’t respond, verify the agent status is Started using the CLI command below.

Find your resource names

To use the Azure CLI verification command, you need the following values:

Value	How to find it
Account name	In the Foundry portal, open your project and select Overview. The account name is the first part of your project endpoint URL (before .services.ai.azure.com). Alternatively, in the Azure portal, go to your resource group and find the Foundry resource—its name is the account name.
Project name	In the Foundry portal, open your project and copy the name from the Overview page.
Agent name	In the Foundry portal, go to Build > Agents. The agent name appears in the list.

You can also find these values in your azd output. After azd up completes, it displays the deployed resource names.

Check agent status

Run the following command with your values:

az cognitiveservices agent show \
    --account-name <your-account-name> \
    --project-name <your-project-name> \
    --name <your-agent-name>

Look for status: Started in the output.

If the status isn’t “Started”:

Status	Meaning	Action
Provisioning	Agent is still starting	Wait 2-3 minutes and check again.
Failed	Deployment error occurred	Run azd deploy to retry, or check logs in the Foundry portal.
Stopped	Agent was manually stopped	Run az cognitiveservices agent start to restart.
Unhealthy	Container is crashing	Check View deployment logs in the Foundry portal for errors.

Step 5: Clean up resources

To avoid charges, delete the resources when you’re finished.

This command permanently deletes all Azure resources created in this quickstart, including the Foundry project, Container Registry, Application Insights, and your hosted agent. This action can’t be undone.

To preview what will be deleted before confirming:

azd down --preview

When you’re ready to delete, run:

azd down

The cleanup process takes approximately 2-5 minutes.

To verify resources were deleted, open the Azure portal, go to your resource group (for example, rg-my-hosted-agent), and confirm the resources no longer appear. If the resource group is empty, you can delete it as well.

Troubleshooting

If you encounter issues, try these solutions for common problems:

Issue	Solution
azd init fails	Run azd version to verify version 1.23.0+. Update with winget upgrade Microsoft.Azd (Windows) or brew upgrade azd (macOS).
Docker build errors	Ensure Docker Desktop is running. Run docker info to verify.
SubscriptionNotRegistered error	Register providers: az provider register --namespace Microsoft.CognitiveServices
AuthorizationFailed during provisioning	Request Contributor role on your subscription or resource group.
Agent doesn’t start locally	Verify environment variables are set and run az login to refresh credentials.
AcrPullUnauthorized error	Grant AcrPull role to the project’s managed identity on the container registry.
Model not found in catalog	Fork the sample agent.yaml and change the model deployment to one available in your subscription like gpt-4.1. Then remove the AZURE_LOCATION value in the .azure/<environment name>/.env file. Re-run the azd ai agent init command with your forked agent.yaml file.

What you learned

In this quickstart, you:

• Set up a hosted agent sample with Foundry tools (web search and MCP)
• Tested the agent locally using the hosting adapter
• Deployed to Foundry Agent Service using azd up
• Verified your agent in the Foundry playground

Deploy your first hosted agent using VS Code

Use the Microsoft Foundry for Visual Studio Code extension to deploy your agent code to Foundry from the IDE which just a few clicks. See the VS Code extension documentation for more information.

Next steps

Now that you’ve deployed your first hosted agent, learn how to:

Manage hosted agent lifecycle

Customize your agent with additional capabilities:

• Connect MCP tools to extend agent functionality
• Use function calling to integrate custom logic
• Add file search to search your documents
• Enable code interpreter to run Python code

You can see a full list of available tools in the tool catalog article.

Related content

• What are hosted agents?
• Deploy a hosted agent
• Agent development lifecycle
• Python hosted agent samples