Skip to main content
In this quickstart, you:
  • Scaffold a hosted agent project
  • Test the agent locally
  • Deploy to Foundry Agent Service
  • Chat with the agent in the playground
  • Clean up resources Choose your preferred development experience to get started, VS Code or CLI.
This document is for Hosted Agents on the new backend and requires azd ai agent version 0.1.27-preview or later. For the legacy experience that uses Azure Container Apps, continue using 0.1.25-preview.Hosted agents are currently in preview.

​
Prerequisites

Before you begin, you need:

​
Required permissions

You need the Foundry Project Manager role at project scope to create and deploy hosted agents. The Azure Developer CLI and the Visual Studio Code extension handle the remaining role assignments (project managed identity, agent identity, and Azure Container Registry (ACR) pull) automatically when you also have Owner or User Access Administrator on the subscription. If you don’t have those subscription-level roles, ask an administrator to assign the roles described in Hosted agent permissions reference.
The Foundry RBAC roles were recently renamed. Foundry User, Foundry Owner, Foundry Account Owner, and Foundry Project Manager were previously named Azure AI User, Azure AI Owner, Azure AI Account Owner, and Azure AI Project Manager. You might still see the previous names in some places while the rename rolls out. The role IDs and core permissions are unchanged by the rename.

​
Verify and test your agent

​
Test in the Foundry playground

The Foundry portal includes a shared playground you can use to test the agent.
  1. Open the Foundry portal and sign in.
  2. Select your project from Recent projects or All projects.
  3. In the left navigation, select Build > Agents.
  4. Select your agent, then select Open in playground.
  5. Enter a prompt such as Write a haiku about deploying cloud applications. and press Enter. If the playground doesn’t load or the agent doesn’t respond, verify the agent status is Started on the agent detail page.

​
Clean up resources

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

​
Troubleshooting

IssueSolution
SubscriptionNotRegisteredRegister the provider: az provider register --namespace Microsoft.CognitiveServices.
AuthorizationFailed during provisioningRequest the Contributor role on the subscription or resource group.
AuthenticationError or DefaultAzureCredential failureTo refresh credentials, run azd auth logout and then azd auth login.
ResourceNotFound or DeploymentNotFoundVerify the endpoint URL and model deployment name in the Foundry portal under Build > Deployments.
AcrPullUnauthorizedGrant the AcrPull role to the project’s managed identity on the Container Registry.
Connection refused on local runEnsure no other process is using port 8088.
azd ai agent init failsRun 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 foundInstall the Microsoft Foundry Toolkit for Visual Studio Code from the Marketplace and switch to the prerelease channel.
Local run fails on Windows ARM64 with build errors for aiohttp, grpcio, cryptography, or httptoolsPrebuilt 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 both the CLI (or VS Code) and the Foundry playground.

​
Next steps

Manage hosted agent lifecycle

Customize your agent with additional capabilities: Use the Microsoft Foundry Skill in your coding agent to standardize deployment, evaluation, and troubleshooting workflows.

​
Related content