测试、部署和集成代理

  • 9 分钟

测试、部署和发布代理是从开发迁移到生产的关键步骤。 Microsoft Foundry 提供了用于验证代理行为、部署到 Foundry 项目以及将代理发布为外部使用者和应用程序可以使用的可调用终结点的综合功能。

代理的测试策略

彻底测试可确保代理在访问用户之前在各种方案中可靠地运行。 Foundry 门户和 Visual Studio Code 扩展都提供用于交互式测试的沙盒。

有效地使用操场：

  • 最佳路径测试 - 验证代理是否正确处理常见的预期请求。
  • 边缘用例测试 - 尝试不明确的输入、不完整的信息和异常请求，以揭示代理如何处理不确定性。
  • 边界测试 - 通过测试范围外请求来确认代理遵循其指令中定义的边界。
  • 多轮次对话测试 - 验证代理在多次对话交流中保持上下文，并在之前的响应基础上进一步发展。
  • 工具调用测试 - 验证代理在正确的时间调用正确的工具，并正确合并结果。

记录测试结果以跟踪改进并捕获回归。

将代理程序部署到您的项目中

Microsoft Foundry 支持从门户或 Visual Studio Code 部署代理。 部署会将代理配置保存到 Foundry 项目，以便可以测试和迭代。

将应用从 Foundry 门户进行部署

  1. 在 Foundry 门户中访问您的代理
  2. 验证配置和测试结果是否令人满意
  3. 从代理的页面选择 “保存”
  4. 确认版本和部署设置

从Visual Studio Code部署

  1. 在 AI 工具包中打开代理
  2. 选择 “保存到 Foundry ”以推送配置更改
  3. 对于托管代理，请在开发人员工具中打开 “+生成 ”菜单，然后选择“ 部署到Microsoft Foundry
  4. 选择容器配置并确认

这两种方法将代理保留在项目工作区中，团队成员可以访问并测试它。

将代理发布到终结点

发布指将代理从项目工作区移动到一个名为“代理应用程序”的 Azure 托管资源。 此步骤使代理可以通过稳定的终结点进行外部调用。

发布创建了什么

发布代理版本时，Foundry 会创建：

  • 代理应用程序 - 具有自己的调用 URL、身份验证策略和 Entra 代理标识的 Azure 资源。
  • 部署 - 应用程序中特定代理版本的正在运行实例，其中包含启动/停止生命周期管理。

部署和发布之间的主要区别在于范围。 部署会将软件代理保留在项目中。 发布创建一个专用终结点，外部使用者可以调用该终结点，而无需访问 Foundry 项目。

从 Foundry 平台发布

  1. 在门户中，选择要发布的代理版本
  2. 选择 “发布 ”以创建代理应用程序和部署

从 Visual Studio Code 中发布

  1. 打开命令面板（Ctrl+Shift+P），并运行 Microsoft Foundry：为托管代理部署托管代理
  2. 选择目标工作区和容器配置
  3. 确认和部署

发布后，代理将显示在 AI 工具包扩展树视图的 “托管代理”（预览） 部分中。

代理应用程序终结点

已发布的代理使用Responses API协议提供稳定的端点：

https://<foundry-resource-name>.services.ai.azure.com/api/projects/<project-name>/applications/<app-name>/protocols/openai/responses

即使推出新的代理版本，此 URL 也保持不变，因此下游使用者不会因更新而中断。

身份验证和标识

代理应用程序使用 Microsoft Entra ID 进行身份验证。 调用方必须在代理应用程序资源上具有 Azure AI 用户 角色。 代理应用程序不支持 API 密钥身份验证。

重要

当您发布代理时，它会获得其专有的 Entra 标识，与项目的共享标识相区分。 权限不会自动传输。 对于智能体访问的任何资源，必须将 RBAC 角色重新分配给新的智能体标识。 如果跳过此步骤，则发布代理后，在开发过程中工作的工具调用会失败，并出现授权错误。

验证终结点

发布后，验证终结点是否正常工作：

  1. 获取访问令牌：

    az account get-access-token --resource https://ai.azure.com

  2. 调用代理应用程序终结点：

    curl -X POST \
  "https://<foundry-resource-name>.services.ai.azure.com/api/projects/<project-name>/applications/<app-name>/protocols/openai/responses?api-version=2025-11-15-preview" \
  -H "Authorization: Bearer <access-token>" \
  -H "Content-Type: application/json" \
  -d '{"input":"Say hello"}'

如果收到 403 Forbidden，请确认调用方在代理应用程序资源上具有 Azure AI 用户 角色。

更新已发布的代理

若要推出新的代理版本，请执行以下操作：

  1. 在开发环境中进行更改并彻底测试
  2. 在 Foundry 门户中，从智能体操场中选择“发布更新”
  3. 代理应用程序自动将 100% 流量路由到新版本

终结点 URL 保持不变，因此现有集成将继续工作。

生成集成代码

Microsoft Foundry VS Code 扩展生成示例集成代码，以便将应用程序连接到已发布的代理：

  1. 在“我的资源”视图中选择已部署的代理
  2. 选择“查看代码”
  3. 选择文件夹
  4. 该扩展生成用于对消息进行身份验证、连接、发送消息和处理响应的代码

集成模式

集成已发布代理的常见模式包括：

  • Web 应用程序 - 将用户消息发送到响应 API 终结点，并在 UI 中显示响应。 将会话历史存储在客户端，以支持多轮交互。
  • API 驱动的工作流 - 从事件或计划触发的后端服务调用代理终结点。 以编程方式处理响应以驱动下游操作。
  • 聊天机器人接口 - 将用户会话映射到对话。 通过终结点处理实时消息交换。
  • 后台自动化 - 安排代理程序调用以执行定期任务。 将系统数据馈送到代理中，并处理输出以更新业务系统。

生产注意事项

在生产环境中运行智能体需要注意多个操作领域：

  • 监视 - 使用 Application Insights 集成跟踪响应时间、工具调用成功率、错误模式和令牌消耗。
  • 安全性 - 使用托管标识进行身份验证、应用最低特权访问和定义数据保留策略。
  • 成本管理 - 监视令牌使用情况、设置响应长度限制，并实施速率限制以防止意外峰值。
  • 错误处理 - 实现具有指数退避的重试逻辑以应对瞬时性故障。 使用退避策略处理速率限制。 在发送到代理之前验证输入。
  • 对话管理 - 代理应用程序终结点当前仅支持无状态响应 API。 在客户端中存储对话历史记录，以便进行多轮次体验。