Quickstart: Deploy your first hosted agent - Microsoft Foundry Docs

Prerequisites

Before you begin, you need:

An Azure subscription. If you don’t have one, 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.

Clean up resources

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

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.
`create_version_from_code` fails with `Hosted agent provisioning failed`	Check that `main.py` and `requirements.txt` are at the root of the zip you uploaded, and verify that the model deployment name in `.env` exists in the target Foundry project.
`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.
Uploaded and routed a hosted agent version with the Python SDK or scaffolded the sample with Azure Developer CLI.
Tested the agent locally.
Deployed the agent to Foundry Agent Service.
Sent test prompts from the Python SDK, Azure Developer CLI, VS Code, Foundry canvas, or a coding agent that uses the Microsoft Foundry Skill.

Next step

Build a toolbox and use it with a hosted agent

⌘I