Quickstart: Deploy your first hosted agent

• Azure Developer CLI version 1.23.0 or later

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

Step 1: Set up the sample project

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

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

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

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

   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.

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

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

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.

Verify agent status

Check the status of your deployed agent:

azd ai agent show

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:

azd ai agent monitor

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.