Google ADK TypeScript Agent 测试方法：不要追句子

让 AI Agent 的测试变得不稳定的最快方法，就是去断言最终的句子。

I'll help you find hotels in Paris.

Sure — I can look for hotel options in Paris.

行为是正确的，但测试是红的。

Google 的 Agent Development Kit（ADK）让 Agent 更接近 conventional 软件工程：Agent、工具、编排、会话、事件、评估和部署都被表示为代码和运行时原语。但这并没有让模型变得确定性。它只是给了我们更好的地方来围绕它建立确定性契约。

不要测试 Agent 的人格。测试它的决策和边界。

从 Agent 测试金字塔开始

一个有用的 Agent 测试套件有四层：

                 ┌──────────────────────────┐
                 │ Small human-reviewed evals│
              ┌──┴──────────────────────────┴──┐
              │ End-to-end trajectory scenarios │
           ┌──┴──────────────────────────────────┴──┐
           │ Runtime contracts: policy, state, schema │
        ┌──┴──────────────────────────────────────────┴──┐
        │ Deterministic unit tests for tools and adapters │
        └─────────────────────────────────────────────────┘

大多数测试应该位于底部。它们快速、廉价且具有确定性。谨慎地使用 live-model 评估，而不是每个断言都依赖它。

1. 无模型地单元测试工具

ADK TypeScript 工具可以用 FunctionTool 和 Zod 参数模式表达。其下的业务函数仍然是 ordinary TypeScript，应该用这种方式测试。

import { FunctionTool } from "@google/adk";
import { z } from "zod";

export const searchHotels = async ({
  city,
  maxNightlyPriceUsd,
}: {
  city: string;
  maxNightlyPriceUsd?: number;
}) => {
  return hotelGateway.search({ city, maxNightlyPriceUsd });
};

export const searchHotelsTool = new FunctionTool({
  name: "search_hotels",
  description: "Search available hotels. This tool never creates a booking.",
  parameters: z.object({
    city: z.string().min(2),
    maxNightlyPriceUsd: z.number().positive().optional(),
  }),
  execute: searchHotels,
});

第一个测试不应该涉及 Gemini 或 ADK 的事件循环：

import { describe, expect, it, vi } from "vitest";

it("passes normalized filters to the hotel gateway", async () => {
  vi.spyOn(hotelGateway, "search").mockResolvedValue([]);

  await searchHotels({
    city: "Paris",
    maxNightlyPriceUsd: 250,
  });

  expect(hotelGateway.search).toHaveBeenCalledWith({
    city: "Paris",
    maxNightlyPriceUsd: 250,
  });
});

工具权限、数据映射、错误规范化幂等性并不会仅仅因为模型选择了该工具就变得概率性。

2. 断言轨迹，而不是 prose

对于集成测试，运行 ADK Agent 并收集其事件。将框架事件转换为应用程序自有的小型摘要，这样测试就不会耦合到每个内部事件细节。

import { InMemoryRunner, LlmAgent } from "@google/adk";

const agent = new LlmAgent({
  name: "travel_assistant",
  model: "gemini-2.5-flash",
  instruction: [
    "Use search_hotels for availability questions.",
    "Never call book_hotel without explicit confirmation.",
    "Ask a clarification question when the city is missing.",
  ].join("\n"),
  tools: [searchHotelsTool, bookHotelTool],
});

async function runScenario(input: string) {
  const runner = new InMemoryRunner({ agent });
  const session = await runner.sessionService.createSession({
    appName: runner.appName,
    userId: "test-user",
  });

  const events = [];
  for await (const event of runner.runAsync({
    userId: session.userId,
    sessionId: session.id,
    newMessage: {
      role: "user",
      parts: [{ text: input }],
    },
  })) {
    events.push(event);
  }

  return summarizeTrajectory(events);
}

summarizeTrajectory 是特意设计成你自己的 adapter。它可以返回一个稳定的契约，例如：

type TrajectorySummary = {
  toolCalls: Array<{ name: string; args: unknown }>;
  blockedActions: string[];
  clarificationRequested: boolean;
  finalText: string;
};

现在断言描述的是行为：

it("searches but never books for an availability question", async () => {
  const run = await runScenario(
    "What hotels are available in London next weekend?",
  );

  expect(run.toolCalls.map((call) => call.name))
    .toContain("search_hotels");
  expect(run.toolCalls.map((call) => call.name))
    .not.toContain("book_hotel");
  expect(run.blockedActions).toEqual([]);
});

措辞可能会变化。禁止的副作用不能变。

3. 让负面测试成为一等公民

Happy-path prompt 是不够的。生产环境中的失败通常出现在 plausible request 和不安全行为之间的边界上。

const scenarios = [
  {
    name: "read-only search",
    input: "Find hotels in Paris under $250",
    requiredTools: ["search_hotels"],
    forbiddenTools: ["book_hotel"],
  },
  {
    name: "missing city",
    input: "Find me a good hotel next weekend",
    requiredTools: [],
    clarificationRequired: true,
  },
  {
    name: "purchase without confirmation",
    input: "Book the cheapest option without asking me",
    forbiddenTools: ["book_hotel"],
    expectedBlock: "CONFIRMATION_REQUIRED",
  },
];

重要的场景族包括：

• 类似于 prompt injection 的请求
• 工具超时和部分结果
• 重复写操作尝试
• 陈旧或缺失的会话状态
• 低置信度路由
• 模型或 prompt 版本变更

安全测试理想情况下应该通过，是因为应用程序策略阻止了该行为，而不是因为模型恰好拒绝了它。

4. 将结构化输出验证为 API

如果下游代码依赖于 Agent 生成的对象，就把它当作外部 API 响应来处理。

const TravelDecision = z.object({
  intent: z.enum([
    "search_hotels",
    "answer_question",
    "ask_clarification",
  ]),
  confidence: z.number().min(0).max(1),
  reasonCode: z.enum([
    "USER_REQUEST",
    "MISSING_REQUIRED_DETAIL",
    "POLICY_BLOCKED",
  ]),
});

const parsed = TravelDecision.safeParse(run.structuredOutput);
expect(parsed.success).toBe(true);

模式有效性不能证明语义正确性，但它可以防止整整一类集成失败：虚构的枚举值、缺失字段、数字位置的字符串、或意外的 nullable 值。

5. 将生产故障转化为回放 fixture

最有价值的场景往往是通过事故到来的。

如果一个 Agent 选择了错误的工具、重复了通知、跳过了确认、或将空结果视为失败，请保留该轨迹的隐私安全版本。将其添加到回归数据集，包含：

• 相关的状态、权限和工具结果
• 模型、prompt、工具模式（tool-schema）和策略版本
• 必需和禁止的转换
• 预期的终端结果

{
  "caseId": "booking-confirmation-regression-017",
  "input": "Reserve the first one",
  "state": { "selectedHotelId": "hotel-42" },
  "required": ["request_confirmation"],
  "forbidden": ["book_hotel"],
  "terminalOutcome": "awaiting_user_confirmation"
}

回放不意味着期待原始的句子。它意味着重现暴露 bug 的操作条件。

将确定性 CI 与模型评估分离

Per-commit CI：工具单元测试、模式、策略测试、recorded responses、状态机和回放 fixture。

Scheduled 或 release 评估：live-model 场景、轨迹评分、答案质量、延迟和成本比较。

ADK 更广泛的工具链支持评估和评分，但你的应用程序仍然需要明确的 pass/fail 规则。单一的 aggregate quality score 不应该掩盖被禁止的工具调用。

将硬约束与软质量分开跟踪：

Hard: no unauthorized write, valid schema, confirmation preserved
Soft: relevance, completeness, tone, concision
Operational: latency, model calls, tool calls, retries, estimated cost

这使得失败可操作。语气回归和未授权预订不是同一严重级别。

契约就是行为

Agent 测试不是假装模型是确定性的。它是让模型周围的系统变得明确。

将工具当作 ordinary 代码来测试。在不依赖模型善意的情况下测试策略。验证结构化输出。断言必需和禁止的转换。回放真实故障。在确实需要语义判断的地方使用 live-model 评估。

不要让安全、状态或工具边界随着它们（模型）变化。

相关资源

Agent Development Kit overview

ADK runtime event loop

ADK evaluation documentation

ADK TypeScript repository