Quickstart: Deploy your first hosted agent

• Azure Developer CLI (AZD) 1.25.0 or later.

• The azd ai agent extension, version 0.1.34-preview or later. Install and verify the extension after AZD is installed:

  azd ext install azure.ai.agents
  

• Sign in to Azure:

  azd auth login
  

• Visual Studio Code.
• Microsoft Foundry Toolkit for Visual Studio Code.

Step 1: Scaffold the sample project

Initialize a new hosted agent project in an empty directory and choose the recommended options for each prompt:

azd ai agent init

The interactive flow prompts for:

• Language--Select Python.
• Starter template--Select Basic agent (Responses, Agent Framework, Python)
• Agent name--Choose the default agent-framework-agent-basic-responses
• Deployment type--Select Container deploy
• Runtime--Select Python 3.13
• Entry point--Chose the default main.py
• Dependency resolution--Select Remote build (dependencies installed on server during deployment)
• Foundry Project--Select Create a new Foundry project
• Azure Tenant--Select your Azure direction for the subscription you want to use
• Azure subscription--The subscription that hosts the Foundry resources
• Location--A region for the resources
• Model deployment--Select the default Use 'gpt-4.1-mini' (from manifest)
• Model version--Select the default 2025-04-14 (default)
• Model SKU--A SKU available in your region and subscription and has quota available
• Deployment capacity--Select the default 10
• Deployment name--Choose the default gpt-4.1-mini
• Container resources--Select the default 0.5 cores, 1Gi memory

When complete, you should see AI agent definition added to your azd project successfully!.

Step 2: Provision Azure resources

Provision the resources defined in azure.yaml:

azd provision

This step takes a few minutes and creates the following resources. To run provision and deploy together, you can use azd up instead.

Step 3: Test the agent locally

1. Start the agent:

   azd ai agent run
   

   This command creates a virtual environment, installs dependencies, and launches the agent using the startupCommand defined in azure.yaml. Preview packages can produce pip dependency version-conflict warnings during setup. These warnings are nonblocking. The agent starts and responds correctly despite them.

2. In a separate terminal, send a test prompt:

   azd ai agent invoke --local "Write a haiku about deploying cloud applications."
   

   You should see a haiku response from the agent.

Step 4: Deploy to Foundry Agent Service

Build and deploy the agent container:

azd deploy

When the command finishes, the output shows links to the agent playground and the agent endpoint:

Deploying services (azd deploy)

  Done: Deploying service basic-agent
  - Agent playground (portal): https://ai.azure.com/.../build/agents/basic-agent/build?version=1
  - Agent endpoint: https://ai-account-<name>.services.ai.azure.com/api/projects/<project>/agents/basic-agent/versions/1

Step 1: Create a Foundry project

1. Open the Command Palette (Ctrl+Shift+P) and select Foundry Toolkit: 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.

Step 2: Deploy a model

1. Open the Command Palette and select Foundry Toolkit: Open Model Catalog.
2. Search for gpt-4.1 and select Deploy.
3. On the model deployment page, select Deploy to Microsoft Foundry.

Step 3: Create a hosted agent project

1. Open the Command Palette and select Foundry Toolkit: Create new Hosted Agent.
2. Select the Python as the language.
3. For "Framework", select Agent Framework.
4. Select Responses API as the protocol type.
5. Select Basic as the sample code.
6. Select the "Next" button.
7. Choose a folder for the project files and enter a name for the agent.
8. For "Environment Setup", choose Set up with Microsoft Foundry, the content should auto-populate with the project and model you created in step 1 and 2.
9. Select the "Create" button.

A new VS Code window opens with the project as the active workspace.

Step 4: Install dependencies

Create a virtual environment and install the requirements.

For macOS or Linux:

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

For Windows (PowerShell):

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt

Step 5: Test the agent locally

Press F5 to start the local HTTP server with debugging enabled. The Foundry Toolkit Agent Inspector opens for interactive testing, and you can set breakpoints in your code.

To run the server without debugging:

python main.py

The agent listens on http://localhost:8088/. Send a test prompt with curl (or any HTTP client):

curl -sS -H "Content-Type: application/json" -X POST http://localhost:8088/responses \
    -d '{"input": "Write a haiku about deploying cloud applications.", "stream": false}'

Step 6: Deploy to Foundry Agent Service

1. Open the Command Palette and select Foundry Toolkit: Deploy Hosted Agent. A deployment webview will open.
2. For "Deployment Method", select Code.
3. Select Remote as the package mode.
4. The "Agent Name" should auto-populate.
5. Select the "Next" button.
6. This "Review and Deploy" page should all auto-populate.
7. Select the "Deploy" button.

When deployment completes, the agent appears under Hosted Agents (Preview) in the Foundry Toolkit explorer.

1. Check the agent status:

   azd ai agent show
   

   Verify that the agent is "Active".

2. Send the same prompt to the deployed agent:

   azd ai agent invoke "Write a haiku about deploying cloud applications."
   

   You should see a haiku response within a few seconds.

3. (Optional) Stream container logs while you interact with the agent:

   azd ai agent monitor --follow
   

   The platform injects an Application Insights connection string into the container, so OpenTelemetry traces also appear in the Application Insights resource provisioned earlier. View them in the Azure portal under Investigate > Transaction search or Performance.

1. In the Foundry Toolkit explorer, expand Hosted Agents (Preview) and select your agent. The detail page shows the status under Deployment Details.
2. Select the Playground tab and send a test prompt such as Write a haiku about deploying cloud applications..

azd down

azd lists the resources it deletes and prompts for confirmation. Cleanup takes about 2-5 minutes.

1. Open the Azure portal and navigate to the resource group that contains your agent.
2. Select Delete resource group, type the resource group name to confirm, and select Delete.