Building AI Agents with the TypeScript Agent Development Kit (ADK)
DEV Community

Building AI Agents with the TypeScript Agent Development Kit (ADK)

Requirements

  • Node.js 20 or newer
  • A Gemini API key, or Google Cloud credentials for Vertex AI

Setup

npm install
cp .env.example .env

Edit .env and choose one authentication method:

  • Gemini Developer API: set GOOGLE_API_KEY
  • Vertex AI: set GOOGLE_GENAI_USE_VERTEXAI=TRUE, GOOGLE_CLOUD_PROJECT, and GOOGLE_CLOUD_LOCATION, then run gcloud auth application-default login

Never commit .env.

Run

# Interactive terminal
npm start

# ADK development UI
npm run web

# Type-check and run unit tests
npm run check

The ADK CLI can also be called directly:

npx adk run src/agent.ts
npx adk web

The agent source is in src/agent.ts. Its two local tools preserve the original sample behavior: weather and local time are available for New York, while other cities return a clear unsupported-city result.

What Is TypeScript?

TypeScript is a strongly typed programming language built on top of JavaScript, maintained by Microsoft. It compiles to plain JavaScript and runs anywhere JavaScript runs - including Node.js, which is what the ADK for TypeScript targets. The static type system pairs naturally with agent development: tool parameters, tool results, and agent configuration are all checked at compile time, before the model ever sees them.

Installing Node.js

The ADK for TypeScript requires Node.js 20 or newer. If Node.js is not installed in your environment, the Node Version Manager (nvm) is the easiest way to install and manage versions:

  • nvm-sh / nvm
  • Node Version Manager - POSIX-compliant bash script to manage multiple active node.js versions
  • Table of Contents:
    • Intro
    • About
    • Installing and Updating
      • Install & Update Script
      • Additional Notes
      • Installing in Docker
      • Installing in Docker for CICD-Jobs
      • Troubleshooting on Linux
      • Troubleshooting on macOS
      • Ansible
      • Verify Installation
      • Important Notes
      • Git Install
      • Manual Install
      • Manual Upgrade
    • Usage
    • Long-term Support
    • Migrating Global Packages While Installing
    • Migrating Global Packages Between Installed Versions
    • Offline Install
    • Default Global Packages From File While Installing
    • io.js
    • System Version of Node
    • Listing Versions
    • Setting Custom Colors
      • Persisting custom colors
      • Suppressing colorized output
    • Restoring PATH
    • Set default node version
    • Use a mirror of node binaries
    • Pass Authorization header to mirror
    • .nvmrc
    • Deeper Shell Integration
      • Calling nvm use automatically in a directory with a .nvmrc file
        • bash
        • zsh
        • fish
    • Running Tests
    • Environment variables
    • Bash Completion
    • Usage Compatibility Issues
    • Installing nvm on Alpine Linux
      • Alpine Linux 3.13+
      • Alpine Linux 3.5 - 3.12
    • Uninstalling / Removal
      • Manual Uninstall
    • Docker For Development Environment
    • Problems
    • macOS Troubleshooting
    • …

View on GitHub

Install and activate a current Node.js release:

nvm install --lts
nvm use --lts

Validate the installation:

node --version   # v22.x

What is the Agent Development Kit?

The Agent Development Kit (ADK) is a flexible and modular framework for developing and deploying AI agents. While optimized for Gemini and the Google ecosystem, ADK is model-agnostic, deployment-agnostic, and built for compatibility with other frameworks. Google provides full documentation on the ADK here: Agent Development Kit (ADK).

Google provides the source to the complete TypeScript version of the ADK project: google/adk-js. Important links: Docs, Samples, & ADK Web.

Agent Development Kit (ADK) is a flexible and modular framework for building, deploying, and orchestrating AI agent workflows, from simple tasks to complex multi-agent systems. Define agent behavior, orchestration, and tool use directly in code, enabling robust debugging, versioning, and deployment anywhere.

The TypeScript version of ADK is built for the Node.js and browser ecosystems, with full type safety, Zod schema validation, and support for ESM, CommonJS, and web runtimes.

✨ Key Features

  • Code-First TypeScript: Define agent logic, tools, and orchestration with full type safety. Tool parameters support Zod v3 and v4 schemas with compile-time type inference.
  • Browser and Server: Ships ESM, CommonJS, and web bundles. Run agents in Node.js or directly in the browser.
  • Rich development tooling: The ADK CLI (@google/adk-devtools) provides interactive and web-based debugging, and one-command Cloud Run deployment.

The ADK is published to npm as @google/adk, with the development tooling in @google/adk-devtools. This tutorial uses ADK 1.4.0.

Gemini API Key

If not using Application Default Credentials (ADC), you will need a Gemini API key. You can get a Gemini key from Google AI Studio.

Checking the Developer Environment

Once Node.js is installed, clone the sample repo and run the init.sh script. It installs the npm dependencies and creates a starter .env file:

git clone https://github.com/xbill9/adk-hello-world-typescript
cd adk-hello-world-typescript
source init.sh

Output:

Created .env from .env.example. Add your credentials before running the agent.
Setup complete. Run: npm start

Edit .env and choose one authentication method:

  • Gemini Developer API: set GOOGLE_API_KEY
  • Vertex AI: set GOOGLE_GENAI_USE_VERTEXAI=TRUE, GOOGLE_CLOUD_PROJECT, and GOOGLE_CLOUD_LOCATION, then authenticate with ADC:
    gcloud auth login
gcloud auth application-default login

Note: Never commit .env - it is already listed in .gitignore.

Debugging API Permission Errors

If your Application Default Credentials expire or your Google Cloud authentication expires, re-authenticate with:

gcloud auth login
gcloud auth application-default login

Another common issue is missing environment variables. The agent loads .env automatically via dotenv, and the set_env.sh script is provided for shell commands that need the same values:

source set_env.sh

The TypeScript ADK Agent

The entire agent lives in a single file - src/agent.ts. It defines two local tools (weather and current time) and wires them into an LlmAgent running on Gemini 2.5 Flash. Tool parameters are declared with Zod schemas, so the ADK derives the function-calling declarations directly from the types:

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

const cityParameters = z.object({
  city: z.string().min(1).describe('The city to look up.'),
});

const weatherTool = new FunctionTool({
  name: 'get_weather',
  description: 'Retrieves the current weather report for a specified city.',
  parameters: cityParameters,
  execute: ({ city }) => getWeather(city),
});

export const rootAgent = new LlmAgent({
  name: 'weather_time_agent',
  model: 'gemini-2.5-flash',
  description: 'Answers questions about the time and weather in a city.',
  instruction:
    'You are a helpful assistant. Use the available tools to answer ' +
    'questions about time and weather. Clearly explain when a city is ' +
    'unsupported.',
  tools: [weatherTool, currentTimeTool],
});

The tools return a discriminated union - a success result with a report, or an error result with a message - which gives the model a consistent shape to reason about:

export type ToolResult =
  | { status: 'success'; report: string }
  | { status: 'error'; errorMessage: string };

Weather and local time are available for New York; other cities return a clear unsupported-city result.

Type-Checking and Unit Tests

Unlike earlier Go and Python versions of this sample, the TypeScript project ships with a unit test suite built on the Node.js native test runner. A single command type-checks the project and runs the tests:

npm run check

Example test output:

> adk-hello-world-typescript@1.0.0 build
> tsc --noEmit

> adk-hello-world-typescript@1.0.0 test
> tsx --test test/**/*.test.ts

▶ weather and time agent
  ✔ exports the ADK root agent (0.43ms)
  ✔ returns the configured New York weather (0.16ms)
  ✔ rejects unsupported cities (0.45ms)
  ✔ formats New York time deterministically (12.27ms)
  ✔ weather and time agent (14.06ms)

ℹ tests 4
ℹ pass 4
ℹ fail 0

Because the tools are plain exported functions, they can be tested deterministically without calling the model at all.

Running the ADK from the CLI

The agent can be debugged locally from the terminal. Use cli.sh or run the npm script directly:

npm start   # runs: adk run src/agent.ts

The ADK CLI can also be called directly:

npx adk run src/agent.ts

Sample interaction with the agent:

User -> what can you do?
Agent -> I can answer questions about the time and weather in a city using my tools. Currently I support New York - for other cities I will let you know that information is not available.

User -> what is the weather in New York?
Agent -> The weather in New York is sunny with a temperature of 25 degrees Celsius (77 degrees Fahrenheit).

Interacting with the ADK Web UI

The agent can be debugged from the web GUI running in the local development environment:

npm run web   # runs: adk web

If developing on a remote VM or container and needing the UI reachable from outside, bind the server to all interfaces:

npx adk web --host=0.0.0.0

The UI is the same development interface presented for Python, Java, and Go ADK agents - select agent from the dropdown and chat with full tool-calling tracing.

Expose the agent as a plain HTTP API without the UI:

npx adk api_server

Deploying to Cloud Run with the ADK CLI

For deployment options, check the official documentation: Cloud Run - Agent Development Kit (ADK).

The TypeScript ADK CLI has deployment built right in. The cloudrun.sh script loads .env and calls the deploy command:

npx adk deploy cloud_run \
  --project "$GOOGLE_CLOUD_PROJECT" \
  --region "$GOOGLE_CLOUD_LOCATION" \
  --service_name "$SERVICE_NAME" \
  --with_ui true \
  src/agent.ts

The --with_ui true flag bundles the development UI into the deployed Cloud Run service.

Check Google Cloud Console

Once deployed, validate your Cloud Run service from the Google Cloud Console, or fetch the service URL from the CLI:

gcloud run services describe hello-world-agent-service \
  --region us-central1 --format 'value(status.url)'

Summary

The TypeScript Agent Development Kit (ADK) enables fast agent development using standard TypeScript and Node.js features:

  • Clean Tooling: Define typed tools using Zod schemas.
  • Deterministic Testing: Fast unit testing with Node's native test runner (node:test).
  • Local Tracing: Interactive CLI and Web UI (adk web).
  • Direct Cloud Deployment: One-command Cloud Run deployment (adk deploy cloud_run).
Read on DEV Community ↗ ← Back to News

Comments

No comments yet. Start the discussion.