Quickstart: Deploy your first hosted agent

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. Choose your preferred deployment method to get started.

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
(Optional) An MCP tool, if you have one you want to use.
Python 3.10 or later

Azure Developer CLI version 1.24.0 or later

Note

Hosted agents are currently in preview.

Required Permission

You need Azure AI Project Manager at project scope to create and deploy hosted agents. This role includes both the data plane permissions to create agents and the ability to assign the Azure AI User role to the platform-created agent identity. The agent identity needs Azure AI User on the project to access models and artifacts at runtime.

If you use azd or the VS Code extension, the tooling handles most RBAC assignments automatically, including:

Ensure that the Foundry Project's managed identity has ACR pull role on the Azure Container Registry you use. if you prefer and have Owner or "User Access Administrator" access then the tooling azd/vscode can also do this assignment for you. Azure AI User for the platform-created agent identity (runtime model and tool access)

Step 1: Set up the sample project

Warning

This document is for Hosted Agents on the new backend and requires azd ai agent version 0.1.26-preview or later. For the legacy experience that uses Azure Container Apps, please continue using 0.1.25-preview.

Install the Azure Developer CLI agent extension and initialize a new hosted agent project.

Install the ai agent extension for the Azure Developer CLI:
```
azd ext install azure.ai.agents
```
To verify the extension is installed, run:
```
azd ext list
```
Initialize a new hosted agent project:
```
azd ai agent init
```
When prompted, select Start new from a template. The interactive flow guides you through the following configuration:
- Environment name — determines your resource group name (for example, my-hosted-agent creates rg-my-hosted-agent).
- Azure subscription — select the 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 size — select the CPU and memory allocation or accept the defaults.
Note

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.
Important

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>
```
Alternatively you can also use this cmd:
```
azd init -t Azure-Samples/azd-ai-starter-basic
```
The -t flag means template.

You're telling azd to use this specific template:

Azure-Samples/azd-ai-starter-basic - a starter project from Microsoft’s sample repository

The AI starter basic template sets up a minimal AI-powered app using Azure services. Typically it includes:
- A simple backend (often Python or Node.js)
- Integration with Azure OpenAI Service
- Infrastructure to deploy:
  - Web app (Azure App Service)
  - AI resources
- Preconfigured environment for quick deployment
Tip

If you're running in a non-interactive environment such as a CI/CD pipeline or an SSH session, use the --no-prompt flag with azd ai agent init. You must also supply all required values as command-line flags rather than responding to interactive prompts.

Provision the required Azure resources:

Note

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

Tip

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.

Start the agent locally:

azd ai agent run

This command automatically sets up the environment, installs dependencies, and starts the agent. It uses the startupCommand defined in azure.yaml to launch your agent.

Note

Preview packages can produce pip dependency version-conflict warnings during setup. These warnings are non-blocking — the agent starts and responds correctly despite them.

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.

In a separate terminal, send a test message to the local agent:
```
azd ai agent invoke --local "What is Microsoft Foundry?"
```
You should see a response with web search results about Microsoft Foundry.

Step 3: Deploy to Foundry Agent Service

Since you already provisioned infrastructure in Step 1, deploy your agent code to Azure:

azd deploy

The agent container is built remotely, so Docker Desktop isn't required on your machine.

Note

The azd deploy command assigns Azure RBAC roles to the agent's Agent identity. This role assignment requires Owner or User Access Administrator permissions on your subscription, in addition to the Contributor role required for provisioning.

Warning

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

When finished, the output shows a link to the Agent Playground and the endpoint for invoking 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

Important

Make sure you are using the prelease version of the Microsoft Foundry Toolkit extension and the Foundry extension in VS Code.

In your VS Code extensions page, choose Foundry Toolkit extension and Foundry extension and switch to the pre-release version.

Step 1: Create a Foundry project

Use the Microsoft Foundry Toolkit extension in VS Code to create a new Microsoft Foundry Project resource.

Open the Command Palette (Ctrl+Shift+P) and select Microsoft Foundry: Create Project.
Select your Azure subscription.
Create a new resource group or select an existing one.
Enter a name for the Foundry Project resource.

Once the project creation is complete, continue to the next step and deploy a model.

Step 2: Deploy a model

Use the Microsoft Foundry Toolkit extension in VS Code to deploy a model to Foundry.

Open the Command Palette (Ctrl+Shift+P) and select Microsoft Foundry: Open Model Catalog.
Browse the model catalog or search for gpt-4.1 and select the Deploy button.
In the Model deployment page, select the Deploy to Microsoft Foundry button.

Once the model is deployed successfully, move on to the next step and create a Hosted Agent project

Step 3: Create a Hosted Agent project

Use the Microsoft Foundry Toolkit extension in VS Code to scaffold a new hosted agent project.

Open the Command Palette (Ctrl+Shift+P) and select Microsoft Foundry: Create new Hosted Agent.
Select the Framework you want to use.
Select a programming language, Python or C#.
Select either Responses API or Invoke API.
Select the sample code you want to use.
Choose the folder where you want your project files to be saved.
Enter a name for the hosted agent.

A new VS Code window will launch with the new agent project folder as the active workspace.

Step 4: Install dependencies

It's recommended to use a virtual environment to isolate project dependencies:

macOS/Linux:

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

Windows (PowerShell):

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

Installing Dependencies

Install the required Python dependencies using pip:

pip install -r requirements.txt

See the requirement.txt for a list of required packages.

Step 5: Test the agent locally

Run and test your agent before deploying.

Option 1: Press F5 (Recommended)

Press F5 in VS Code to start debugging. Alternatively, you can use the VS Code debug menu:

Open the Run and Debug view (Ctrl+Shift+D / Cmd+Shift+D)
Select "Debug Local Workflow HTTP Server" from the dropdown
Click the green Start Debugging button (or press F5)

This will:

Start the HTTP server with debugging enabled
Open the Foundry Toolkit Agent Inspector for interactive testing
Allow you to set breakpoints and inspect the workflow

Option 2: Run in Terminal

Run as HTTP server (default):

python main.py

This will start the hosted agent locally on http://localhost:8088/.

PowerShell (Windows):

$body = @{
   input = "I need a hotel in Seattle from 2025-03-15 to 2025-03-18, budget under `$200 per night"
    stream = $false
} | ConvertTo-Json

Invoke-RestMethod -Uri http://localhost:8088/responses -Method Post -Body $body -ContentType "application/json"

Bash/curl (Linux/macOS):

curl -sS -H "Content-Type: application/json" -X POST http://localhost:8088/responses \
   -d '{"input": "Find me hotels in Seattle for March 20-23, 2025 under $200 per night","stream":false}'

The agent will use the get_available_hotels tool to search for available hotels matching your criteria.

Step 6: Deploy to Foundry Agent Service

Deploy your agent directly from VS Code.

Open the Command Palette (Ctrl+Shift+P) and select Microsoft Foundry: Deploy Hosted Agent.
Select "Default ACR"
Select the CPU and Memory configuration for the Hosted Agent container.

Switch to the Microsoft Foundry Toolkit explorer by selecting the icon on the left. The agent appears in the Hosted Agents (Preview) tree view sidebar after deployment completes.

Verify and test your agent

After deployment completes, verify your agent is running.

Check agent status

Check the status of your agent to confirm it's running.

Select your hosted agent from the Hosted Agents (Preview) tree view.
Select the agent you just deployed

The detail page shows the Status under the Container Details section.

Test in the playground using VS Code

Microsoft Foundry Toolkit for VS Code includes an integrated playground to chat and interact with your agent.

Select your hosted agent from the Hosted Agents (Preview) tree view.
Select the Playground option and type a message and send to test your agent.

Verify agent status

Check the status of your deployed agent:

azd ai agent show

To display the output in table format:

azd ai agent show --output table

If your project has multiple agent services, specify the agent name as a positional argument:

azd ai agent show <agent-name>

Tip

Find <agent-name> in the azure.yaml file under the services: section.

Test the deployed agent

Send a test message to your deployed agent:

azd ai agent invoke "What is Microsoft Foundry?"

You should see a response with web search results about Microsoft Foundry. The response might take a few seconds as the agent queries external sources.

View agent logs

Monitor your agent's live logs:

# Fetch recent container console logs
azd ai agent monitor

# Fetch the last N lines of console logs
azd ai agent monitor --tail 20

# Fetch system event logs (container start and stop events)
azd ai agent monitor --type system

# Stream session logs in real time
azd ai agent monitor --session <session-id> --follow

If your project has multiple agent services, specify the agent name as a positional argument:

azd ai agent monitor <agent-name> --follow

Test in the Foundry playground

Navigate to the agent in the Foundry portal:

Open the Foundry portal and sign in with your Azure account.
Select your project from the Recent projects list, or select All projects to find it.
In the left navigation, select Build to expand the menu, then select Agents.
In the agents list, find your deployed agent (it matches the agent name from your deployment).
Select the agent name to open its details page, then select Open in playground in the top toolbar.
In the chat interface, type a test message like "What is Microsoft Foundry?" and press Enter.
Verify that the agent responds with information from web search results. The response might take a few seconds as the agent queries external sources.

Tip

If the playground doesn't load or the agent doesn't respond, verify the agent status is Started using the Container Details page described above.

Clean up resources

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

Warning

This command permanently deletes all Azure resources in the resource group, including the Foundry project, model deployments, Container Registry, Application Insights, and your hosted agent. This action can't be undone. If you're using an existing resource group that contains other resources, use caution — azd down removes everything in the group, not just resources created by this quickstart.

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.

Warning

Deleting resources permanently removes 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 delete your resources, open the Azure portal, navigate to your resource group, and delete it along with all contained resources.

To verify resources were deleted, open the Azure portal, go to your resource group, 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
`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.

For comprehensive details about all permissions and role assignments involved in hosted agent deployment, see Hosted agent permissions reference.

Issue	Solution
`azd ai agent init` fails	Run `azd version` to verify version 1.23.0+. Update with `winget upgrade Microsoft.Azd` (Windows) or `brew upgrade azd` (macOS). Verify the agent extension is installed with `azd ext list`.
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.

View the container logs of your agent

You can check the console and system logs of the container to troubleshoot issues.

Select your hosted agent from the Hosted Agents (Preview) tree view.
Select the "Playground" tab of your hosted agent
Select the "Logs" section in the session details.

View the session files of your agent

You can view all the files stored on the home directory of your ADC based agent

Select your hosted agent from Hosted Agents (Preview) tree view.
Select the "Playground" tab of your hosted agent
Select the "files" section in the session details.

You can download, upload, and create folders within the current folder, clicking on a folder will step into the folder, and clicking on the top navbar will step back into that folder.

Issue	Solution
Extension not found	Install the Microsoft Foundry Toolkit for VS Code extension from the VS Code Marketplace.

What you learned

In this quickstart, you:

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

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.

คำติชม

หน้านี้มีประโยชน์หรือไม่

Last updated on 2026-04-22

แชร์ผ่าน

Quickstart: Deploy your first hosted agent

Prerequisites

Required Permission

Step 1: Set up the sample project

Step 2: Test the agent locally

Step 3: Deploy to Foundry Agent Service

Step 1: Create a Foundry project

Step 2: Deploy a model

Step 3: Create a Hosted Agent project

Step 4: Install dependencies

Installing Dependencies

Step 5: Test the agent locally

Option 1: Press F5 (Recommended)

Option 2: Run in Terminal

Step 6: Deploy to Foundry Agent Service

Verify and test your agent

Check agent status

Test in the playground using VS Code

Verify agent status

Test the deployed agent

View agent logs

Test in the Foundry playground

Clean up resources

Troubleshooting

View the container logs of your agent

View the session files of your agent

What you learned

Next steps

Related content

คำติชม

แหล่งทรัพยากรเพิ่มเติม