Tracking: @google/adk cannot be bundled for the browser (5 build-level defects)
- Dominant language
- TypeScript
- Stars
- 1.4k
- Forks
- 205
- Avg merge
- 3d 16h
- Merged PRs (30d)
- 92
Description
## 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
```bash
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:
```bash
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. **#4** — hard blocker, one-line fix, nothing else matters while a shipped file fails to parse
2. **#2** — one condition, removes ~300 of the 625 errors
3. **#1** — makes `import from '@google/adk'` resolve correctly in the first place
4. **#3** and **#5** — remaining Node leakage
## Please add a regression test
None of these would have survived a CI job that does:
```bash
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.
Contributor guide
Assessment
This issue has not been assessed yet.