Testing Google ADK TypeScript Agents Without Chasing Sentences

Google's Agent Development Kit (ADK) for TypeScript enables developers to test AI agents deterministically by focusing on tool contracts and runtime behavior rather than model-generated sentences. The approach layers tests from deterministic unit tests for tools to small human-reviewed evals, ensuring reliability without chasing exact wording.

The fastest way to make an AI-agent test flaky is to assert the final sentence. You expect: I'll help you find hotels in Paris. The agent returns: Sure — I can look for hotel options in Paris. The behavior is correct, but the test is red. Google's Agent Development Kit ADK brings agents closer to conventional software engineering: agents, tools, orchestration, sessions, events, evaluation, and deployment are represented as code and runtime primitives. That does not make the model deterministic. It gives us better places to establish deterministic contracts around it. Do not test the agent's personality. Test its decisions and boundaries. A useful agent test suite has four layers: ┌──────────────────────────┐ │ Small human-reviewed evals│ ┌──┴──────────────────────────┴──┐ │ End-to-end trajectory scenarios │ ┌──┴──────────────────────────────────┴──┐ │ Runtime contracts: policy, state, schema │ ┌──┴──────────────────────────────────────────┴──┐ │ Deterministic unit tests for tools and adapters │ └─────────────────────────────────────────────────┘ Most tests should live near the bottom. They are fast, cheap, and deterministic. Use live-model evaluations deliberately, not for every assertion. ADK TypeScript tools can be expressed with FunctionTool and a Zod parameter schema. The business function underneath is still ordinary TypeScript and should be tested that way. js 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, } ; The first test should not involve Gemini or ADK's event loop: js 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, } ; } ; Tool permissions, data mapping, error normalization, and idempotency do not become probabilistic merely because a model selected the tool. For an integration test, run the ADK agent and collect its events. Convert framework events into a small application-owned summary so your tests are not coupled to every internal event detail. js 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 is deliberately your adapter. It can return a stable contract such as: type TrajectorySummary = { toolCalls: Array<{ name: string; args: unknown } ; blockedActions: string ; clarificationRequested: boolean; finalText: string; }; Now the assertion describes behavior: js 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 ; } ; The wording may vary. The prohibited side effect may not. Happy-path prompts are not enough. Production failures usually live at the boundary between a plausible request and an unsafe action. js 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", }, ; Important scenario families include: A safety test should ideally pass because an application policy blocked the action, not because the model happened to decline it. If downstream code depends on an agent-produced object, treat it like an external API response. js 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 ; Schema validity does not prove semantic correctness, but it prevents an entire class of integration failures: invented enum values, missing fields, strings where numbers are expected, or unexpected nullable values. The most valuable scenario often arrives through an incident. If an agent selected the wrong tool, repeated a notification, skipped confirmation, or treated an empty result as a failure, preserve a privacy-safe version of that trajectory. Add it to a regression dataset with: { "caseId": "booking-confirmation-regression-017", "input": "Reserve the first one", "state": { "selectedHotelId": "hotel-42" }, "required": "request confirmation" , "forbidden": "book hotel" , "terminalOutcome": "awaiting user confirmation" } Replay does not mean expecting the original sentence. It means recreating the operational conditions that exposed the bug. Use two lanes: ADK's broader tooling supports evaluation and scoring, but your application still needs explicit pass/fail rules. A single aggregate quality score should never hide a prohibited tool call. Track hard constraints separately from soft quality: Hard: no unauthorized write, valid schema, confirmation preserved Soft: relevance, completeness, tone, concision Operational: latency, model calls, tool calls, retries, estimated cost This makes failures actionable. A tone regression and an unauthorized booking are not the same severity. Agent testing is not about pretending the model is deterministic. It is about making the system around the model explicit. Test tools as ordinary code. Test policies without depending on model goodwill. Validate structured outputs. Assert required and forbidden transitions. Replay real failures. Use live-model evaluations where semantic judgment is actually needed. Let sentences vary. Do not let safety, state, or tool boundaries vary with them.