# Google ADK for TypeScript: a code-first agent toolkit on npm

> ADK for TypeScript builds agents as ordinary TypeScript modules, with Zod-validated tools and a CLI for running and debugging them. The package is published as @google/adk, and the README warns that the devtools binary must be named explicitly.

**google/adk-js** — An open-source, code-first Typescript toolkit for building, evaluating, and deploying sophisticated AI agents with flexibility and control.

- Repository: https://github.com/google/adk-js
- Website: https://adk.dev
- Stars: 1,425 · Forks: 216
- Language: TypeScript
- License: Apache-2.0
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/google-adk-js

## What ADK for TypeScript is for

ADK is a toolkit for writing AI agents as code rather than configuring them through a hosted console. The TypeScript edition targets the Node.js and browser ecosystems, and the README describes it as code-first: agent behavior, orchestration and tool use are defined in source files, which is what makes the usual software practices (diffing, code review, unit tests) apply to an agent the same way they apply to any other module.

The intended reader is a TypeScript developer who already knows what an LLM call looks like and wants the surrounding structure: which agent runs next, which tools it may call, how a sub-agent gets delegated to. The repository is organized as npm workspaces named core, dev and integrations, so the framework, the CLI and the third-party connectors are versioned separately. If you only want a thin wrapper around a chat completion endpoint, this is more machinery than the job needs.

## How agents, tools and orchestration fit together

An agent is an object. The README's example constructs an LlmAgent with a name, a description, a model string, an instruction and a tools array. Orchestration is composition: the README lists sequential, parallel, loop and routed workflows, and remote delegation through the A2A protocol. That means the control flow lives in your TypeScript, not in a server-side graph you edit through a UI.

Tools are where the type safety claim becomes concrete. Tool parameters accept Zod v3 and v4 schemas, and the README states that this gives compile-time type inference, so a tool's argument shape is checked when you build, not when the model calls it. Beyond function wrapping, the built-in tools cover Google Search, Google Maps, Vertex AI Search and URL context, and MCP servers can be connected for anything else. The trade-off is that the built-ins are Google-centric: if your retrieval lives in a non-Google vector store, you are writing a tool wrapper or wiring an MCP server.

The devtools package is a separate concern from the runtime library. It provides the interactive dev UI, scaffolding through adk create, local execution through adk run and adk web, and deployment through adk deploy cloud_run. Keeping the CLI in a dev dependency is a reasonable split: production code imports @google/adk and never touches the tooling.

## Installing @google/adk and running a first agent

ADK for TypeScript requires Node.js 20.19 or newer, which the README states as a prerequisite. Install the runtime library and the devtools package, the latter as a dev dependency:

```bash
npm install @google/adk
npm install -D @google/adk-devtools
```

Authentication comes next. The README's path is an API key from Google AI Studio written into a .env file beside your agent:

```bash
echo "GOOGLE_GENAI_API_KEY=your-api-key-here" > .env
```

If you are on Vertex AI instead, the README says to set GOOGLE_GENAI_USE_VERTEXAI=1 along with GOOGLE_CLOUD_PROJECT and GOOGLE_CLOUD_LOCATION in place of the API key, and to authenticate with gcloud auth application-default login.

Now define the agent. The README's example exports a rootAgent symbol, which is the name the tooling looks for:

```typescript
import {LlmAgent, GOOGLE_SEARCH} from '@google/adk';

export const rootAgent = new LlmAgent({
  name: 'search_assistant',
  description: 'An assistant that can search the web.',
  model: 'gemini-flash-latest',
  instruction:
    'You are a helpful assistant. Answer user questions using Google Search when needed.',
  tools: [GOOGLE_SEARCH],
});
```

Run it from the agent project directory. The README gives two entry points, an interactive CLI and a browser UI:

```bash
npx @google/adk-devtools run agent.ts
npx @google/adk-devtools web
```

The README attaches an explicit warning to these commands: always name the package. If @google/adk-devtools is not installed, a bare npx adk silently downloads and runs an unrelated adk package from the public registry. That is a real footgun, not a documentation nicety, and it is the kind of thing that produces a confusing failure on a fresh machine.

## Where ADK for TypeScript is the wrong choice

The framework assumes you are building in TypeScript. If your team is standardized on Python, Go or Java, the README's own links point at sibling projects rather than a polyglot runtime, so choosing this edition is a language decision as much as a framework decision.

A second limitation is backend coupling. The two documented authentication paths are a Google AI Studio API key and Vertex AI. Nothing in the README describes pointing an LlmAgent at an OpenAI-compatible endpoint or a locally hosted model, so anyone who needs that is outside the documented path and should treat it as unproven.

The devtools dependency is also worth reading carefully. The CLI and dev UI arrive through @google/adk-devtools, and the README's warning about the unrelated adk package means a misconfigured environment can execute code you did not intend. Pin the package, install it explicitly, and do not rely on npx resolving the right thing.

Finally, the README does not document a rollback path for adk deploy cloud_run, nor does it discuss what happens to in-flight agent state during a redeploy. If you need that level of operational detail, the README is silent and you will have to read the deployment docs at adk.dev.

## ADK for TypeScript against LangGraph.js and the Vercel AI SDK

LangGraph.js also models agents as graphs, but it makes the graph an explicit, inspectable structure with its own state and checkpointing story. ADK's orchestration is closer to plain composition: you write sequential, parallel, loop or routed workflows as TypeScript control flow, and the framework supplies the agent abstraction and the tool plumbing. The practical difference shows up when you want to pause a run, persist its state and resume it later. LangGraph.js treats that as a first-class concern; ADK's README does not describe a checkpointing mechanism.

The Vercel AI SDK sits at a lower level. It is primarily a model-calling layer with streaming and UI helpers, and it leaves agent structure to you. ADK ships the agent abstraction, the built-in Google tools and a dev UI in the same box. If you want a thin call layer and intend to write your own loop, the AI SDK is the smaller dependency. If you want the loop, the tools and a debugging UI already assembled, ADK is the shorter path, at the cost of being tied to Google's model endpoints.

## Maintenance, licensing and the cost of upgrading

The repository is not archived, and the last push was on 2026-09-10, which is recent enough that the codebase is being worked on. The release history shows a coordinated v2.0.0 across three packages on 2026-08-21: main-v2.0.0, integrations-v2.0.0 and devtools-v2.0.0. Because the project is split into npm workspaces, those three version numbers can move independently, and a major bump in any of them is a signal to read the changelog before upgrading.

Upgrade cost is dominated by the Zod dependency. The README states that tool parameters support Zod v3 and v4 schemas, which means the project carries compatibility for both major versions. If you have pinned Zod v3 across a large codebase, this is convenient; if you migrate to v4, you should confirm your tool schemas still infer the types you expect, since schema inference is the feature being relied on.

The license is Apache-2.0, and the repository carries both a LICENSE file and a LICENSE_SUMMARY.md. Apache-2.0 permits commercial use and modification and includes a patent grant, with the usual obligations around notices and attribution. That is a general description of the license, not legal advice; if you are redistributing the code, read the LICENSE file and your own counsel's guidance.

## Conclusion

Adopt ADK for TypeScript if your agents are TypeScript modules you intend to version and test, and if you are comfortable with Gemini or Vertex AI as the model backend, since the README's authentication steps cover only those two. Skip it if you need a language-agnostic runtime or a hosted control plane, because this repository ships libraries and a local CLI, not a service. Verify three things before committing: that your Node.js is 20.19 or newer, that your agent file exports a rootAgent symbol, and that you always invoke the devtools package by its full name, because a bare adk on npx resolves to a different package in the public registry.

## FAQ

### What does ADK stand for?

The README expands it as Agent Development Kit, and the package is published on npm as @google/adk.

### What is the purpose of Google ADK?

It is a code-first toolkit for building, evaluating and deploying AI agents, with multi-agent orchestration and built-in tools for Google Search, Google Maps, Vertex AI Search and URL context.

### What is the difference between an SDK and an ADK?

The README does not draw that distinction. It describes ADK as a framework for building and orchestrating agent workflows, and the repository ships it as an npm package alongside a separate devtools package.

## Sources

- [google/adk-js on GitHub](https://github.com/google/adk-js)
- [License: Apache-2.0](https://github.com/google/adk-js/blob/main/LICENSE)
- [Project website](https://adk.dev)
- [README](https://github.com/google/adk-js/blob/main/README.md)
- [Releases](https://github.com/google/adk-js/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/google-adk-js