Google ADK for TypeScript: Build Type-Safe AI Agents with Code-First Approach

TypeScript developers building AI agents face an annoying paradox. You write type-safe code all day, but the moment you integrate an LLM framework, those types evaporate into JSON schemas and runtime validation hell. You’re either maintaining duplicate type definitions or crossing your fingers that your tool schemas match reality. Google’s Agent Development Kit (ADK) for TypeScript cuts through this mess with a code-first approach that treats TypeScript as a first-class citizen, not an afterthought. Released in version 0.2.0 on December 17, 2025, Google ADK TypeScript uses Zod schemas as the single source of truth for both compile-time types and runtime validation. This tutorial walks you through building type-safe AI agents that actually feel like TypeScript development, not glorified string templating.

Why ADK Matters for TypeScript Developers

Most AI agent frameworks bolt TypeScript support on as an afterthought, forcing you to define tool schemas in JSON or YAML and then manually write corresponding TypeScript types. The Google ADK TypeScript implementation flips this model entirely. You define your tools with Zod schemas, and those schemas serve double duty as both runtime validators and compile-time type sources.

ADK ships with native multi-agent orchestration patterns built in. SequentialAgent chains tasks in order, ParallelAgent runs operations concurrently, and LoopAgent handles iterative refinement workflows. You’re not hacking together agent coordination with brittle state machines or manual Promise juggling. These patterns are first-class primitives in the framework.

While ADK is model-agnostic and works with any LLM provider, it’s optimized for Google’s Gemini models with tuned prompts and native multimodal support. The framework integrates with Google’s AI ecosystem without locking you in. For broader context on how ADK fits into the emerging agentic AI landscape, see our Agentic AI Foundation explainer covering OpenAI and Anthropic’s competing standards.

Getting Started with Google ADK TypeScript

Installation requires three packages: the core ADK runtime, developer tools, and Zod for schema validation. Run this command to get everything:

npm install @google/adk @google/adk-devtools zod

Your project needs ESM module support enabled in package.json. ADK doesn’t support CommonJS, which is the right call in 2026. Add this to your package.json:

{
  "type": "module",
  "scripts": {
    "dev": "npx adk web",
    "start": "npx adk run"
  }
}

Your tsconfig.json needs module resolution that supports ESM. Use these settings as a baseline:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ES2022",
    "moduleResolution": "bundler",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true
  }
}

Set your Google API key as an environment variable. Create a .env file in your project root:

GOOGLE_API_KEY=your_api_key_here

The official TypeScript Getting Started guide covers additional setup details for different deployment targets.

Type-Safe Tools with Zod

The killer feature of Google ADK TypeScript is Zod-powered tool definitions. You write one schema, and that schema generates TypeScript types while also validating inputs at runtime. No duplicate definitions, no drift between your types and your validation logic.

A FunctionTool wraps a Zod schema and a handler function. The schema defines the input structure, and TypeScript infers the handler’s parameter types from that schema automatically. Here’s a complete example of a weather lookup tool:

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

const weatherSchema = z.object({
  location: z.string().describe('City name or ZIP code'),
  units: z.enum(['fahrenheit', 'celsius']).default('fahrenheit')
});

export const weatherTool = new FunctionTool({
  name: 'get_weather',
  description: 'Get current weather for a location',
  schema: weatherSchema,
  handler: async (input) => {
    // input is fully typed as { location: string; units: 'fahrenheit' | 'celsius' }
    const response = await fetch(
      `https://api.weather.example.com?location=${input.location}&units=${input.units}`
    );
    return response.json();
  }
});

Notice how the handler function gets a fully typed input parameter without any manual type annotations. Zod’s z.infer does the heavy lifting. The .describe() method adds descriptions that show up in the LLM’s tool documentation, helping the model understand when to use each parameter.

This pattern scales beautifully to complex tools with nested objects, arrays, unions, and optional fields. Zod’s composition operators let you build sophisticated schemas that stay maintainable. The Function Tools documentation covers advanced patterns like streaming responses and error handling.

If you’re building tools that need to integrate with external systems, consider checking out our Building MCP Servers Tutorial for patterns on creating reusable tool interfaces across different AI frameworks.

Building Your First Agent

An LlmAgent is Google ADK TypeScript’s basic building block for single-agent workflows. You configure it with tools, a model, and an instruction prompt. The agent handles the reasoning loop, tool calling, and response generation automatically.

Here’s a complete working agent that can look up weather and answer questions about it:

import { LlmAgent, InMemoryRunner } from '@google/adk';
import { weatherTool } from './tools.js';

const agent = new LlmAgent({
  name: 'weather_assistant',
  model: 'gemini-2.0-flash-exp',
  instruction: `You are a weather assistant. Use the get_weather tool to look up current conditions.
  Provide concise, helpful responses with temperature and conditions.`,
  tools: [weatherTool]
});

// Run the agent
const runner = new InMemoryRunner(agent);
const result = await runner.run({
  message: "What's the weather in Seattle?"
});

console.log(result.output);

The InMemoryRunner executes the agent with in-memory state management. It’s perfect for development and testing. The agent sees the user message, decides whether to call tools, interprets tool results, and generates a natural language response. You get full logs of the reasoning trace for debugging.

The model parameter accepts any Gemini model identifier. As of v0.2.0, gemini-2.0-flash-exp offers the best balance of speed and capability for most agent tasks. For production deployments, you’ll swap InMemoryRunner for a persistence-backed runner that survives restarts.

Multi-Agent Workflows

Single agents hit limits quickly when you need complex task decomposition or parallel processing. Google ADK TypeScript provides three workflow agent types that coordinate multiple sub-agents with different orchestration patterns.

SequentialAgent runs a series of agents in order, passing output from each agent as input to the next. This is your go-to for multi-step workflows where each stage depends on previous results:

import { SequentialAgent, LlmAgent } from '@google/adk';

const researchAgent = new LlmAgent({
  name: 'researcher',
  model: 'gemini-2.0-flash-exp',
  instruction: 'Research the given topic and provide key facts.',
  tools: [searchTool]
});

const writerAgent = new LlmAgent({
  name: 'writer',
  model: 'gemini-2.0-flash-exp',
  instruction: 'Write a blog post using the research provided.'
});

const pipeline = new SequentialAgent({
  name: 'content_pipeline',
  agents: [researchAgent, writerAgent]
});

const result = await runner.run(pipeline, {
  message: 'Create a blog post about quantum computing'
});

ParallelAgent runs multiple agents concurrently and aggregates their results. Use this when you have independent subtasks that can execute simultaneously. LoopAgent executes an agent repeatedly until a condition is met or a maximum iteration count is reached, perfect for iterative refinement tasks like code debugging or optimization.

The Workflow Agents documentation provides detailed examples of each pattern with best practices for task decomposition. Here’s when to use each type:

Agent Type	Use Case	Example
SequentialAgent	Dependent multi-step tasks	Research → Outline → Write → Edit
ParallelAgent	Independent concurrent tasks	Translate to 5 languages simultaneously
LoopAgent	Iterative refinement	Generate code → Test → Fix → Repeat until tests pass

CLI and Development Tools

Google ADK TypeScript ships with CLI tools that streamline development and deployment. The npx adk run command executes your agent in the terminal with a REPL interface for interactive testing. You type messages, see the agent’s reasoning process, and inspect tool calls in real-time.

The npx adk web command launches a browser-based UI for agent development. This interface provides a richer debugging experience with visual tool call inspection, state management, and conversation history. It’s especially useful when developing multi-agent workflows where you need to see how agents coordinate.

For starting new projects, npx adk create scaffolds a complete TypeScript agent project with sensible defaults, example tools, and deployment configuration. The generator creates projects ready to deploy to Google Cloud Run with a single command.

The ADK GitHub repository contains example projects showing production deployment patterns, integration tests, and CI/CD workflows. The examples cover everything from simple single-agent bots to complex multi-agent systems with custom tool implementations.

For production safety patterns when deploying AI agents, see our Claude Code Hooks Tutorial which covers validation, sandboxing, and automated safety checks that apply to any agent framework.

Conclusion

Google ADK TypeScript finally gives TypeScript developers an AI agent framework that respects their tooling and workflow. Zod-powered type safety eliminates the dual-maintenance nightmare of separate schemas and types. Native workflow agents make multi-agent orchestration a design primitive rather than an implementation afterthought. The code-first approach means you’re writing TypeScript that happens to build agents, not configuration files that happen to have some TypeScript sprinkled in.

Version 0.2.0 is production-ready for most use cases, though the framework is still evolving rapidly. Google is actively developing the ecosystem with new model integrations, tool patterns, and deployment targets. Start with the official TypeScript guide to build your first agent, then explore the workflow patterns that match your use case. TypeScript’s type system finally has an AI agent framework worthy of it.