|
| 1 | +--- |
| 2 | +title: Set up your environment for Azure AI Foundry Agent Service |
| 3 | +titleSuffix: Azure AI Foundry |
| 4 | +description: Use this guide to set up your agent environment |
| 5 | +manager: nitinme |
| 6 | +author: aahill |
| 7 | +ms.author: aahi |
| 8 | +ms.reviewer: fosteramanda |
| 9 | +ms.service: azure-ai-agent-service |
| 10 | +ms.topic: how-to |
| 11 | +ms.date: 05/09/2025 |
| 12 | +ms.custom: azure-ai-agents |
| 13 | +--- |
| 14 | + |
| 15 | +# Set up your environment |
| 16 | + |
| 17 | +Creating your first agent with Azure AI Agent Service is a two-step process: |
| 18 | +1. Set up your agent environment. |
| 19 | +1. Create and configure your agent using either the SDK of your choice or the Azure Foundry Portal. |
| 20 | + |
| 21 | +Use this article to learn more about setting up your agents. |
| 22 | + |
| 23 | +### Required permissions |
| 24 | + |
| 25 | +| Action | Required Role | |
| 26 | +|------------------------------------------------------------------------|----------------------------------| |
| 27 | +| Create an account and project | Azure AI Account Owner | |
| 28 | +| **Standard Setup Only:** Assign RBAC for required resources (Cosmos DB, Search, Storage, etc.) | Role Based Access Administrator | |
| 29 | +| Create and edit agents | Azure AI User | |
| 30 | + |
| 31 | +## Set up your agent environment |
| 32 | +To get started, you need an account and a project. |
| 33 | +Agents are scoped at the project level, which ensures data isolation—agents within the same project share access to the same resources. |
| 34 | + |
| 35 | +### Prerequisites |
| 36 | + |
| 37 | +* An Azure subscription - [Create one for free](https://azure.microsoft.com/free/cognitive-services). |
| 38 | +* Ensure that the individual creating the account and project has the **Azure AI Account Owner** role at the subscription scope |
| 39 | +* If configuring **Standard Setup**, the same individual must also have permissions to assign roles to required resources (Cosmos DB, Search, Storage). |
| 40 | + * The built-in role needed is **Role Based Access Administrator**. |
| 41 | + * Alternatively, having the **Owner** role at the subscription level also satisfies this requirement. |
| 42 | + * The key permission needed is: `Microsoft.Authorization/roleAssignments/write` |
| 43 | + |
| 44 | +### Choose your setup |
| 45 | +Azure AI Foundry Agent Service offers three environment configuration modes to suit different needs: |
| 46 | + |
| 47 | +- **Basic Setup**: |
| 48 | + |
| 49 | + This setup is compatible with OpenAI Assistants and manages agent states using the platform's built-in storage. It includes the same tools and capabilities as the Assistants API, with added support for non-OpenAI models and tools such as Azure AI Search, Bing, and SharePoint. |
| 50 | + |
| 51 | +- **Standard Setup**: |
| 52 | + |
| 53 | + Includes everything in the basic setup and fine-grained control over your data by allowing you to use your own Azure resources. All customer data—including files, threads, and vector stores—are stored in your own Azure resources, giving you full ownership and control. |
| 54 | + |
| 55 | +- **Standard Setup with Bring Your Own (BYO) Virtual Network**: |
| 56 | + |
| 57 | + Includes everything in the Standard Setup, with the added ability to operate entirely within your own virtual network. This setup supports Bring Your Own Virtual Network (BYO virtual network), allowing for strict control over data movement and helping prevent data exfiltration by keeping traffic confined to your network environment. |
| 58 | + |
| 59 | +### Compare setup options |
| 60 | + |
| 61 | +| Use Cases | Basic Setup | Standard Setup with Public Networking | Standard Setup with Private Networking | |
| 62 | +|--------------------------------------------------------------------------|-------------|----------------------------------------|----------------------------------------| |
| 63 | +| Get started quickly without managing resources | ✅ | | | |
| 64 | +| All conversation history, file, and vector stores are stored in your own resources | | ✅ | ✅ | |
| 65 | +| Support for Customer Managed Keys (CMK) | | ✅ | ✅ | |
| 66 | +| Private Network Isolation (Bring your own virtual network) | | | ✅ | |
| 67 | + |
| 68 | +### Deployment options |
| 69 | +To customize these templates, see [use your own resources](./how-to/use-your-own-resources.md). |
| 70 | + |
| 71 | +If you want support for Private Network Isolation see [network-secured setup](./how-to/virtual-networks.md) for more information on how to bring your own virtual network. |
| 72 | + |
| 73 | +| Description and Autodeploy | Diagram (click to zoom in) | |
| 74 | +|-----------------------------|------------------------------| |
| 75 | +| Deploy a basic agent setup that uses **Managed Identity** for authentication. <br> An account and project are created. <br> A GPT-4o model is deployed. <br> A Microsoft-managed Key Vault is used by default. <br> [](https://portal.azure.com/#create/Microsoft.Template/uri/https%3A%2F%2Fraw.githubusercontent.com%2Fazure-ai-foundry%2Ffoundry-samples%2Frefs%2Fheads%2Fmain%2Fsamples%2Fmicrosoft%2Finfrastructure-setup%2F40-basic-agent-setup%2Fbasic-setup.json) | :::image type="content" source="./media/quickstart/basic-setup-resources-foundry.png" alt-text="An architecture diagram for basic agent setup." lightbox="./media/quickstart/basic-setup-resources-foundry.png"::: | |
| 76 | +| Deploy a standard agent setup that uses **Managed Identity** for authentication. <br>An account and project are created. <br> A GPT-4o model is deployed. <br> Azure resources for storing customer data - **Azure Storage**, **Azure Cosmos DB**, and **Azure AI Search** - are automatically created if existing resources are't provided. <br> These resources are connected to your project to store files, threads, and vector data. <br> A Microsoft-managed Key Vault is used by default.</li></ul> <br> [](https://portal.azure.com/#create/Microsoft.Template/uri/https%3A%2F%2Fraw.githubusercontent.com%2Fazure-ai-foundry%2Ffoundry-samples%2Frefs%2Fheads%2Fmain%2Fsamples%2Fmicrosoft%2Finfrastructure-setup%2F41-standard-agent-setup%2Fazuredeploy.json) | :::image type="content" source="./media/quickstart/standard-agent-setup.png" alt-text="An architecture diagram for standard agent setup." lightbox="./media/quickstart/standard-agent-setup.png"::: | |
| 77 | + |
| 78 | +### [Optional] Model selection in autodeploy template |
| 79 | +You can customize the model used by your agent by editing the model parameters in the autodeploy template. To deploy a different model, you need to update at least the `modelName` and `modelVersion` parameters. |
| 80 | + |
| 81 | +By default, the deployment template is configured with the following values: |
| 82 | + |
| 83 | +| Model Parameter | Default Value | |
| 84 | +|------------------|----------------| |
| 85 | +| modelName | gpt-4o | |
| 86 | +| modelFormat | OpenAI (for Azure OpenAI) | |
| 87 | +| modelVersion | 2024-11-20 | |
| 88 | +| modelSkuName | GlobalStandard | |
| 89 | +| modelLocation | eastus | |
| 90 | + |
| 91 | +> [!IMPORTANT] |
| 92 | +> **Don't change the modelFormat parameter.** |
| 93 | +> |
| 94 | +> The templates only support deployment of Azure OpenAI models. See which Azure OpenAI models are supported in the [Azure AI Foundry Agent Service model support](./concepts/model-region-support.md) documentation. |
| 95 | +
|
| 96 | + |
| 97 | +### What's next? |
| 98 | +* [Create your first agent](./quickstart.md) |
| 99 | +* Explore more: |
| 100 | + * [Use your existing resources](./how-to/use-your-own-resources.md) |
| 101 | + * [Network secured agent setup](./how-to/virtual-networks.md) |
0 commit comments