Quickstart: Deploy your first hosted agent

Prerequisites

Before you begin, you need:

An Azure subscription--Create one for free.
If you have an existing Foundry project, you need Foundry Project Manager at project scope. If you need to create a new Foundry project, you need the Owner role at resource group scope. For the full role matrix, see Hosted agent permissions reference.
Python 3.13 or later.

Azure Developer CLI (AZD) 1.25.3 or later.
The azd microsoft.foundry extension. Install and verify the extension after AZD is installed:
```
azd ext install microsoft.foundry
```

A coding agent host with the Microsoft Foundry Skill installed.
Azure CLI and Azure Developer CLI (AZD) installed and authenticated:
```
az login
azd auth login
```

Step 1: Initialize sample agent

Initialize a new hosted agent using the basic Agent Framework sample in an empty directory:

azd ai agent init -m "https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/agent-framework/responses/01-basic/agent.manifest.yaml" --deploy-mode code

The interactive flow prompts for:

Agent name: Customize the name or accept the default, agent-framework-agent-basic-responses
Foundry Project: Select Create a new Foundry project or Use an existing Foundry project
Tenant: Select your Azure tenant
Subscription: Select your Azure subscription
Location: Select an Azure region
Model: Select the default, gpt-4.1-mini, or another model you can access.
Model Version: Select the default option.
Model SKU: Select an option with available quota that isn't Batch, usually Standard or GlobalStandard
Deployment capacity: Select the default, 10
Deployment name: Select the default, gpt-4.1-mini

When complete, you should see AI agent definition added to your azd project successfully!. Change directory into newly created agent folder.

cd agent-framework-agent-basic-responses

Step 2: Provision Azure resources

Provision the resources defined in azure.yaml:

azd provision

Step 3: Test the agent locally

azd ai agent run

This command creates a virtual environment, installs dependencies, launches the agent using the startupCommand defined in azure.yaml and opens the agent inspector in your browser so you can chat with 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 5: Invoke your agent

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.
(Optional) Stream container logs while you interact with the agent:
```
azd ai agent monitor --follow
```

Step 1: Create a Foundry project

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

Step 2: Deploy a model

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

Step 3: Create a hosted agent project

Open the Command Palette and select Foundry Toolkit: Create new Hosted Agent.
Select the Python as the language.
For "Framework", select Agent Framework.
Select Responses API as the protocol type.
Select Basic as the sample code.
Select the "Next" button.
Choose a folder for the project files and enter a name for the agent.
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.
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

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

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

Step 7: Invoke your agent

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

Step 1: Open a workspace with the Foundry Skill

Open an empty folder in your coding agent host, such as GitHub Copilot in Visual Studio Code, Copilot CLI, or Claude Code. Confirm that the microsoft-foundry skill is available before you ask the coding agent to create Azure resources.

If the skill isn't available, follow Use the Microsoft Foundry Skill in coding agents.

Step 2: Ask the skill to create the hosted agent

Ask your coding agent to use the skill for the complete hosted-agent workflow:

Use the Microsoft Foundry Skill hosted-agent quick-start workflow to create my
first hosted agent end to end. Verify my environment first, and stop if I need
to sign in myself. Use Python 3.13, Agent Framework, the Responses API, the
Basic sample, and code deployment. Create a new Foundry project unless I provide
an existing project. Use the model deployment from the Basic sample unless I
provide an existing deployment. Test the agent locally, deploy it to Foundry
Agent Service, and invoke it with: "Write a haiku about deploying cloud
applications."

The coding agent should inspect the available Foundry tools when MCP tools are available, load the hosted agent quick-start workflow, and ask for or default missing values such as the subscription, region, project name, and whether to use an existing Foundry project.

Step 3: Review and approve the plan

Review the plan, files, commands, Azure resources, and role assignments the coding agent proposes.
To match this quickstart, choose Python 3.13, Agent Framework, Responses API, Basic sample code, and Code deployment.
Approve cost-bearing resource creation only after you verify the subscription, region, resource group, model deployment, and quota.
If the coding agent asks you to authenticate, run az login and azd auth login yourself, and then ask the coding agent to continue.

Step 4: Let the skill scaffold and test the agent

Let the coding agent create the hosted agent project, provision resources when you choose a new Foundry project, write local environment values, prepare the local environment, and run a local smoke test. For Python agents, the skill workflow uses azd ai agent run to install dependencies during the first local run.

The workflow should also add the project guidance file required by the coding agent host and sanity-check the generated project configuration before the local test.

If your coding agent host can't keep a local server running for the smoke test, use the Azure Developer CLI tab in this article for the local test commands. You can continue to deployment only after you decide to validate the agent remotely instead.

Step 5: Deploy and invoke the hosted agent

After the local smoke test succeeds, ask your coding agent to finish the deployment and remote validation:

Continue with the Microsoft Foundry Skill workflow. Deploy the hosted agent to
Foundry Agent Service, show the deployment status and playground link, and invoke
it remotely with: "Write a haiku about deploying cloud applications." If the
skill workflow requires evaluation suite generation before the final summary,
submit the generation job and show me the follow-up eval command.

When the workflow completes, the coding agent should show the hosted agent name, version, deployment status, endpoint, playground link, resources created, the response to the test prompt, and any evaluation follow-up command.

Clean up resources

Delete the resources when you're finished so you stop incurring charges.

Warning

azd down permanently deletes every resource in the resource group, including the Foundry project, model deployments, Container Registry, Application Insights, and the hosted agent. If you provisioned into a resource group that contains other resources, those resources are deleted too.

azd down

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

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

Warning

Deleting the resource group permanently removes everything in it, including the Foundry project, Container Registry, Application Insights, and the hosted agent.

The Microsoft Foundry Skill doesn't delete resources by itself. It can help your coding agent identify the resources that this quickstart created and choose the right cleanup method. You or your coding agent still run the cleanup command after you review and approve it.

In the hosted agent project folder, ask your coding agent to review cleanup:

Use the Microsoft Foundry Skill to identify the Azure resources created for
this quickstart. Confirm whether azd down is the right cleanup method for
this project, and show me the resources before any deletion command runs.

If the hosted agent project was created with azd and the resource group contains only quickstart resources, run:
```
azd down
```
Approve deletion only after you verify the resource group and resources that the command lists.

If your coding agent can't run cleanup commands, use the Azure Developer CLI tab in this article or delete the resource group from the Azure portal.

Troubleshooting

Issue	Solution
`SubscriptionNotRegistered`	Register the provider: `az provider register --namespace Microsoft.CognitiveServices`.
`AuthorizationFailed` during provisioning	Request the Contributor role on the subscription or resource group.
`AuthenticationError` or `DefaultAzureCredential` failure	To refresh credentials, run `azd auth logout` and then `azd auth login`.
`ResourceNotFound` or `DeploymentNotFound`	Verify the endpoint URL and model deployment name in the Foundry portal under Build > Deployments.
`Connection refused` on local run	Ensure no other process is using port 8088.
`azd ai agent init` fails	Run `azd version` to verify 1.25.0 or later. Update with `winget upgrade Microsoft.Azd` (Windows) or `brew upgrade azd` (macOS). Run `azd ext list` and upgrade the agent extension with `azd ext upgrade azure.ai.agents` to get 0.1.34-preview or later.
Microsoft Foundry Toolkit extension not found	Install the Microsoft Foundry Toolkit for Visual Studio Code from the Marketplace and switch to the prerelease channel.
Coding agent doesn't load the Microsoft Foundry Skill	Install or reload the skill by following Use the Microsoft Foundry Skill in coding agents.
Coding agent can't run the local smoke test	Use the Azure Developer CLI or VS Code tab in this article for local testing. Continue to remote validation only after you review why local validation isn't available.
Local run fails on Windows ARM64 with build errors for `aiohttp`, `grpcio`, `cryptography`, or `httptools`	Prebuilt arm64 wheels aren't published for these packages, and source builds require Microsoft C++ Build Tools. As a workaround, skip Step 3 and validate the agent remotely with `azd deploy` followed by `azd ai agent invoke`.

For the full permission and role-assignment matrix, see Hosted agent permissions reference.

What you learned

In this quickstart, you:

Scaffolded a hosted agent project from the Basic agent sample.
Tested the agent locally.
Deployed the agent to Foundry Agent Service.
Sent test prompts from Azure Developer CLI, VS Code, or a coding agent that uses the Microsoft Foundry Skill.

Next step

Build a toolbox and use it with a hosted agent

Feedback

Was this page helpful?

Last updated on 2026-07-06