使用 Azure 开发人员 CLI AI 代理扩展将代理部署到 Microsoft Foundry

本文介绍如何使用 Azure 开发人员 CLI （azd） AI 代理扩展在 Microsoft Foundry 中设置和部署代理。该扩展允许你从终端或编辑器搭建代理并部署代理，并将 Foundry 功能与 azd 生命周期命令（azd init， azd up）组合在一起，实现一致的本地到云工作流。

主要功能

项目基架：设置完整的代理项目（基础结构即代码模板、代理定义、配置）并立即开始迭代。
声明性配置：在 azure.yaml 文件中为一致的环境定义服务、资源和模型部署。
统一预配和部署：运行 azd up 以生成容器、推送映像、创建资源、部署模型，并在一个步骤中发布代理。
代理定义管理：从目录、GitHub 或本地路径导入代理定义;CLI 将所需的参数映射到环境变量。
默认情况下安全：自动设置托管标识和基线安全性，而无需手动处理凭据。
可缩放的模型预配：指定模型名称、版本和容量; azd 在环境中一致地部署它们。

先决条件

Azure 开发人员 CLI（azd）已安装（版本 1.21.3 或更高版本）并经过azd auth login身份验证。
- 已安装的 azd ai agent 扩展（azd extension install azure.ai.agents）。如果未安装扩展，则初始化初学者模板或运行 azd ai agent 扩展时会自动安装扩展。
有权创建资源组和Microsoft Foundry 资源的 Azure 订阅。
安装 Azure CLI 以进行必要的操作。

设置和部署代理

完成以下部分，使用 AI 代理扩展将代理预配并部署到 Microsoft Foundry azd 。

初始化 Foundry 模板

使用 azd-ai-starter-basic 模板初始化新项目。在空文件夹中，运行：
```
azd init -t Azure-Samples/azd-ai-starter-basic --location northcentralus
```
注释

托管代理目前仅限于美国中北部 Azure 区域。在 Microsoft Foundry 文档中详细了解托管代理的区域可用性。
出现提示时，输入代理项目的环境名称（例如“my-analytics-agent”）。

该过程 azd init ：
- 将入门模板文件复制到你的项目中
- 使用 infra/ （基础结构即代码文件）和 src/ 文件夹创建目录结构
- 生成azure.yaml配置文件
- 为特定于环境的变量设置.azure/<env>/.env

初始化代理定义

初学者模板提供项目结构，但需要添加特定的代理定义。代理定义描述代理的行为、工具和功能。在 Agent Framework 存储库中查找示例定义。

使用自己的代理定义或目录中的代理定义。使用您自己的 <agent-definition-url> 值运行 azd ai agent init 命令：

azd ai agent init -m <agent-definition-url>

例如，将以下 URL 用于简单的计算器代理：

azd ai agent init -m https://github.com/azure-ai-foundry/foundry-samples/blob/main/samples/microsoft/python/getting-started-agents/hosted-agents/calculator-agent/agent.yaml

azd ai agent init 命令：

将代理定义 YAML 文件下载到项目的 src/ 目录中
分析代理定义以了解其要求
使用相应的服务和配置进行更新azure.yaml
将代理参数映射到环境变量

查看项目结构

初始化的模板包括以下关键文件：

├── .azure/                 # Environment-specific settings (.env)
├── infra/                  # Bicep files for Azure infrastructure
├── src/                    # Agent definition and code
└── azure.yaml              # Project configuration

打开 azure.yaml 以查看代理项目的设置方式：

requiredVersions:
    extensions:
        azure.ai.agents: latest
services:
    CalculatorAgent:
        project: src/CalculatorAgent
        host: azure.ai.agent
        language: docker
        docker:
            remoteBuild: true
        config:
            container:
                resources:
                    cpu: "1"
                    memory: 2Gi
                scale:
                    maxReplicas: 3
                    minReplicas: 1
            deployments:
                - model:
                    format: OpenAI
                    name: gpt-4o-mini
                    version: "2024-07-18"
                  name: gpt-4o-mini
                  sku:
                    capacity: 10
                    name: GlobalStandard
infra:
    provider: bicep
    path: ./infra
    module: main

此声明性配置定义代理服务和所需的 Azure AI 资源，包括模型部署。

预配和部署代理

运行 azd up 以部署资源和代理：

azd up

该 azd up 命令协调从基础结构到实时代理终结点的部署工作流：

预配基础结构：创建 Bicep 文件中定义的 Microsoft Foundry 帐户、项目和 Azure 资源。 - 预预配挂钩检查代理及其依赖项、模型和其他资源，然后填充环境变量，以便 Bicep 知道要预配的内容，包括： - AI_PROJECT_DEPLOYMENTS （JSON）：要部署的模型的规范。 - AI_PROJECT_CONNECTIONS （JSON）：要创建的连接的规范。 - AI_PROJECT_DEPENDENT_RESOURCES （JSON）：依赖资源的规范。 - ENABLE_HOSTED_AGENTS （布尔值）：是否需要预配托管代理（包含 ACR 和 CapHost）。
部署模型：根据 azure.yaml 中的指定，提供模型部署（例如，配置容量为 GPT-4o-mini 的模型）。
生成并推送容器：如果代理具有自定义代码， azd 请将其打包到容器映像中，并将其推送到 Azure 容器注册表。
发布代理：在 Microsoft Foundry 中创建代理应用程序，并将代理部署为实时的可调用服务。

完成 azd up 后，输出会显示 Microsoft Foundry 项目的端点、资源组、项目名称以及代理应用程序的详细信息。输出还提供指向 Microsoft Foundry 门户中“Agent Playground”的直接链接。

注释

对于新项目，预配和部署过程通常需要几分钟才能完成。

标识和安全性

azd 自动配置安全访问模式，因此无需手动管理凭据：

托管标识：代理使用 Foundry 项目的系统分配的托管标识与其他 Azure 资源进行身份验证。
角色分配： azd 自动授予所需的权限（例如，为代理授予对 Azure AI 服务、存储或数据库的访问权限）。
终结点安全性：代理终结点默认使用 Microsoft Entra ID （Azure AD）身份验证，因此只有经过授权的用户或应用程序才能调用代理。

这些安全配置遵循 Azure 最佳做法并开箱即用，因此从安全基础开始。

在 Microsoft Foundry 中测试代理

打开 Microsoft Foundry 门户。
导航到由 azd 创建的项目（项目名称出现在 azd up 输出中）。
打开 “代理 ”部分以查看已部署的代理。
在沙盒环境中启动代理并发送测试查询，例如“汇总您的能力”。

可在聊天窗口中看到代理的响应。

高级配置

可以自定义项目以满足默认工作流以外的高级要求。

自定义模型部署

该文件 azure.yaml 可让你控制部署的模型。若要添加或更改模型，请编辑文件：

services:
    CalculatorAgent:
        project: src/CalculatorAgent
        host: azure.ai.agent
        language: docker
        docker:
            remoteBuild: true
        config:
            container:
                resources:
                    cpu: "1"
                    memory: 2Gi
                scale:
                    maxReplicas: 3
                    minReplicas: 1
            deployments:
                - model:
                    format: OpenAI
                    name: gpt-4o-mini
                    version: "2024-07-18"
                  name: gpt-4o-mini
                  sku:
                    capacity: 10
                    name: GlobalStandard

运行 azd up 以部署新模型并更新项目。

此示例配置部署了多个模型，以便代理可以使用较大的模型进行复杂的推理，使用较小的模型进行简单查询。

管理环境变量

azd 设置或使用的环境变量：

Variable	目的
`AZURE_SUBSCRIPTION_ID`	资源的目标订阅。
`AZURE_RESOURCE_GROUP`	托管 AI 项目的资源组。
`AZURE_LOCATION`	Azure 区域（必须支持所选模型）。
`AZURE_AI_ACCOUNT_NAME`	Microsoft Foundry 帐户（枢纽）。
`AZURE_AI_PROJECT_NAME`	托管该代理的项目。
`AZURE_AI_FOUNDRY_PROJECT_ENDPOINT`	代理管理和运行时调用的终结点。

这些变量存储在 .azure/<environment-name>/.env. 为每个环境（开发、测试和生产）自定义它们。

示例用例和方案

使用 azd 和 AI 代理扩展，通过 Microsoft Foundry 加速各种代理方案。

构建对话助理

创建使用上下文回答问题并连接到内部数据的代理。

部署用于 A/B 测试的变体
添加 Azure AI 搜索以实现检索增强的响应
通过自定义工具集成业务 API

建立数据和见解代理

提供摘要、计算和可视化。

连接到 Azure SQL 数据库或 Cosmos DB。
使用代码解释器工具进行计算
将较大的推理模型与较小的经济高效模型混合

协调多个代理

负责协调复杂工作流的专家。

添加协调器代理以路由请求。
在 azure.yaml 中声明式定义关系。
根据负载独立调整代理。

标准化企业部署

在团队之间推动一致性。

发布可重用的蓝图和模板
应用一致的安全性、合规性和监视
使用azd provision和azd deploy在 CI/CD 中自动预配置和部署。

探索生态系统

浏览示例代理：浏览 .NET 代理和 Python 代理的代理框架存储库，并使用它们azd ai agent init进行部署。
加入社区：在 Azure 开发人员 CLI GitHub 讨论中分享体验并提问。
报告问题和建议功能：在 Azure/azure-dev 存储库中提供反馈和问题或功能建议，并用 ai-agent它们进行标记。
查看文档：有关代理开发的综合指南，请访问 Microsoft Foundry 文档。

其他资源

反馈

此页面是否有帮助？

Last updated on 2025-11-19