google/adk-js レビュー: TypeScript でエージェントをコードとして書くための設計と制約

設定ファイルではなくコードに寄せるという選択

ADK の TypeScript 版が解こうとしているのは、エージェントの振る舞いが YAML や GUI の設定に散らばり、差分レビューも型検査もできない状態である。README は「Define agent behavior, orchestration, and tool use directly in code」と述べ、エージェントの定義そのものを TypeScript のモジュールとして書く方針を取る。対象は Node.js とブラウザの両方で動かしたい開発者で、前提として Node.js 20.19 以上が要求される。

コードに寄せる利点は、エージェントの分岐やツール呼び出しが通常のソースコードになるため、Git の差分、型検査、テストの対象にできる点にある。逆に、非エンジニアがプロンプトやフローを直接編集する運用には向かない。設定ファイルを介したノーコード運用を前提にしているチームにとっては、この設計自体が導入コストになる。

LlmAgent と Zod スキーマが担う型の境界

中心になるのは LlmAgent クラスである。README の例では name、description、model、instruction、tools を渡しており、model には 'gemini-flash-latest' のような文字列を指定する。tools には GOOGLE_SEARCH のような組み込みツールをそのまま配列で入れる。

型安全性の要はツール引数のスキーマで、README は「Tool parameters support Zod v3 and v4 schemas with compile-time type inference」と説明している。つまり関数をツールとして包むとき、引数の形を Zod で書き、その型が TypeScript 側に推論される。エージェントがモデルに渡す引数スキーマと、実装側が受け取る型が同じ定義から出るため、両者がずれる余地が減る。Zod v3 と v4 の両対応は、既存プロジェクトの依存バージョンを上げずに済ませたい場合に効く。

組み込みツール、MCP、A2A の役割分担

ツール周りは 3 層に分かれている。1 つ目は Google Search、Google Maps、Vertex AI Search、URL context といった組み込みツールで、README の例のように定数として渡すだけで使える。2 つ目は MCP サーバーへの接続と任意の関数のラップ、コード実行の追加で、外部のツール群を自分のエージェントに組み込む経路になる。3 つ目が A2A プロトコルによるリモートエージェントへの委譲である。

オーケストレーションは sequential、parallel、loop、routed の 4 種類が挙げられており、複数エージェントを合成してワークフローを作る。ここで注意したいのは、組み込みツールの多くが Google 側のサービスに紐づく点だ。Google のスタックに寄せるほど記述量は減るが、その分だけ他社モデルや他社検索基盤へ移すときの書き換え範囲は広くなる。

インストールと起動: 実際のコマンドと環境変数

導入は 2 つのパッケージに分かれる。コア SDK が @google/adk、CLI と dev UI を含む開発ツールが @google/adk-devtools で、後者は開発依存として入れる。

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

認証はエージェントの隣に .env を置き、GOOGLE_GENAI_API_KEY を設定する。Vertex AI を使う場合は API キーの代わりに GOOGLE_GENAI_USE_VERTEXAI=1、GOOGLE_CLOUD_PROJECT、GOOGLE_CLOUD_LOCATION を設定し、gcloud auth application-default login で認証する。

実行はエージェントのプロジェクトディレクトリから行う。対話 CLI は npx @google/adk-devtools run agent.ts、Web UI は npx @google/adk-devtools web である。スキャフォールドは adk create、デプロイは adk deploy cloud_run が用意されている。README が明示的に警告しているのは npx の解決で、パッケージ名を省略して npx adk と書くと、無関係な adk パッケージが公開レジストリから黙って取得され実行される。常に @google/adk-devtools まで書く必要がある。

マルチエージェント構成で先に決めておくこと

sequential、parallel、loop、routed という 4 つの合成方法は、いずれもコード上の構成として表現される。並列に走らせるエージェントが同じ外部ツールや同じレート制限を共有する場合、失敗の切り分けは構成側で設計するしかない。README にはリトライやタイムアウトの既定値についての記述がないため、これらの挙動は採用前に自分で確認する項目になる。

A2A でリモートエージェントに委譲する構成は、境界がプロセス外に出る。ローカルで完結するエージェントと違い、相手側のバージョンや可用性が実行時の挙動に直接効く。単一プロセスで完結する構成から始め、委譲が本当に必要な箇所だけを切り出すほうが、デバッグの手数は少なくなる。

ブラウザ実行と dev UI が前提にするもの

配布物は ESM、CommonJS、web バンドルの 3 種類で、Node.js でもブラウザでも動かせると README は説明している。ブラウザでエージェントを動かす場合、API キーをクライアント側に置けないという制約が別途つきまとう。この点について README は具体的な方式に触れていないため、ブラウザ実行を検討するならキーの扱いを自分で設計する必要がある。

adk web はテストとデバッグ用の開発 UI を起動するコマンドで、README には関数呼び出しの様子を写したスクリーンショットが掲載されている。CLI と dev UI が @google/adk-devtools 側に分離されているため、本番の依存に開発ツールを混ぜずに済む。この分離は、デプロイ対象を小さく保ちたい場合に素直な構成である。

向かない場面と、代わりに検討する構成

ADK が向かないのは、エージェントの振る舞いを非エンジニアが設定画面から編集する運用を既に回している場合である。この SDK はコードが唯一の定義源なので、その運用と正面から衝突する。

別の系統として、LangChain.js や LlamaIndex.TS のような汎用のオーケストレーションライブラリがある。違いは既定値の置き方にある。ADK は LlmAgent と GOOGLE_SEARCH のように Google のモデルとツールを最初から結びつけ、adk run や adk deploy cloud_run まで同じ配布物で提供する。汎用ライブラリはモデルやツールを自分で組み合わせる代わりに、対象プロバイダを選ばない。Google のスタックに寄せる前提が固まっているなら前者、複数プロバイダを同じコードで扱いたいなら後者、という切り分けになる。

Apache-2.0 とバージョンの追い方

ライセンスは Apache-2.0 で、リポジトリの LICENSE に全文がある。特許条項を含む寛容なライセンスだが、実際の適合判断は利用形態によって変わるため、ここでは法的助言はしない。

バージョンは main、integrations、devtools の 3 系列が同じ日に 2.0.0 としてリリースされており、コアと開発ツールが別々にバージョン付けされる構成だとわかる。@google/adk と @google/adk-devtools のバージョンを揃えて更新する運用が前提になり、片方だけを上げると CLI と SDK の噛み合わせが崩れる可能性がある。2026 年 8 月の 2.0.0 以降も main への push が続いているため、追従するならリリースノートを確認してから上げるほうが安全である。

編集部の結論

Node.js 20.19 以上で Gemini 系モデルを使い、エージェントの分岐やツール引数をコードと型で管理したいチームに向く。設定ファイル主体のオーケストレーションを既に持つ場合や、Google 以外のモデルを主軸にする場合は、LlmAgent のモデル指定と組み込みツールの依存範囲を先に確認したい。導入前に検証すべきは、npx @google/adk-devtools run が自分のエージェント構成で通ること、GOOGLE_GENAI_USE_VERTEXAI 経路の認証が通ること、そして公開レジストリの adk ではなく @google/adk-devtools を解決できていることの 3 点である。

公式情報源

1. google/adk-js on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases