可易

用 Azure Developer CLI 把托管智能体推进生产

可易团队阅读约 6 分钟

用 azd 把同一源代码修订从开发推进到测试再到生产，先锁住稳定版本 100% 流量，再以 10% 金丝雀验证，失败则切回。

目录

#用 Azure Developer CLI 把托管智能体推进生产

重要

这篇文章里标为预览（preview）的项目目前处于预览。此预览不提供服务级别协议（service-level agreement），Microsoft 不建议把它用于生产工作负载。某些功能可能不受支持，或能力受到限制。

用 Azure Developer CLI（azd）把你的 Microsoft Foundry 托管智能体（hosted agent）经开发、测试推进到生产环境。在测试中验证一次发布之后，把它部署到生产，并逐步提高新版本所占的流量份额。如果发现问题，把流量路由回上一版本。

这篇文章建立在“为托管智能体设置持续集成/持续交付（CI/CD）”之上。它用跨环境的源代码部署和一次渐进的生产发布，扩展你现有的流水线。这些 Bash 命令可以在 GitHub Actions 作业和 Azure DevOps 流水线阶段里使用。

用 azd 管理部署和端点更新。不用它的话，你需要自己通过门户、软件开发工具包（SDK）或 REST API 管理 Azure 资源和部署操作。

跨环境推进发布

把你的单环境 CI/CD 设置扩展为：把发布从开发推进到测试，再推进到生产。在每个环境使用同一份源代码修订。把每个环境绑定到一个单独的、已经存在的 Foundry 项目。仅靠环境名称并不能隔离 Azure 资源。

注意

为每个环境分别打包并部署源代码，而不是共享一个构建产物。推进的是已测试的源代码修订和依赖文件。一次未改变的部署可以复用已有的智能体版本。

配置每个环境

把你现有的源代码智能体配置留在 azure.yaml 里。项目服务的端点使用 ${FOUNDRY_PROJECT_ENDPOINT}，模型部署和连接名称使用环境变量引用。参见 Azure YAML 配置。

  • 在包含 azure.yaml 的目录中，创建任何缺失的环境。跳过你已经配置过的环境，并使用每个目标项目的订阅和区域：
azd env new development --subscription "<dev-subscription-id>" \
  --location "<dev-region>" --no-prompt
azd env new test --subscription "<test-subscription-id>" \
  --location "<test-region>" --no-prompt
azd env new production --subscription "<prod-subscription-id>" \
  --location "<prod-region>" --no-prompt

参考：azd env new。

  • 对开发、测试和生产分别运行下面这段，并为每个目标替换其中的值。保留该环境特有的任何额外模型、连接和运行时设置：
TARGET_ENV="test"

azd env set AZURE_TENANT_ID "<tenant-id>" -e "$TARGET_ENV"
azd env set AZURE_RESOURCE_GROUP "<resource-group>" -e "$TARGET_ENV"
azd env set AZURE_AI_PROJECT_ID "<project-resource-id>" -e "$TARGET_ENV"
azd env set FOUNDRY_PROJECT_ENDPOINT "<project-endpoint>" -e "$TARGET_ENV"
azd env set AZURE_AI_MODEL_DEPLOYMENT_NAME "<model-name>" -e "$TARGET_ENV"

参考：azd env set。

使用完整的项目 ARM 资源 ID 及其匹配的端点。每个项目需要自己的依赖和部署权限；切换环境不会复制这些资源或权限。

部署并测试这次发布

在任一 CI/CD 提供方中使用下面的顺序。把 my-agent 替换成你的服务名；这些示例使用 Responses 协议。

  • 在开发环境部署并测试：
TARGET_ENV="development"
azd deploy my-agent -e "$TARGET_ENV" --no-prompt
azd ai agent show my-agent -e "$TARGET_ENV" --output json --no-prompt
azd ai agent invoke my-agent "<feature-test-prompt>" \
  -e "$TARGET_ENV" --protocol responses \
  --new-session --new-conversation --no-prompt

参考：azd deploy，调用一个托管智能体。

确认智能体返回预期结果，并记录源代码提交。

  • 在测试作业或阶段检出同一提交。用 TARGET_ENV="test" 重复这些命令，然后运行你的回归测试和集成测试。如果代码或依赖发生变化，重复两个环境的检查。
  • 批准之后，在生产作业或阶段使用同一提交。在部署之前先遵循“逐步推出一个生产版本”，以保持稳定版本继续承接流量。

在流水线里应用这些阶段

用上面的顺序扩展你现有的流水线：

  • GitHub Actions：为开发、测试和生产使用有依赖关系的作业。把变量和机密限定到每个 GitHub 环境，并为生产批准配置环境保护规则。
  • Azure DevOps：使用有依赖关系的阶段，部署作业分别指向开发、测试和生产环境。把变量和服务连接限定到相应阶段，并在生产环境上配置批准和检查。

对任一提供方，在每个运行器或构建代理上配置所选的 azd 环境；本地 .azure 设置不会自动传递。把生产部署和路由变更串行化，并在提高候选版本流量份额之前要求批准。

逐步推出一个生产版本

金丝雀部署（canary deployment）把一小部分生产流量发给候选版本，稳定版本承接其余流量。两个版本使用同一个生产智能体端点。通过 agentEndpoint.versionSelector 和 azd ai agent endpoint update 改变流量；用 --version 测试某个特定候选版本。

下面的路由编辑使用一份隔离的生产检出。保持在测试中已批准的源代码修订不变，并把生产路由配置与你的发布记录一起保留。不要把生产版本号应用到开发或测试。

让稳定版本继续承接流量

在部署候选版本之前，识别当前的生产路由配置：

azd ai agent endpoint show my-agent -e production --output json --no-prompt

参考：Agent CLI 命令。

记录稳定版本和现有端点设置。下面的示例使用稳定版本 1 和候选版本 2。用你生产项目里的实际版本替换它们，而不是测试环境里的版本号。

  • 在生产检出的 azure.yaml 里，于 services.my-agent 下添加或更新这一段。保留服务配置的其余部分，包括任何端点协议和授权设置：
agentEndpoint:
  versionSelector:
    versionSelectionRules:
      - type: FixedRatio
        agentVersion: "1"
        trafficPercentage: 100
  • 应用稳定路由并读回：
azd ai agent endpoint update my-agent -e production --no-prompt
azd ai agent endpoint show my-agent -e production --output json --no-prompt

确认 version_selection_rules 把 100% 分给稳定版本。在部署新代码之前做这件事，并在部署期间保持这一段不动。

部署候选版本并启动金丝雀

在保持稳定路由已配置的情况下，部署已批准的源代码修订：

azd deploy my-agent -e production --no-prompt
azd ai agent show my-agent -e production --output json --no-prompt
azd ai agent endpoint show my-agent -e production --output json --no-prompt

确认候选版本处于活动状态，记录它的生产版本号，并验证端点仍然指向稳定版本。下面的示例假定新版本是 2。

  • 只改版本选择规则，把 10% 发给候选版本，90% 发给稳定版本：
agentEndpoint:
  versionSelector:
    versionSelectionRules:
      - type: FixedRatio
        agentVersion: "1"
        trafficPercentage: 90
      - type: FixedRatio
        agentVersion: "2"
        trafficPercentage: 10
  • 不重新部署代码，只应用这次变更：
azd ai agent endpoint update my-agent -e production --no-prompt
azd ai agent endpoint show my-agent -e production --output json --no-prompt

确认返回的规则包含两个生产版本，以及预期的百分比。端点更新改变路由，不会再创建一个智能体版本。

测试候选版本

用 --version 选择候选版本，并为这次测试开始一个新的会话和对话。发送一条只读提示，以演练新功能：

azd ai agent invoke my-agent "<candidate-feature-test-prompt>" \
  -e production --protocol responses --version 2 \
  --new-session --new-conversation --no-prompt

检查响应，并对照你的预期结果确认新行为。你也可以把应用程序的测试客户端指向生产智能体端点，并运行端到端功能检查。在批准更多流量之前，在金丝雀期间查看错误、延迟和响应质量。

对于使用 Invocations 协议的智能体，提供一份与其处理程序匹配的载荷：

azd ai agent invoke my-agent --input-file candidate-test.json \
  -e production --protocol invocations --version 2 --new-session --no-prompt

用一条已知的、只读的智能体请求创建 candidate-test.json，并检查返回结果。--version 标志为该会话选择版本；它不改变已配置的流量百分比。

提高流量，或回到稳定版本

测试成功之后，调整两个百分比，应用端点更新，并在每个阶段查看结果。总和保持为 100%。例如，在完成发布之前，从 90/10 移到 50/50。

要完成这次发布，用一条只针对候选版本的规则替换选择规则：

agentEndpoint:
  versionSelector:
    versionSelectionRules:
      - type: FixedRatio
        agentVersion: "2"
        trafficPercentage: 100

应用并验证完整发布：

azd ai agent endpoint update my-agent -e production --no-prompt
azd ai agent endpoint show my-agent -e production --output json --no-prompt

如果一次金丝雀检查失败，停止提高流量。用稳定版本 100% 替换这些规则：

agentEndpoint:
  versionSelector:
    versionSelectionRules:
      - type: FixedRatio
        agentVersion: "1"
        trafficPercentage: 100

运行同样的端点更新和显示命令，以应用并验证回到稳定版本。这次操作不重新构建代码，也不创建另一个版本。在这次发布被接受之前，保留可用的稳定版本。

把最终路由配置与生产发布设置一起保存。把它作为下一次部署的起点，这样后续流水线运行就不会重新应用一份过时的流量拆分。

PRIMARY_SOURCE: https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/deploy-hosted-agent-production

  • #Microsoft Foundry
  • #金丝雀部署
  • #azd
  • #托管智能体
  • #回滚

继续阅读