Quickstart: Deploy your first hosted agent

• Azure Developer CLI version 1.23.0 or later
• Docker Desktop installed and running

• Visual Studio Code
• Microsoft Foundry for Visual Studio Code extension

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 in an empty directory:

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

   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.

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

   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>
   

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

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-4.1"

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.

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 1: Create a Foundry project

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

1. Open the Command Palette (Ctrl+Shift+P) and select Microsoft Foundry: Create Project.

2. Select your Azure subscription.

3. Create a new resource group or select an existing one.

4. 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 extension in VS Code to deploy a model to Foundry.

1. Open the Command Palette (Ctrl+Shift+P) and select Microsoft Foundry: Open Model Catalog.

2. Browse the model catalog or search for gpt-4.1 and select the Deploy button.

3. 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 extension in VS Code to scaffold a new hosted agent project.

1. Open the Command Palette (Ctrl+Shift+P) and select Microsoft Foundry: Create new Hosted Agent.

2. Select either the Single Agent or Multi-Agent Workflow template

3. Select a programming language, Python or C#.

4. Choose the existing gpt-4.1 model you deployed in the previous step.

5. Choose the folder where you want your project files to be saved.

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

The required packages are:

• azure-ai-agentserver-agentframework - Agent Framework and AgentServer SDK

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:

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

This will:

1. Start the HTTP server with debugging enabled
2. Open the AI Toolkit Agent Inspector for interactive testing
3. 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.

1. Open the Command Palette (Ctrl+Shift+P) and select Microsoft Foundry: Deploy Hosted Agent.

2. Select the CPU and Memory configuration for the Hosted Agent container.

3. In the dialog that appears, select the Confirm and Deploy button.

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

Check agent status

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

1. Select your hosted agent from the Hosted Agents (Preview) tree view.

2. Select a version (v1) to open the detail page.

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

Test in the playground using VS Code

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

1. Select your hosted agent from the Hosted Agents (Preview) tree view.

2. Select a version (v1) to open the detail page.

3. Select the Playground option and type a message and send to test your agent.

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

View the container logs of your agent

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

1. Select your hosted agent from the Hosted Agents (Preview) tree view.

2. Select a version (v1) to open the detail page.

3. Select the Logs button on the right to open the log viewer.