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

Important

本文中标记了“（预览版）”的项目目前为公共预览版。 此预览版未提供服务级别协议，不建议将其用于生产工作负载。 某些功能可能不受支持，或者可能具有受限功能。 有关详细信息，请参阅 Microsoft Azure 预览版补充使用条款。

Azure 开发人员 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	何时使用
托管代理	在代码中生成的容器化应用程序，打包为 Docker 映像，并部署到 Foundry。	需要自定义逻辑、框架集成或完全控制行为。
提示智能体	完全通过说明和工具配置定义的代理，无需自定义代码。	你需要一个快速的配置驱动代理，而无需编写应用程序代码。

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

配置文件

托管代理项目使用项目根目录中的一个 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 服务定义你的托管智能体内联，并使用 uses: 引用其他服务，例如项目、连接、工具箱、技能和例程。 当前托管代理agent.yaml项目模型中没有独立agent.manifest.yaml或azd文件。

变量替换

在azure.yaml中使用${VAR_NAME}来表示因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 环境变量。
• 项目内的环境始终优先于全局上下文，因此切换到某个项目目录会使 CLI 重新指向该项目的端点。

协议

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

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

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

会话和对话

概念	Description
Session	单个代理交互的独立执行环境。 每个会话在其自己的沙盒中运行，其中包含专用资源。
对话	会话中的消息序列。 Foundry 管理对话历史，并可以在跨请求中填充它。

会话由一个 session_id 标识。 运行 azd ai agent invoke时，Foundry 默认重复使用上次调用中的会话。 使用 --new-session 重新开始，或使用 --session-id <id> 指定特定会话。

Foundry 项目中的资源

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

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

这些资源在同一项目中的开发人员和代理之间共享。 每个命令组公开标准create、update、delete和showlist谓词。

评估和改进智能体

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

• 评估会让代理针对数据集运行，使用一个或多个评估器对响应进行评分，并给出总体质量指标。 你使用 azd ai agent eval 管理它。
• 优化迭代重写你的智能体的提示，以提升评估信号。 它将评估用作目标函数，并生成一个由你审阅并接受的候选提示词。 你使用 azd ai agent optimize 管理它。

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

部署生命周期

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

# 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

相关内容

• 快速入门：部署第一个托管代理
• 什么是托管代理？
• 托管代理运行时协定
• 代理开发生命周期