Quickstart: Deploy your first hosted agent

Deploy an AI agent to Foundry Agent Service with Azure Developer CLI, Python, C#, Visual Studio Code, Foundry Skills, or Foundry Canvas.

In this quickstart, you deploy and invoke a hosted agent in Foundry Agent Service. Choose the development tool or SDK that fits your workflow.

If you use a coding agent like GitHub Copilot, the Microsoft Foundry Skill can help you pick a development path and complete the setup, deployment, and invocation steps.

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.

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.27.1 or later. Update with winget upgrade Microsoft.Azd (Windows) or brew upgrade azd (macOS). Run azd ext show azure.ai.agents to verify 1.0.0-beta.4 or later. Upgrade with azd ext upgrade azure.ai.agents.
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 or C# 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 or C# 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

Related content

• What are hosted agents?
• Deploy a hosted agent
• Author azure.yaml for hosted agents