Agent Environment Setup

Deploy the infrastructure needed for Foundry Agent Service including resource provisioning, model deployment, and configuration.

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:

Basic Setup

Quick start with managed resources

Includes:

• 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

Standard Setup

Enterprise data control

Includes:

• Everything in Basic Setup
• Bring your own Azure Storage
• Bring your own Azure Cosmos DB
• Bring your own Azure AI Search
• Customer-managed encryption keys

Best for: Production workloads, compliance requirements

Standard with Private Network

Maximum security

Includes:

• Everything in Standard Setup
• Private virtual network support
• No public network access
• Data exfiltration prevention

Best for: Highly regulated industries, sensitive data

Deployment Options

Basic Setup Deployment

1. Deploy using Azure Portal

   Click the deploy button:

   

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:

   

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:

Parameter	Default Value
modelName	gpt-4.1
modelFormat	OpenAI (Azure OpenAI)
modelVersion	2025-04-14
modelSkuName	GlobalStandard
modelLocation	eastus

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

Issue	Cause	Solution
Quota error	Insufficient quota for model	Request quota increase or select different region
Permission denied	Missing RBAC Administrator role	Ask subscription owner to grant required role
Resources created but agent fails	Project not connected properly	Verify connections in Project settings > Connected resources
Model not available	Model not in selected region	Check model region support

Common Issues

Insufficient Cosmos DB Throughput

Error: Capability host provisioning fails

Cause: Cosmos DB doesn’t have minimum 3,000 RU/s

Solution: Increase throughput or switch to Provisioned mode

az cosmosdb update \
  --name <cosmos-name> \
  --resource-group <rg> \
  --throughput 3000

Region Not Supported

Error: Deployment fails with region error

Cause: Agent Service not available in selected region

Solution: Choose a supported region:

• East US
• West Europe
• Southeast Asia
• Check model region support for the full list

Model Not Available

Error: Model deployment fails

Cause: Selected model not available in region

Solution:

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