可易

测试 Microsoft Foundry 托管智能体

可易团队阅读约 5 分钟

说明如何对 Microsoft Foundry 托管智能体做单元测试、本地与已部署集成测试，并用 azd 评估作为上线前质量门。

目录

#测试 Microsoft Foundry 托管智能体

在不同层级测试你的托管智能体（hosted agent），从对单个组件做单元测试，到对已部署的 Microsoft Foundry 智能体做端到端集成测试。你还会了解何时使用结构化的 azd ai agent eval 运行，而不是临时的调用测试。

前提条件

  • 一个已初始化的托管智能体项目，其中包含智能体代码和测试。要创建项目，见初始化智能体项目（https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/init-agent-project）。
  • 已安装 azd Foundry 扩展。安装步骤见安装 azd Foundry 扩展（https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/install-cli-foundry-extensions）。
  • 一个已认证的 Azure Developer CLI 会话。如有需要，运行 azd auth login。
  • 你所用语言所需的测试工具，例如 Python 的 pytest 或 .NET 的 xUnit。
  • 对于已部署集成测试和结构化评估（evaluation），需要一个已部署的托管智能体。要部署一个，见部署托管智能体（https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/deploy-hosted-agent）。

选择测试层级

层级你测试的内容工具速度
单元测试智能体逻辑、工具处理程序、提示格式化pytest / xUnit快（数秒）
本地集成在本地针对真实模型运行的完整智能体azd ai agent run + invoke --local中等（每次请求数秒）
已部署集成在 Foundry 基础设施上运行的智能体azd ai agent invoke较慢（包含网络往返）
结构化评估用自适应评估器对照数据集为智能体打分azd ai agent eval较慢（长时间运行操作，long-running operation, LRO）

对智能体逻辑做单元测试

测试智能体的核心逻辑，而不运行完整服务器或调用外部模型。

  • Python
  • C#
# test_agent.py
import pytest
from unittest.mock import MagicMock

def test_tool_handler_returns_expected_format():
    """Test that your tool handler returns valid output."""
    from my_agent.tools import weather_tool

    result = weather_tool("Seattle")
    assert "temperature" in result
    assert isinstance(result["temperature"], (int, float))

def test_system_prompt_includes_required_context():
    """Verify system prompt contains key instructions."""
    from my_agent.config import SYSTEM_PROMPT

    assert "helpful assistant" in SYSTEM_PROMPT.lower()
    assert "weather" in SYSTEM_PROMPT.lower()
pytest test_agent.py
// AgentTests.cs
using Xunit;

public class AgentTests
{
    [Fact]
    public void ToolHandler_ReturnsExpectedFormat()
    {
        var result = WeatherTool.GetWeather("Seattle");
        Assert.Contains("temperature", result.Keys);
    }

    [Fact]
    public void SystemPrompt_IncludesRequiredContext()
    {
        Assert.Contains("helpful assistant",
            AgentConfig.SystemPrompt, StringComparison.OrdinalIgnoreCase);
    }
}
dotnet test

运行本地集成测试

在本地测试完整智能体，包括模型调用和协议处理。

用 invoke 做手工测试

  1. 在一个终端中启动智能体，在另一个终端中发送测试消息：
# Terminal 1: Start the agent
azd ai agent run

# Terminal 2: Send test messages
azd ai agent invoke --local "What's the weather in Seattle?"
azd ai agent invoke --local "Can you summarize this document?" -f test-doc.json

用 curl 测试

  1. 对于可重复的测试，使用 curl 或任意 HTTP 客户端：
# Check the readiness probe (expects HTTP 200)
curl -i http://localhost:8088/readiness

# Test the responses protocol
curl -s -X POST http://localhost:8088/responses \
  -H "Content-Type: application/json" \
  -d '{"input": "Hello, what can you do?"}' | jq .

# Test with a specific session
curl -s -X POST http://localhost:8088/responses \
  -H "Content-Type: application/json" \
  -d '{"input": "Follow up question", "metadata": {"session_id": "test-session-1"}}' | jq .

自动化本地测试

把本地集成测试包进一个脚本，由它启动智能体、运行测试并清理。

#!/bin/bash
# test-integration.sh

# Start agent in background
azd ai agent run --port 9090 &
AGENT_PID=$!
sleep 5  # Wait for startup

# Run tests
RESPONSE=$(curl -s -X POST http://localhost:9090/responses \
  -H "Content-Type: application/json" \
  -d '{"input": "Say hello"}')

echo "$RESPONSE" | jq -e '.output' > /dev/null
if [ $? -eq 0 ]; then
  echo "[x] Basic invoke test passed"
else
  echo "[!] Basic invoke test failed"
  echo "$RESPONSE"
fi

# Cleanup
kill $AGENT_PID

运行已部署集成测试

部署到 Foundry 之后，核验智能体端到端可用。

# Deploy
azd up

# Test basic invoke
azd ai agent invoke "Hello, what can you do?"

# Test with a new session
azd ai agent invoke --new-session "Start a fresh conversation"

# Test with file input
azd ai agent invoke -f test-request.json

运行结构化评估

一旦智能体开始做有意义的事，临时的 invoke 调用就不再是可靠信号。你改了一个提示（prompt）或换了一个工具，跑了几条提示，现在需要判断这次改动总体上是不是更好。azd ai agent eval 是超出临时调用测试的结构化路径：它对照固定数据集运行你的智能体，并用一个或多个评估器为响应打分，从而使同一次改动每次都能以相同方式衡量。

选择结构化评估

在以下情况使用结构化评估：

  • 你更改了提示、工具或模型，并想知道这次更改是有帮助还是有损害。
  • 不止一个人在编辑智能体，非正式的冒烟测试不再覆盖足够的范围。
  • 你想要一个可以接入持续集成（continuous integration, CI）的质量门，以自动捕获回归。

初始化评估资产

  • 在智能体部署之后运行此命令一次，通常就在你第一次 azd up 之后：
azd ai agent eval generate

这是一个需要数分钟的长时间运行操作。它会生成一个很小的冒烟数据集、一个范围限定在你的智能体行为上的默认自适应评估器，以及一个可运行的 eval.yaml。传入 --reset-defaults 可覆盖现有配置。

运行一次评估

  • 一旦存在 eval.yaml，就运行评估并查看结果：
azd ai agent eval run
azd ai agent eval show --eval-run-id <run-id>

eval run 默认解析智能体项目根目录中的 eval.yaml，并报告每个评估器的分数，以便你准确看到智能体在何处回归。使用 --config <file> 指向特定配方，使用 --no-wait 提交后脱离等待。用 eval show 查看运行历史和详情。

提升为共享套件

把 eval.yaml 与智能体代码一起做版本管理，并在 CI 中用 azd ai agent eval run --config eval.yaml 运行同一配方。当前命令界面没有 eval suites 子命令。

若要明确的通过率质量门，安装可选的 azure.ai.evaluations 扩展（https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/install-cli-foundry-extensions）。用 azd ai eval init 搭建评估脚手架，然后用 azd ai eval create 注册已配置的资产。该工作流使用 evals/azure.eval.yaml，而不是快速评估的 eval.yaml。质量门命令见在 CI 中用评估核验（https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/set-up-ci-cd-cli#verify-with-eval-in-ci）。

生产前核验

在把智能体投入生产之前，使用此清单做核验：

  • [ ] 智能体启动时没有错误（azd ai agent run）
  • [ ] 就绪探测返回 200（curl localhost:8088/readiness）
  • [ ] 基本调用返回有效响应
  • [ ] 智能体能妥善处理无效输入（不会崩溃）
  • [ ] 智能体在可接受的时限内响应
  • [ ] 会话持久化可用（多轮对话）
  • [ ] 已部署智能体有响应（不带 --local 的 azd ai agent invoke）
  • [ ] 日志显示预期行为（azd ai agent monitor --follow）

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

  • #Foundry
  • #托管智能体
  • #测试
  • #评估
  • #质量门

继续阅读