Azure AI Agent Deploy

Overview

This skill guides the deployment of simple prompt-based Azure AI agents to Azure AI Foundry using YAML definitions. It automates the complex process of Azure authentication, project selection, model deployment, and agent creation while providing clear guidance for users unfamiliar with Azure constraints.

📦 Self-Contained: This skill includes all required Python scripts, bash scripts, and the agents module in the

scripts/

directory. No external repository dependencies are needed.

Dependencies

Core Python packages required:

azure-ai-projects==2.0.0b3
azure-ai-agents==1.1.0
azure-identity==1.25.1
azure-core==1.38.0
openai==2.16.0
PyYAML==6.0.3

Full requirements: See

scripts/requirements.txt

for complete pinned dependencies.

System requirements:

Python 3.10+
Azure CLI (
```
az
```
) - must be installed and logged in

Pre-Flight Check (IMPORTANT)

Before running any deployment commands, verify the environment is ready:

bash

# 1. Check Python dependencies are installed
python -c "from azure.ai.projects import AIProjectClient; from azure.identity import DefaultAzureCredential; import yaml; print('✅ Dependencies OK')" 2>/dev/null || echo "❌ Missing dependencies - run: pip install -r requirements.txt"

# 2. Check Azure CLI is installed and logged in
az account show >/dev/null 2>&1 && echo "✅ Azure CLI OK" || echo "❌ Azure CLI not ready - run: az login"

If dependencies are missing, install them:

bash

pip install -r requirements.txt
# OR install core packages directly:
pip install azure-ai-projects==2.0.0b3 azure-identity PyYAML openai

Quick Start

Setup: Copy the

scripts/

directory from this skill to your working directory.

The complete workflow involves 3 steps:

Create agent YAML - Define agent with name, description, and instructions
Deploy - Run
```
create-agent.py
```
to deploy to Azure (handles all Azure complexity)
Test - Run
```
test-agent.py
```
for interactive testing

Typical user flow:

bash

# Setup (one time)
cp -r scripts/* ./

# Install dependencies (REQUIRED before deployment)
pip install -r requirements.txt

# Verify Azure login
az login

# 1. Create or use example: agents/examples/my-agent.yaml
python create-agent.py agents/examples/helpful-assistant.yaml --filter myproject

# 2. Script handles: Azure auth, project selection, model deployment, agent creation
# Creates: agents/examples/helpful-assistant.agent.txt with connection details

# 3. Test interactively
python test-agent.py agents/examples/helpful-assistant.agent.txt

Agent YAML Format

Agents use YAML frontmatter + instructions format:

yaml

---
name: agent-name
description: Brief description of what the agent does
model: gpt-4o-mini  # Optional hint - if not found, will prompt/deploy
---

System instructions for the agent go here.
These become the agent's system prompt.

Example instructions:
You are a helpful assistant that specializes in...

Required fields:

```
name
```
- Agent identifier (lowercase, hyphens allowed)
```
description
```
- What the agent does (one sentence)

Optional fields:

```
model
```
- Model hint (e.g.,
```
gpt-4o
```
,
```
gpt-4o-mini
```
) - triggers auto-deployment if not found

Use the template in

assets/template-agent.yaml

for new agents. See

references/yaml-examples.md

for complete examples.

Deployment Workflow

Prerequisites Check

The

create-agent.py

script automatically checks:

Azure CLI installed - Provides install commands if missing
Azure login - Prompts for device code login if needed
RBAC roles - Verifies user has Azure AI User/Contributor/Owner role

If role check fails, script provides admin command to fix:

bash

az role assignment create --role "Azure AI User" --assignee "user@example.com" --scope /subscriptions/{sub-id}

Interactive Deployment Steps

The script guides through each step:

1. Project Selection

Lists Azure AI Foundry projects (with optional
```
--filter
```
for large subscriptions)
Auto-selects if only one match
Shows:
```
resource-name/project-name location
```

2. Model Deployment Selection

Lists current deployments in selected project
If model hint provided in YAML:
- Checks for exact match on deployment/model name
- Checks quota availability in project region
- Offers to deploy model automatically if not found
If no model hint: shows all deployments for manual selection
Can select existing deployment (letter A-Z) or deploy new model (number)

3. Model Deployment (if needed)

Launches
```
deploy-azure-model.sh
```
interactively
Handles:
- Model availability in region
- Quota checking (GlobalStandard/Standard SKUs)
- Capacity configuration (default 10K TPM)
- Deployment name conflicts

4. Agent Creation

Creates prompt-based agent with AgentKind.PROMPT
Handles name conflicts - prompts for new name if exists
Verifies creation with follow-up GET request

5. Output

Saves
```
.agent.txt
```
file with connection details and sample code

Prints test command:

python test-agent.py <agent-name> <endpoint>

Command Reference

bash

# Basic deployment
python create-agent.py agents/examples/code-reviewer.yaml

# Filter projects (useful for large subscriptions)
python create-agent.py agents/examples/math-tutor.yaml --filter maeda

# Deploy and test immediately
python create-agent.py agents/examples/helpful-assistant.yaml --test

Testing Agents

Interactive Testing

bash

# Using .agent.txt file (recommended)
python test-agent.py agents/examples/my-agent.agent.txt

# Direct specification
python test-agent.py agent-name https://resource.services.ai.azure.com/api/projects/project-name

Test session features:

Interactive chat loop
Type 'exit' or 'quit' to end
Ctrl+C to interrupt
Prints Python code sample after conversation

Programmatic Usage

The

.agent.txt

file includes sample code:

python

from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential

client = AIProjectClient(
    endpoint="https://resource.services.ai.azure.com/api/projects/project",
    credential=DefaultAzureCredential(),
)

openai_client = client.get_openai_client()

response = openai_client.responses.create(
    input=[{"role": "user", "content": "Your message"}],
    extra_body={"agent": {"name": "agent-name", "type": "agent_reference"}},
)

print(response.output_text)

Setup Azure Infrastructure (Optional)

If user needs to create Azure AI Foundry infrastructure from scratch:

bash

./setup-azure-ai.sh myproject swedencentral

Creates:

Resource group:
```
rg-myproject
```
AI Services resource:
```
myproject-resource
```
(with project management enabled)
AI Foundry project:
```
myproject-project
```

Returns endpoint and API key for use.

Model Deployment (Standalone)

To deploy models without creating agents:

bash

# Interactive deployment
./deploy-azure-model.sh

# With filters
./deploy-azure-model.sh myresource gpt-4o

Features:

Lists available models by region
Checks quota (GlobalStandard/Standard)
Configurable capacity (TPM)
Can select existing deployments

Important Constraints

Agent Type

This skill only covers simple prompt-based agents (AgentKind.PROMPT). No tools like Code Interpreter, File Search, or custom functions. For tool-enabled agents, see

.agents/skills/hosted-agents-v2-py/

Model Requirements

Only OpenAI models (gpt-4o, gpt-4o-mini, gpt-4, gpt-35-turbo, etc.)
Standard or GlobalStandard SKU (not Provisioned)
Model must be available in project region
Quota must be available (checked automatically)

Azure Requirements

Azure CLI must be installed
User must be logged in via
```
az login
```
User needs Azure AI User role minimum (or Contributor/Owner)
Uses
```
DefaultAzureCredential()
```
(never API keys)

Beta SDK Notice

Uses

azure-ai-projects==2.0.0b3

(beta) - APIs may change. The

AgentDefinition

API is specific to SDK 2.0.0b3+.

Common Issues

See

references/troubleshooting.md

for detailed solutions to:

Authentication failures (tenant mismatches)
RBAC permission errors
Quota exhaustion
Model availability by region
Name conflicts
SDK version issues

Bundled Scripts

This skill includes all required scripts and dependencies:

Main Scripts

scripts/create-agent.py - Main deployment CLI (610 lines)
scripts/test-agent.py - Interactive testing tool (179 lines)
scripts/deploy-azure-model.sh - Model deployment (336 lines)
scripts/setup-azure-ai.sh - Infrastructure setup (140 lines)

Python Module

scripts/agents/ - Core Python module with:
- ```
__init__.py
```
  - Module initialization
- ```
yaml_parser.py
```
  - YAML frontmatter parser
- ```
agent_builder.py
```
  - Agent creation via SDK
- ```
azure_discovery.py
```
  - Resource discovery

Example Agents

scripts/agents/examples/ - Agent YAML templates:
- ```
helpful-assistant.yaml
```
  - General purpose
- ```
code-reviewer.yaml
```
  - Code review
- ```
math-tutor.yaml
```
  - Tutoring
- ```
data-analyst.yaml
```
  - Data analysis
- ```
pirate-captain.yaml
```
  - Fun pirate example

Configuration

scripts/requirements.txt - Python dependencies

Usage: Copy the

scripts/

directory to your working directory to deploy agents.

Resources

Setup Documentation

README.md - Complete setup guide with installation and configuration steps

References

troubleshooting.md - Solutions to common Azure/deployment errors
yaml-examples.md - Complete agent YAML examples for various use cases

Assets

template-agent.yaml - Clean template for creating new agents

azure-ai-agent-deploy

NPX Install

Tags

SKILL.md Content

Azure AI Agent Deploy

Overview

Dependencies

Pre-Flight Check (IMPORTANT)

Quick Start

Agent YAML Format

Deployment Workflow

Prerequisites Check

Interactive Deployment Steps

Command Reference

Testing Agents

Interactive Testing

Programmatic Usage

Setup Azure Infrastructure (Optional)

Model Deployment (Standalone)

Important Constraints

Agent Type

Model Requirements

Azure Requirements

Beta SDK Notice

Common Issues

Bundled Scripts

Main Scripts

Python Module

Example Agents

Configuration

Resources

Setup Documentation

References

Assets