用 Azure Developer CLI 初始化托管智能体项目

#用 Azure Developer CLI 初始化托管智能体项目

重要

本文中标记为预览的内容目前处于预览阶段。此预览不提供服务级别协议，Microsoft 不建议将其用于生产工作负载。某些功能可能不受支持，或能力受限。更多信息见 Microsoft Azure 预览版补充使用条款。

使用 azd ai agent init 搭建托管智能体项目，其中包含在 Microsoft Foundry 上构建、测试和部署 AI 智能体所需的文件。在本文中，你选择一个起点，并从模板、自己的代码或现有 Foundry 项目初始化该项目。

如果使用 GitHub Copilot 这类编码智能体，Microsoft Foundry Skill 可以帮助你选择起始模板、搭建项目，并解释生成的 azd 配置。

先决条件

• 已安装 Azure Developer CLI Foundry 扩展。
• 一个已身份验证的 Azure 会话（azd auth login）。
• 对 Azure 订阅拥有参与者访问权限。

选择起点

开始一个项目有三种方式。选择与你的情况匹配的路径。

从模板初始化

在空目录中运行交互式向导，并选择从模板开始新建：

Bash

azd ai agent init

向导会引导你完成以下选择。

智能体名称来自模板。CLI 创建一个名为 <directory>-dev 的 azd 环境，并用所选 Foundry 项目的详细信息配置它。每个模板都包含智能体源代码、一个 Dockerfile，以及一个 azure.yaml 文件，该文件充当 azd 项目和托管智能体配置的统一项目清单。

从 azure.yaml URL 初始化

如果有特定的智能体示例，把 -t（--template）指向该示例的 azure.yaml。CLI 采用该文件作为项目清单，并下载所引用的智能体源代码。

Bash

azd ai agent init -t https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/agent-framework/responses/01-basic/azure.yaml

注意

智能体清单（agent.manifest.yaml）和独立智能体定义（agent.yaml）已弃用。自 Foundry azd 扩展（azure.ai.agents 1.0.0-beta.1）起，所有托管智能体配置都位于单个 azure.yaml 中。见为托管智能体编写 azure.yaml。

对 azure.yaml 项目文档使用 -t。-m（--manifest）选项已弃用，仅为兼容而保留。不支持旧版智能体清单和独立智能体定义。

指定模型

在初始化时选择模型：

Bash

azd ai agent init --model gpt-4.1

或者使用 Foundry 项目中的现有模型部署：

Bash

azd ai agent init --model-deployment my-deployment

选择部署模式

默认情况下，azd ai agent init 对 Python 和 .NET 项目使用代码部署。代码部署把源代码作为 ZIP 包上传。要改为搭建基于容器的项目，传入 --deploy-mode container：

Bash

azd ai agent init --deploy-mode container

要部署预先构建的容器映像，传入 --image 和 --agent-name。此选项会跳过模板和语言选择、代码搭建、Dockerfile 生成以及 Azure 容器注册表设置。

Bash

azd ai agent init --agent-name my-agent --image myregistry.azurecr.io/my-agent:v1

非交互地浏览模板

要在搭建之前检查目录，或从脚本驱动 azd ai agent init，请列出目录：

Bash

# Everything in the catalog
azd ai agent sample list

# Just the featured Python agent samples
azd ai agent sample list --featured-only --language python --type agent

# Full azd templates only, as JSON for scripting
azd ai agent sample list --type azd --output json

每个条目都包含一条可直接运行的 initCommand，你可以复制并在要搭建到的目录中运行它。

提示

当以不同的 Foundry 智能体身份复用示例时，在 azd ai agent init 上传入 --agent-name <new-name>，这样写入 azure.yaml 的名称就不会与示例的默认名称冲突。

从现有代码初始化

如果已有 Python 或 .NET 智能体代码，在已经包含代码的目录中运行 azd ai agent init：

Bash

cd my-agent/
azd ai agent init

CLI 会检测现有文件，并围绕它们生成 azure.yaml 服务条目，而不会覆盖你的代码。对于容器部署，它还会添加一个 Dockerfile。除非你以后弹出基础设施即代码，否则基础设施默认仍然不含 Bicep。

智能体代码必须满足托管智能体运行时契约：

• 在端口 8088 上监听。
• 在 GET /readiness 提供健康探测。
• 处理一种受支持的协议（responses 或 invocations）。

如果代码还不能使用这些协议之一，添加协议适配器，即一个轻量 SDK 包装器，在 Foundry 协议与智能体逻辑之间进行转换。

要向现有 azd 项目添加智能体，init 会检测该项目，并向现有 azure.yaml 添加新的服务条目。使用 --src 指定子目录：

Bash

azd ai agent init --src src/my-agent

连接到现有 Foundry 项目

要通过 azd 管理现有 Foundry 项目，运行向导并选择连接到现有项目的选项。也可以直接提供项目的 Azure 资源 ID，跳过交互式选择：

Bash

azd ai agent init --project-id /subscriptions/{sub}/resourceGroups/{rg}/providers/Microsoft.CognitiveServices/accounts/{account}/projects/{project}

要查找项目 ID，打开 Foundry 门户，转到管理 > 项目详细信息，并复制资源 ID值。

警告

使用 --project-id 针对现有项目初始化时，工具会跳过它在创建新项目时执行的自动角色分配。请确保所需角色已经分配。完整矩阵见托管智能体权限参考。

查看会创建什么

默认情况下，init 创建以下项目结构。只有容器部署才需要 Dockerfile：

.
|-- azure.yaml                  # Unified azd project and hosted agent configuration
|-- src/
|   \-- <agent-name>/
|       |-- Dockerfile          # Container build definition
|       \-- ...                 # Agent source code
|-- .azure/                     # Environment configuration
\-- infra/                      # Optional IaC, created when you pass --infra

模板和示例在项目根目录发布统一的 azure.yaml。初始化期间，azd 采用或生成该文件。默认情况下，除非选择弹出基础设施，否则不需要维护 Bicep 或 Terraform 文件。

选择 Terraform 或 Bicep 基础设施

要用 Terraform 管理基础设施，在初始化项目时选择它：

Bash

azd ai agent init --infra=terraform

基础设施和部署模式是相互独立的选择。对于带 Terraform 基础设施的基于容器的智能体，使用：

Bash

azd ai agent init --infra=terraform --deploy-mode container

对于新项目，该命令在 infra/ 下写入 Terraform 文件，并在 azure.yaml 中配置 Terraform 基础设施提供程序。在已有基础设施的项目中，Foundry 基础设施可以作为单独一层生成在 infra/foundry/ 下。供应之前先检查生成的配置。

要改为选择 Bicep，使用 --infra=bicep 或简写 --infra。省略 --infra 会保留默认的无基础设施工作流。

azd provision 应用所选基础设施。azd deploy 仍然创建托管智能体版本；选择 Terraform 并不会把智能体版本管理移入 Terraform 状态。

文件结构和自定义见托管智能体基础设施。在管道中使用 Terraform 之前，配置 Terraform CI/CD 和远程状态。 PRIMARY_SOURCE: https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/init-agent-project