Tracking: @google/adk cannot be bundled for the browser (5 build-level defects)

[AmaadMartin]

Summary

@google/adk's README states the package is "built for the Node.js and browser ecosystems" and "Ships ESM, CommonJS, and web bundles. Run agents in Node.js or directly in the browser."

The Node half is true. The browser half does not currently work: a plain browser bundle of @google/adk fails with 625 errors, and one of them is a syntax error in published code that no bundler configuration can work around.

All five defects are in packaging and the build script. None are in the ADK API.

Evidence that the API itself is fine

I built a non-trivial browser app on ADK — a Chrome extension doing natural-language tab search with LlmAgent, ParallelAgent, FunctionTool, Runner, InMemorySessionService, outputSchema/outputKey, beforeModelCallback, RunConfig.maxLlmCalls, and a custom BaseLlm over Chrome's built-in Prompt API.

The identical pipeline, agents, tools and model adapter run unmodified against a stock import ... from '@google/adk' on Node — 22/22 tests pass, no aliases, no shims, no stubs.

Getting that same code into a browser bundle required 226 lines of pure workaround (four shims, a stub for an unparseable ADK file, and a dual-resolution import layer) plus 12 lines of bundler config.

Reproduce the baseline

echo "import {LlmAgent} from '@google/adk';" > t.ts
npx esbuild t.ts --bundle --platform=browser --target=chrome138
# 625 errors

Even bypassing the exports map and pointing a bundler directly at ADK's own documented web entry still fails:

npx esbuild node_modules/@google/adk/dist/web/index_web.js --bundle --platform=browser
# 316 errors, including:
#   ✘ [ERROR] Unexpected "super"
#       node_modules/@google/adk/dist/web/models/apigee_llm.js:141:25

The five defects

Each is filed separately with root cause and a proposed patch. Verified against main (8944bfb, core v1.5.0).

#	Defect	Root cause	Size of fix
1	exports has no browser condition and no subpaths, so bundlers resolve the Node build	core/package.json	a few lines
2	Node createRequire banner is injected into the web build (187 files import it, 0 call it)	core/build.js:72	one condition
3	The node:async_hooks shim exists but is gated behind --bundle, which the published build does not pass; winston has no shim at all	core/build.js:53, core/src/utils/logger.ts:6	one condition + a logger shim
4	dist/web/models/apigee_llm.js does not parse. Browser target chrome58/safari11 downlevels async generators, emitting super inside a closure	core/build.js:11	one line
5	index_web.ts re-exports the full barrel, pulling skills/loader and GCS artifacts (node:fs, node:path) into the web build	core/src/index_web.ts	a web-specific barrel

#4 is the hard blocker. It is invalid syntax in a shipped file, on the import path LlmAgent → models/registry → apigee_llm, which no browser consumer can avoid. No bundler flag can parse it.

Suggested order

1. Simple Agent is Failing #4 — hard blocker, one-line fix, nothing else matters while a shipped file fails to parse
2. Add esbuild to bundle the source code #2 — one condition, removes ~300 of the 625 errors
3. fix: add package-lock.json #1 — makes import from '@google/adk' resolve correctly in the first place
4. Fix CI build #3 and isFinalResponse doesn't work properly with empty response #5 — remaining Node leakage

Please add a regression test

None of these would have survived a CI job that does:

npx esbuild dist/web/index_web.js --bundle --platform=browser --outfile=/dev/null

core/test has no browser-bundle test today. One would have caught all five, and would stop them recurring.

Why this matters

Browser support is a genuine differentiator for ADK TypeScript over ADK Python — running an agent against Chrome's built-in on-device model is something the Python SDK structurally cannot do. Right now that story is one unparseable file away from working.

I have working patches for all five and am happy to send PRs.

[AmaadMartin]

Filed

#	Issue	Blocking?
1	#610 — exports has no browser condition and no subpaths	yes
2	#609 — Node createRequire banner injected into the web build	yes (~300 errors)
3	#611 — async_hooks shim gated behind --bundle; winston unshimmed	yes
4	#608 — apigee_llm.js does not parse (async generator downlevel)	hard blocker
5	#612 — index_web.ts re-exports the full barrel	no (workaroundable)

Suggested order: #608 → #609 → #610 → #611 → #612.

#608 first because nothing else is observable while a shipped file fails to parse, and it is a one-line change. #612 last because it is the only one consumers can route around today.

Two of these are one-condition fixes in core/build.js that look like oversights rather than design decisions:

• Node createRequire banner is injected into the web build (187 files import it, none use it) #609: if (format === 'esm') should be if (format === 'esm' && platform === 'node')
• Web build leaks Node-only deps: the async_hooks shim is gated behind --bundle (never applied), and winston has no shim #611: if (platform === 'browser' && bundle) — the && bundle means the existing async_hooks_shim.ts never applies to published output, since prepublishOnly runs npm run build without --bundle

Each issue has a reproduction, the root cause with file and line, and a proposed patch.