azure-ai-agent-deploy

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Azure AI Agent Deploy

Azure AI Agent 部署

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.

本Skill可指导用户通过YAML定义将基于提示词的简单Azure AI Agent部署至Azure AI Foundry。它能自动处理Azure身份验证、项目选择、模型部署和Agent创建等复杂流程，同时为不熟悉Azure限制的用户提供清晰指引。

📦 独立封装： 本Skill包含所有必需的Python脚本、bash脚本以及

scripts/

目录下的agents模块，无需依赖外部代码库。

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

所需核心Python包：

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

完整依赖列表： 完整的固定版本依赖项请查看

scripts/requirements.txt

。

系统要求：

Python 3.10+
Azure CLI (
```
az
```
) - 必须已安装并完成登录

Pre-Flight Check (IMPORTANT)

预检查（重要）

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

bash

undefined

在运行任何部署命令前，请验证环境是否就绪：

bash

undefined

1. Check Python dependencies are installed

1. 检查Python依赖是否已安装

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

2. 检查Azure CLI是否已安装并完成登录

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

az account show >/dev/null 2>&1 && echo "✅ Azure CLI OK" || echo "❌ Azure CLI not ready - run: az login"


**若缺少依赖项，请执行以下命令安装：**
```bash
pip install -r requirements.txt

OR install core packages directly:

或直接安装核心包：

pip install azure-ai-projects==2.0.0b3 azure-identity PyYAML openai

undefined

pip install azure-ai-projects==2.0.0b3 azure-identity PyYAML openai

undefined

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

undefined

设置： 将本Skill中的

scripts/

完整工作流包含3个步骤：

创建Agent YAML - 定义Agent的名称、描述和指令
部署 - 运行
```
create-agent.py
```
将Agent部署至Azure（自动处理所有Azure相关复杂操作）
测试 - 运行
```
test-agent.py
```
进行交互式测试

典型用户流程：

bash

undefined

Setup (one time)

一次性设置

cp -r scripts/* ./

Install dependencies (REQUIRED before deployment)

安装依赖项（部署前必须完成）

pip install -r requirements.txt

Verify Azure login

验证Azure登录状态

az login

1. Create or use example: agents/examples/my-agent.yaml

1. 创建或使用示例文件：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

2. 脚本将处理：Azure身份验证、项目选择、模型部署、Agent创建

Creates: agents/examples/helpful-assistant.agent.txt with connection details

生成：agents/examples/helpful-assistant.agent.txt，包含连接信息

3. Test interactively

3. 交互式测试

python test-agent.py agents/examples/helpful-assistant.agent.txt

undefined

python test-agent.py agents/examples/helpful-assistant.agent.txt

undefined

Agent YAML Format

Agent YAML格式

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.

Agent采用YAML前置元数据+指令的格式：

yaml

---
name: agent-name
description: Brief description of what the agent does
model: gpt-4o-mini  # 可选提示 - 若未找到模型，将提示/部署模型
---

此处为Agent的系统指令。
这些内容将成为Agent的系统提示词。

示例指令：
你是一位专业的助手，擅长...

必填字段：

```
name
```
- Agent标识符（小写，允许使用连字符）
```
description
```
- Agent的功能描述（一句话）

可选字段：

```
model
```
- 模型提示（例如
```
gpt-4o
```
,
```
gpt-4o-mini
```
）- 若未找到模型，将触发自动部署

创建新Agent时可使用

assets/template-agent.yaml

模板。完整示例请查看

references/yaml-examples.md

。

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}

create-agent.py

脚本会自动检查以下内容：

Azure CLI是否已安装 - 若未安装，将提供安装命令
Azure登录状态 - 若未登录，将提示进行设备代码登录
RBAC角色 - 验证用户是否拥有Azure AI User/Contributor/Owner角色

若角色检查失败，脚本将提供管理员修复命令：

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>

脚本将引导用户完成每个步骤：

1. 项目选择

列出Azure AI Foundry项目（针对大型订阅，可使用
```
--filter
```
参数筛选）
若仅匹配一个项目，将自动选择
显示内容：
```
resource-name/project-name location
```

2. 模型部署选择

列出所选项目中的当前部署
若YAML中提供了模型提示：
- 检查是否存在与部署/模型名称完全匹配的项
- 检查项目所在区域的配额可用性
- 若未找到模型，将提供自动部署选项
若未提供模型提示：显示所有部署供手动选择
可选择现有部署（字母A-Z）或部署新模型（数字选项）

3. 模型部署（如需）

交互式启动
```
deploy-azure-model.sh
```
处理以下内容：
- 模型在目标区域的可用性
- 配额检查（GlobalStandard/Standard SKU）
- 容量配置（默认10K TPM）
- 部署名称冲突

4. Agent创建

创建基于提示词的Agent，类型为AgentKind.PROMPT
处理名称冲突 - 若名称已存在，将提示输入新名称
通过后续GET请求验证创建结果

5. 输出

保存
```
.agent.txt
```
文件，包含连接信息和示例代码

打印测试命令：

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

Command Reference

命令参考

bash

undefined

bash

undefined

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

undefined

python create-agent.py agents/examples/helpful-assistant.yaml --test

undefined

Testing Agents

Agent测试

Interactive Testing

交互式测试

bash

undefined

bash

undefined

Using .agent.txt file (recommended)

使用.agent.txt文件（推荐）

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

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


**测试会话功能：**
- 交互式聊天循环
- 输入'exit'或'quit'结束会话
- 按Ctrl+C中断
- 会话结束后打印Python代码示例

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)

.agent.txt

文件中包含示例代码：

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)

搭建Azure基础设施（可选）

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.

若用户需要从零开始创建Azure AI Foundry基础设施：

bash

./setup-azure-ai.sh myproject swedencentral

将创建以下资源：

资源组：
```
rg-myproject
```
AI服务资源：
```
myproject-resource
```
（已启用项目管理）
AI Foundry项目：
```
myproject-project
```

返回可用于后续操作的端点和API密钥。

Model Deployment (Standalone)

模型部署（独立使用）

To deploy models without creating agents:

bash

undefined

若无需创建Agent，仅需部署模型：

bash

undefined

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

./deploy-azure-model.sh myresource gpt-4o


功能特性：
- 按区域列出可用模型
- 检查配额（GlobalStandard/Standard）
- 可配置容量（TPM）
- 可选择现有部署

Important Constraints

重要限制

Agent Type

Agent类型

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/

本Skill仅支持基于提示词的简单Agent（AgentKind.PROMPT）。不支持代码解释器、文件搜索或自定义函数等工具。如需使用支持工具的Agent，请查看

.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)

仅支持OpenAI模型（gpt-4o、gpt-4o-mini、gpt-4、gpt-35-turbo等）
仅支持Standard或GlobalStandard SKU（不支持Provisioned）
模型必须在项目所在区域可用
必须有可用配额（将自动检查）

Azure Requirements

Azure要求

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)

必须安装Azure CLI
用户必须通过
```
az login
```
完成登录
用户至少需要拥有Azure AI User角色（或Contributor/Owner角色）
使用
```
DefaultAzureCredential()
```
（绝不使用API密钥）

Beta SDK Notice

Beta SDK说明

Uses

azure-ai-projects==2.0.0b3

(beta) - APIs may change. The

AgentDefinition

API is specific to SDK 2.0.0b3+.

使用的

azure-ai-projects==2.0.0b3

为Beta版本 - API可能会发生变化。

AgentDefinition

API仅适用于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

有关以下问题的详细解决方案，请查看

references/troubleshooting.md

：

身份验证失败（租户不匹配）
RBAC权限错误
配额耗尽
模型区域可用性
名称冲突
SDK版本问题

Bundled Scripts

内置脚本

This skill includes all required scripts and dependencies:

本Skill包含所有必需的脚本和依赖项：

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)

scripts/create-agent.py - 主部署CLI（610行）
scripts/test-agent.py - 交互式测试工具（179行）
scripts/deploy-azure-model.sh - 模型部署脚本（336行）
scripts/setup-azure-ai.sh - 基础设施搭建脚本（140行）

Python Module

Python模块

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

scripts/agents/ - 核心Python模块，包含：
- ```
__init__.py
```
  - 模块初始化文件
- ```
yaml_parser.py
```
  - YAML前置元数据解析器
- ```
agent_builder.py
```
  - 通过SDK创建Agent
- ```
azure_discovery.py
```
  - 资源发现

Example Agents

示例Agent

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

scripts/agents/examples/ - Agent YAML模板：
- ```
helpful-assistant.yaml
```
  - 通用助手
- ```
code-reviewer.yaml
```
  - 代码评审
- ```
math-tutor.yaml
```
  - 数学辅导
- ```
data-analyst.yaml
```
  - 数据分析
- ```
pirate-captain.yaml
```
  - 趣味海盗示例

Configuration

配置文件

scripts/requirements.txt - Python dependencies

Usage: Copy the

scripts/

directory to your working directory to deploy agents.

scripts/requirements.txt - Python依赖项列表

使用方法： 将

scripts/

Resources

资源

Setup Documentation

设置文档

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

README.md - 包含安装和配置步骤的完整设置指南

References

参考文档

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

troubleshooting.md - Azure/部署相关常见错误的解决方案
yaml-examples.md - 适用于不同场景的完整Agent YAML示例

Assets

资源文件

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

template-agent.yaml - 用于创建新Agent的空白模板