Skip to main content

​
Agent Environment Setup

This guide walks you through deploying the infrastructure needed to create agents with Foundry Agent Service.

​
Prerequisites

  • Azure subscription (Create one for free)
  • Azure CLI installed and authenticated
  • Appropriate permissions:
    • Azure AI Account Owner - Create account and project
    • Role Based Access Control Administrator - Assign RBAC (Standard Setup only)
    • Azure AI User - Create and edit agents

​
Choose Your Setup

Agent Service offers three environment configurations:
Quick start with managed resourcesIncludes:
  • Microsoft-managed storage
  • Compatible with OpenAI Assistants API
  • Support for non-OpenAI models
  • Azure AI Search and Bing tools
Best for: Development, testing, proof of concepts

​
Deployment Options

​
Basic Setup Deployment

1

Deploy using Azure Portal

Click the deploy button:Deploy To Azure
2

Configure deployment

  • Select subscription and resource group
  • Choose region
  • Review default model (GPT-4.1)
  • Click Review + Create
3

Wait for completion

Deployment typically takes 5-10 minutes
Resources created:
  • Foundry account
  • Foundry project
  • GPT-4.1 model deployment
  • Microsoft-managed Key Vault

​
Standard Setup Deployment

1

Deploy using Azure Portal

Click the deploy button:Deploy To Azure
2

Configure deployment

  • Select subscription and resource group
  • Choose region
  • Optionally provide existing resource IDs:
    • Azure Storage
    • Azure Cosmos DB
    • Azure AI Search
  • Click Review + Create
3

Wait for completion

Deployment typically takes 10-15 minutes
Resources created:
  • Everything from Basic Setup
  • Azure Storage account (or use existing)
  • Azure Cosmos DB account (or use existing)
  • Azure AI Search service (or use existing)
  • Project connections
  • RBAC role assignments
  • Capability hosts

​
Model Selection

The deployment templates support customizing the deployed model:
Do not change the modelFormat parameter. Templates only support Azure OpenAI models.
Default configuration:
ParameterDefault Value
modelNamegpt-4.1
modelFormatOpenAI (Azure OpenAI)
modelVersion2025-04-14
modelSkuNameGlobalStandard
modelLocationeastus
To deploy a different model, update modelName and modelVersion in the template parameters. See model region support for agent-compatible models.

​
Verify Deployment

After deployment completes:
1

Check Azure Portal

  1. Navigate to your resource group
  2. Confirm resources exist:
    • Basic: Account, project, model
    • Standard: Plus Storage, Cosmos DB, AI Search
2

Get project endpoint

  1. Open your Foundry project
  2. Navigate to Overview
  3. Copy the endpoint URL:
https://<resource-name>.services.ai.azure.com/api/projects/<project-name>
3

Test connection

az login
az account set --subscription <subscription-id>

# Verify you can access the project
az ml workspace show \
  --name <project-name> \
  --resource-group <resource-group>

​
Troubleshooting

​
Deployment Failures

IssueCauseSolution
Quota errorInsufficient quota for modelRequest quota increase or select different region
Permission deniedMissing RBAC Administrator roleAsk subscription owner to grant required role
Resources created but agent failsProject not connected properlyVerify connections in Project settings > Connected resources
Model not availableModel not in selected regionCheck model region support

​
Common Issues

Error: Capability host provisioning failsCause: Cosmos DB doesn’t have minimum 3,000 RU/sSolution: Increase throughput or switch to Provisioned mode
az cosmosdb update \
  --name <cosmos-name> \
  --resource-group <rg> \
  --throughput 3000
Error: Deployment fails with region errorCause: Agent Service not available in selected regionSolution: Choose a supported region:
Error: Model deployment failsCause: Selected model not available in regionSolution:
  1. Check model availability
  2. Select compatible model
  3. Or deploy to different region

​
Next Steps

Create Agent

Build your first agent

Standard Setup

Configure enterprise features

Virtual Networks

Add private network isolation

Agent Tools

Explore agent capabilities

Build docs developers (and LLMs) love

Get started for freeTalk to us