google/adk-js: a code-first TypeScript agent toolkit with a CLI trap worth knowing
An open-source, code-first Typescript toolkit for building, evaluating, and deploying sophisticated AI agents with flexibility and control.
At a glance
- What is it?
- ADK for TypeScript defines agents as exported TypeScript objects, validates tool parameters with Zod, and ships a dev CLI. The README's own warning about bare npx adk is the first thing to internalise.
- Who is it for?
- Adopt ADK for TypeScript if your team already writes Node.js services and wants agent definitions to live in version control as typed modules rather than in a hosted builder or a YAML file. Skip it if you need a Python-first stack, a non-Google model provider as the primary path, or a browser bundle you can audit without pulling the devtools package.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository received new commits within the last day.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem ADK for TypeScript solves: agent definitions as typed modules
Most agent frameworks ask you to describe behaviour in a config file, a visual builder, or a chain of prompt strings. ADK for TypeScript takes the opposite position. The README states that you define agent behaviour, orchestration and tool use directly in code, which the project frames as enabling debugging, versioning and deployment anywhere. The unit of work is a TypeScript module that exports an agent object. In the README's own example, agent.ts exports a rootAgent built from new LlmAgent({...}) with name, description, model, instruction and tools fields. That object is the agent. There is no separate registration step visible in the material, and no server to run before the agent exists. The audience is Node.js and browser developers who want an agent to behave like the rest of their codebase: importable, type-checked, diffable, and testable with the tooling they already use. If your team's agents currently live in a console UI that nobody can review in a pull request, this is the shape of project that addresses that.
How the mechanism works: a typed agent object, Zod schemas, and a CLI that loads the file
The architecture visible in the README is deliberately thin. You write a module. The devtools CLI loads that module and drives it. Running npx @google/adk-devtools run agent.ts starts an interactive CLI session against the exported agent, and npx @google/adk-devtools web launches a development UI for testing and debugging. The agent's model field is a string such as gemini-flash-latest, and the tools field is an array. GOOGLE_SEARCH is imported from @google/adk and dropped into that array, which is the whole of the tool wiring shown. Tool parameters are where the type safety claim becomes concrete: the README says tool parameters support Zod v3 and v4 schemas with compile-time type inference. That means a function you wrap as a tool gets its argument types derived from a schema you write, rather than from a hand-maintained interface that can drift. Orchestration is compositional. The README lists sequential, parallel, loop and routed workflows, plus delegation to remote agents over the A2A protocol. It does not show the constructor signatures for those composites, so treat the exact API as something to confirm in the docs rather than infer from the feature list. Packaging is stated plainly: ESM, CommonJS and web bundles, with Node.js 20.19 or newer as the prerequisite. The browser target is the unusual part. Most agent SDKs assume a server process holds the API key; ADK for TypeScript explicitly supports running agents in the browser, which is a design choice with security consequences you have to reason about yourself, because the README does not discuss key handling in that context.
Getting it running: two installs, one env file, two commands
The install is split in two. npm install @google/adk brings the core SDK, and npm install -D @google/adk-devtools brings the CLI and dev UI as a dev dependency. Yarn equivalents are given. Node.js 20.19 or newer is a stated prerequisite, so check that before anything else. Authentication has two documented paths. The first is an API key from Google AI Studio written into a .env file next to your agent, using the key GOOGLE_GENAI_API_KEY. The README gives the exact shell line for it. The second is Vertex AI, where you set GOOGLE_GENAI_USE_VERTEXAI=1 along with GOOGLE_CLOUD_PROJECT and GOOGLE_CLOUD_LOCATION in place of the API key, and authenticate with gcloud auth application-default login. Then you run the agent from your agent project directory with npx @google/adk-devtools run agent.ts or npx @google/adk-devtools web. The README adds a warning that deserves more prominence than it gets: always name the package, because if @google/adk-devtools is not installed, a bare npx adk silently downloads and runs an unrelated package from the public registry. That is a supply-chain footgun sitting in the quick start of a Google-published SDK, and it is the single most actionable line in the document. It also hints at the intended workflow: devtools is a dev dependency you install locally, not something you invoke by short name.
Where the documented material runs out
The README is a landing page, not a reference. Several things a reader would need before committing are simply absent. There is no example of a custom tool definition, so the Zod v3 and v4 claim is asserted without a code sample showing how a schema attaches to a function. There is no constructor signature for the sequential, parallel, loop or routed composites, and no example of an A2A delegation. The adk create scaffolding command is named in the feature list but shown nowhere, so its output layout is unknown from this material. Deployment is mentioned only as adk deploy cloud_run, with no flags, no service account guidance and no statement of what gets created in your Google Cloud project. The built-in tools beyond GOOGLE_SEARCH (Google Maps, Vertex AI Search, URL context, MCP servers, code execution) are listed but not demonstrated. None of this is a defect in the SDK; it is a limit of what can be verified here. The honest position is that the quick start is fully reproducible from the README and everything past it requires the linked documentation at adk.dev. Anyone evaluating this for a real workload should budget time for that reading rather than assuming the feature list maps to the API surface one-to-one.
The browser target is the sharpest trade-off
Selling ESM, CommonJS and web bundles in one package is a real convenience for teams that share agent logic between a Node backend and a front end. It also creates a question the README does not answer: where does the credential live when the agent runs in the browser? The two documented auth paths are an API key in a .env file and Vertex AI with application default credentials. Neither is obviously suited to a client-side bundle, since a .env file is a build-time artefact and application default credentials are a machine-level concept. A browser-hosted agent that calls a model provider directly would expose whatever credential it uses to anyone who opens devtools. The material does not describe a proxy pattern, a token exchange, or any restriction on which tools work client-side. That does not mean the browser support is unusable; it means the security model is undocumented in the source available here, and you should not infer one. If your plan is a browser agent, resolve that question first, because it may determine whether you need a thin backend in front of the SDK regardless of what the bundle supports.
How it differs from LangChain.js and the Python ADK
The closest comparison in the TypeScript ecosystem is LangChain.js, which is built around composable abstractions: chains, retrievers, document loaders and a large integration surface. ADK for TypeScript is narrower and more prescriptive. Its primitives are agents and workflow composites, and the README's framing is code-first control rather than breadth of integrations. The practical difference shows up in what you write. A LangChain.js pipeline tends to be assembled from library-provided pieces, while an ADK agent is an object you construct with a name, an instruction and a tool array, and the orchestration you need is expressed as sequential, parallel, loop or routed composition. If you want a large catalogue of pre-built connectors, LangChain.js is the broader tool. If you want the agent's structure to be visible in one typed file, ADK's approach is the more direct one. The second comparison is with ADK for Python, which shares the project name, the adk.dev documentation site and the sample repository. Choosing the TypeScript build is a runtime decision, not a feature decision, and the README does not claim parity between the two. If your team is Python-first, the Python ADK is the natural sibling to evaluate rather than this package.
Maintenance, versioning and the Apache-2.0 boundary
Three packages version independently: main, integrations and devtools each carry their own v2.0.0 tag, released within seconds of one another in August 2026. Independent versioning is normal for a monorepo-style split, but it means the core SDK and the CLI can move separately, and a devtools release is not automatically a signal that @google/adk changed. The repository is not archived and the last push recorded is September 2026. The licence is Apache-2.0, which permits commercial use, modification and redistribution provided you preserve the licence and notices and comply with the patent and attribution terms. That is a permissive licence, and it is the same one used by many Google open source projects. What Apache-2.0 does not do is indemnify you against model provider terms, API pricing changes, or the behaviour of the third-party packages npx might pull in if you follow the bare adk shortcut. The maintenance cost that matters here is not the licence, it is the model identifier. The README's example uses gemini-flash-latest, a moving alias. Pinning to an alias means your agent's behaviour can change without a dependency bump, and pinning to a dated model means you own the upgrade. Neither is wrong, but the choice should be deliberate rather than copied from the quick start.
Who should adopt ADK for TypeScript, and what to check first
Adopt it if you are building on Node.js 20.19 or newer, you are comfortable with the Google AI Studio or Vertex AI auth paths, and you want agent logic to live in source control as typed modules with Zod-validated tool inputs. The multi-agent composites and the A2A delegation path are the features that justify the framework over a hand-rolled loop calling a model API, provided you confirm their APIs in the docs. Do not adopt it if your stack is Python-first, if you need a non-Google provider as the primary model path (nothing in the material describes one), or if you intend to ship a browser-hosted agent before you have worked out where the credential lives. The first thing to verify is the npx behaviour: install @google/adk-devtools locally and invoke it as npx @google/adk-devtools, never as bare npx adk, because the README states the bare form will fetch an unrelated package. The second is the deployment path. adk deploy cloud_run is a single line in the feature list, and what it creates in your Google Cloud project should be understood before it runs against a real project rather than a sandbox.
Editorial conclusion
Adopt ADK for TypeScript if your team already writes Node.js services and wants agent definitions to live in version control as typed modules rather than in a hosted builder or a YAML file. Skip it if you need a Python-first stack, a non-Google model provider as the primary path, or a browser bundle you can audit without pulling the devtools package. Before writing production code, verify three things against the current docs: whether your chosen model identifier is still valid, how GOOGLE_GENAI_USE_VERTEXAI interacts with your gcloud credentials, and what adk deploy cloud_run actually provisions in your project.
Community notes