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

This tutorial builds a starter "Hello World" style agent using TypeScript and the native TypeScript version of the Agent Development Kit (ADK).

The full sample project is available on GitHub:

xbill9 (xbill) · GitHub

12032025/16785778. xbill9 has 209 repositories available. Follow their code on GitHub.

github.com

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 · GitHub

nvm - node version manager. nvm.sh has 4 repositories available. Follow their code on GitHub.

github.com

Install and activate a current Node.js release:

You can validate the installation with the version command:

**
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) - Agent Development Kit (ADK)Agent Development Kit (ADK)

Build powerful multi-agent systems with Agent Development Kit (ADK)

adk.dev

Google provides the source to the complete TypeScript version of the ADK project:

Google · GitHub

Google ❤️ Open Source. Google has 2888 repositories available. Follow their code on GitHub.

github.com

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:

accounts.google.com

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:

Output:

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:

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:

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:

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:

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:

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:

Example test output:

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:

Interacting with the ADK Web UI
The agent can be debugged from the web GUI running in the local development environment:

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

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:

Deploying to Cloud Run with the ADK CLI
For deployment options, check the official documentation:

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

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:

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).