你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站,请访问 https://docs.azure.cn。

使用 Azure 开发人员 CLI 进行代理开发

Important

本文中标记为预览的项目目前为预览版。 此预览版在没有服务级别协议的情况下提供,Microsoft不建议将其用于生产工作负荷。 某些功能可能不受支持,或者可能具有受限功能。 有关详细信息,请参阅 Microsoft Azure 预览版补充使用条款。

Azure Developer CLI(azd)及其 azd ai agent 扩展为你提供了一套统一的命令行工作流,帮助你从想法出发,在 Microsoft Foundry 上构建出可投入生产的代理。 可以开发基于代码的托管代理和基于声明性提示的语音代理。 本文介绍开发人员旅程、定义代理的文件以及在此过程中遇到的核心概念。

本文面向那些偏好以终端为主、可通过脚本实现的工作流,而非使用 Foundry 门户或语言 SDK 的开发人员。

开发人员旅程

无论构建小型原型还是生产代理,工作流 azd ai 都遵循相同的生命周期。 你脚手架一个项目一次,然后随着项目增长混合搭配命令。

阶段 你做的事情 了解详细信息的位置
Install 安装 azd 和 Foundry 扩展。 设置开发人员环境
支架 从模板或现有代码初始化托管代理,或创建基于提示的语音代理。 快速入门:部署托管代理 或 快速入门:创建提示语音代理
定义 在 中 azure.yaml配置代理、模型部署依赖项、协议、工具和环境。 为托管代理编写 azure.yaml
开发 编写代理逻辑,使用工具箱添加工具,并在本地进行测试。 工具箱概述
Deploy 预配基础架构并部署到 Foundry。 部署托管代理
操作 监视日志、管理版本和自动运行。 管理托管代理
Evaluate 衡量智能体质量并改进提示。 使用 azd CLI 运行代理评估

代理类型

该 azd ai agent 扩展支持托管、提示和语音代理。

类型 Description 何时使用
托管代理 部署为源代码或容器映像的应用程序。 需要自定义逻辑、框架集成或完全控制行为。
提示智能体 完全通过说明和工具配置定义的代理,无需自定义代码。 你需要一个快速的配置驱动代理,而无需编写应用程序代码。
语音智能体 声明性提示语音代理,或连接到托管代理的语音封装器。 你需要通过 Voice Live 客户端获得实时语音体验。

托管代理可让你完全控制运行时、框架和工具集成,而 Foundry 处理基础结构、缩放和会话管理。

基于提示的语音代理不需要自定义容器。 如果您需要在自己的容器中运行自定义语音到语音或级联音频管道,请构建使用托管代理的语音代理,并使用invocations_ws协议。

若要在语音直播处理音频时将对话逻辑保留在托管文本代理中,请使用 托管语音包装器工作流。 包装服务和目标服务是在同一 azure.yaml 项目中的两个独立服务。 此流不会替换现有的自定义 invocations_ws 音频管道流。

在使用语音 CLI 选项之前,请检查已安装的扩展,如 语音代理快速入门先决条件中所述。

配置文件

托管代理项目使用项目根目录中的一个 azure.yaml 文件来声明代理及其预配和部署模型。 该文件使用拆分服务模型,其中每个命名服务都有一个host值,例如azure.ai.project、azure.ai.agent、azure.ai.connection、azure.ai.toolbox或azure.ai.skillazure.ai.routine。

文件 Purpose 谁维护它
azure.yaml 声明 Foundry 项目、模型部署、托管代理服务、依赖项、协议、工具、环境变量、容器资源和部署设置。 代理标识、模型、协议、工具和环境值位于服务中 azure.ai.agent 。 它由初始化生成。 根据需要对其进行自定义。

azure.ai.agent 服务通过内联方式定义智能体,或通过显式根 $ref 指向直接 YAML 或 JSON 定义。 对于支持文件的服务,请使用 azd ai agent add <service> --file <path>。 当前初始化不支持参数化 AgentManifest 包装器。 服务 uses: 的列表引用依赖项,如项目、连接和工具箱。

对于基于提示的语音代理, azure.yaml 存储声明性代理定义,包括 kind: prompt-voice模型、模型类型和代理名称。 它不包括托管代理容器运行时。 若要自定义说明、音频、轮次检测、听录、语音输出、工具和问候语,请参阅 配置语音代理。

对于托管语音包装器, conversationEngine.name 引用托管目标的服务名称。 包装器的 uses 依赖关系决定部署顺序,而 conversationEngine.version 默认使用当前环境中已部署的版本。 有关配置字段,请参阅语音服务参考。

变量替换

在${VAR_NAME}中使用azure.yaml来表示因azd环境而异的值。 占位符在部署或运行时从 .azure/<env>/.env 解析,因此相同的 azure.yaml 可在开发、暂存和生产等不同环境中工作。

CLI 的运行位置

azd ai 命令在 azd 项目目录内外均可使用:

  • 在 azd 项目内,命令从活动 azd 环境解析 Foundry 项目终结点。
  • 在 azd 项目之外,使用 azd ai project set <endpoint> 一次性设置活动上下文,或者在单个资源命令(--project-endpoint、connection、toolbox 或 skill)中传递 routine。 作为后备方案,azd ai 会读取 FOUNDRY_PROJECT_ENDPOINT 环境变量。
  • 从活动环境解析的非空端点优先于全局上下文。 有关 shell 回退和特定于命令的行为,请参阅 “设置项目上下文”。

协议

协议定义 Foundry 和代理容器之间的 HTTP 协定。 您的代理在 8088 端口上侦听,并提供健康探测,无论使用何种协议。

Protocol API 风格 何时使用
responses OpenAI 响应 API (POST /responses) 与 OpenAI API 生态系统兼容的标准选择。
invocations 自定义 JSON 协定 (POST /invocations) 当您需要完全控制请求和响应的数据负载时。

有关完整规范,请参阅 托管代理运行时协定。

这些协议设置适用于托管代理容器。 基于提示词的语音代理不会配置托管式代理协议。

azd ai agent invoke 不会为基于提示的语音代理或托管语音包装器实现语音对话。 有关 CLI 行为和测试指南,请参阅 语音代理限制。

会话和对话

概念 Description
Session 单个代理交互的独立执行环境。 每个会话在其自己的沙盒中运行,其中包含专用资源。
对话 响应协议的消息历史记录。 调用操作不会自动保留对话历史记录。

会话由一个 session_id 标识。 CLI 将保存每个代理的会话选择,并默认重用该选择。 使用 --new-session 重新开始,或使用 --session-id <id> 指定特定会话。 缓存未按委托用户键控;使用 --user-identity 时保留显式的用户到会话映射。

Foundry 项目中的资源

Foundry 项目托管的不仅仅是代理。 它还保存代理在运行时引用的共享资源。 CLI 通过专用命令组管理每个命令组。

Resource 它是什么 管理,使用
Connection 将 Foundry 项目链接到外部资源,例如 MCP 服务器、Foundry IQ(Azure AI 搜索),或使用必应进行地面处理。 azd ai connection 命令
工具箱 代理在运行时使用的工具的命名集合。 azd ai toolbox 命令
技能 在项目中的代理之间共享的可重用行为准则。 azd ai skill 命令
例程 触发器加上调用代理的操作。 azd ai routine 命令

这些资源在同一项目中的开发人员和代理之间共享。 它们的命令不同:连接和例程有 update,技能通过 update发布新版本,工具箱则先使用生成版本的连接和技能变更,然后执行 publish。

评估和改进智能体

代理运行后,两个相关工作流可帮助你衡量和提高其质量:

  • 快速代理评估使用 azd ai agent eval 和本地 eval.yaml,包括优化器工作流。 Project评估使用单独安装的azd ai eval扩展和evals/azure.eval.yaml,并配合跟踪或数据集源及显式 CI 质量门禁。 这两种配置格式不可互换。
  • 优化迭代重写你的智能体的提示,以提升评估信号。 它将评估用作目标函数,并生成一个由你审阅并接受的候选提示词。 你使用 azd ai agent optimize 管理它。

有关详细信息,请参阅 使用 azd CLI 运行代理评估 和 优化代理提示词。

按开发人员作业划分的命令组

为所需的结果选择一个命令。 追加 --help 以检查其标志和支持的输出格式。

Job Commands 指南
配置项目和托管模型 azd ai project add、azd ai project deployment add Project配置和上下文
选择或检查终结点上下文 azd ai project set、azd ai project show、azd ai project unset、azd ai project context 全局端点选择独立于基础架构声明。 上下文输出可以包含机密。
浏览示例或初始化代理 azd ai agent sample list、azd ai agent init、azd ai agent add 初始化托管、提示词和语音代理
为智能体分析、提取文档和内容并进行分类 azd ai cu analyze、azd ai cu analyzer Azure内容理解 CLI 快速入门(预览版)
在本地运行和检查 azd ai agent run、azd ai inspector launch 本地开发
调用、委托用户标识或发送自定义标头 azd ai agent invoke 调用选项
检查、跟进或取消工作 azd ai agent invocations show、azd ai agent invocations follow、azd ai agent invocations cancel 长时间运行的调用
查看或更新终结点 azd ai agent endpoint show、azd ai agent endpoint update 终结点和卡片更新
检查状态、诊断问题或查看日志 azd ai agent show、azd ai agent doctor、azd ai agent monitor 诊断 和 日志
创建、列出、查看、停止或删除沙盒 azd ai agent sessions create、azd ai agent sessions list、azd ai agent sessions show、azd ai agent sessions stop、azd ai agent sessions delete 会话管理
检索或维护沙盒文件、为其设定种子 azd ai agent files upload、azd ai agent files download、azd ai agent files list、azd ai agent files mkdir、azd ai agent files stat、azd ai agent files delete 会话文件操作
恢复已部署的源代码 azd ai agent code download 下载代码或 ZIP
检查持久化存储并维护共享项目 azd ai agent state-stores list、azd ai agent state-stores select、azd ai agent state-stores show、azd ai agent state-stores items 状态存储操作和限制
将代理依赖项添加到部署配置 azd ai agent connection add、azd ai agent toolbox add 这两个服务必须已存在于 azure.yaml;这些命令添加 uses 条目,而不是远程资源。
管理连接凭据和元数据 azd ai connection create、azd ai connection list、azd ai connection show、azd ai connection update、azd ai connection delete 连接身份验证和维护
创作、设置版本或下载可重用技能 azd ai skill add、azd ai skill create、azd ai skill update、azd ai skill list、azd ai skill show、azd ai skill download、azd ai skill delete 技能工作流
创作和管理工具箱 azd ai toolbox add、azd ai toolbox create、azd ai toolbox list、azd ai toolbox show、azd ai toolbox delete 工具箱配置
开发和推广工具集合 azd ai toolbox connection、azd ai toolbox skill、azd ai toolbox versions list、azd ai toolbox publish 变更从最新版本分支出来;推广需要显式操作。
计划、分派或检查例程 azd ai routine add、azd ai routine create、azd ai routine list、azd ai routine show、azd ai routine update、azd ai routine enable、azd ai routine disable、azd ai routine dispatch、azd ai routine run list、azd ai routine delete 常规工作流
生成并运行快速评估 azd ai agent eval generate、azd ai agent eval update、azd ai agent eval run、azd ai agent eval list、azd ai agent eval show 快速评估和优化器资产
改进并部署优化候选项 azd ai agent optimize、azd ai agent optimize status、azd ai agent optimize list、azd ai agent optimize cancel、azd ai agent optimize apply、azd ai agent optimize deploy 优化工作流
打包或发布适用于 Teams 的活动智能体 azd ai agent pack、azd ai agent publish Teams 分发
删除托管版本或智能体 azd ai agent delete 删除代理
评估项目并强制实施质量关口 azd ai eval init、azd ai eval generate、azd ai eval create、azd ai eval run、azd ai eval dataset、azd ai eval evaluator、azd ai eval job Project 评估; 单独安装azure.ai.evaluations。
注册和版本化可重用数据集 azd ai dataset 数据集生命周期;azure.ai.dataset 需单独安装。
提交、暂停、恢复、取消或部署微调作业 azd ai finetuning init、azd ai finetuning jobs 微调;单独安装 azure.ai.finetune 。
上传和管理自定义模型权重 azd ai models 自定义模型导入和维护;单独安装 azure.ai.models 。

添加命令的每个扩展都会公开 version;请改用 azd ext list来检查 microsoft.foundry 捆绑包。 连接、例程和技能组还公开 context 用于本地项目和环境检查;将输出视为潜在敏感。

活动智能体发行

部署活动协议智能体后,azd ai agent pack 会创建用于旁加载的 appPackage.zip。 使用 --output-dir、--display-name 和 --app-version 来自定义该包。 打包与发布不同。

azd ai agent publish通过 Microsoft 365 进行发布。 除非另有配置,否则简单活动代理默认为 shared 分发; --scope tenant 需要管理员批准。 数字工作者需要租户作用域。 使用可重复的 --access-boundary 值,使用 --clear-access-boundaries 删除现有边界,以及将可重复的 --optional-permission-scope <resource-app-id>=<scope> 值用于可选权限。 personal 不是发布范围;使用 pack --scope personal 并旁加载包进行每用户测试。

部署生命周期

完整的开发人员循环将精简为一系列命令。 脚手架一次,然后随着项目增长使用直接命令。

有关托管语音智能体路径,请参阅快速入门:创建提示语音智能体。

# Scaffold a project from a template or your existing code
azd ai agent init

# Run locally and invoke
azd ai agent run
azd ai agent invoke --local "Hello, world!"

# Provision infrastructure and deploy the agent
azd up

# Extend the project with shared resources at any time
azd ai connection create my-search --kind cognitive-search --target https://... --auth-type api-key --key "..."
azd ai routine create daily-digest --trigger recurring --cron "0 7 * * *" --agent-name my-agent

# Evaluate quality
azd ai agent eval generate
azd ai agent eval run

# Tear down all Azure resources
azd down