Skills
skills/johnmaeda/azure-ai-agent-deploy-ez/azure-ai-agent-deploy

azure-ai-agent-deploy

Installation
SKILL.md

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:

# 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:

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:

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

Typical user flow:

# 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:

---
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:

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

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

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

# 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

# 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:

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:

./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:

# 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
Weekly Installs
2
Repository
johnmaeda/azure…eploy-ez
First Seen
Feb 7, 2026
Security Audits
Gen Agent Trust HubFail
SocketPass
SnykPass
Installed on
amp2
gemini-cli2
github-copilot2
codex2
kimi-cli2
opencode2