0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@kai_kou(甲斐 甲)

Google ADK TypeScript入門 — コードファーストでAIエージェントを構築する

0
Last updated at Posted at 2026-04-06

はじめに

GoogleのAgent Development Kit（ADK）がTypeScript/JavaScript対応となりました。@google/adk パッケージにより、TypeScript開発者がコードファーストのアプローチでAIエージェントや複数エージェントシステムを構築できるようになっています。

この記事では、ADK for TypeScriptの概要・インストール・基本実装・マルチエージェントシステムの構築方法を、公式ドキュメントと公開情報をもとに解説します。あわせてADK Go 1.0の主要アップデートも紹介します。

この記事で学べること

  • Google ADK TypeScriptの概要とPython版との違い
  • インストールと開発環境の構築
  • LlmAgentの実装とGeminiモデルの利用方法
  • ToolsとFunctionToolの定義
  • SequentialAgentを使ったマルチエージェントワークフロー
  • Google Cloud Runへのデプロイ方法

対象読者

  • TypeScript/Node.jsでAIエージェントを開発したいエンジニア
  • Google ADK（Python版）を知っているがTypeScript版に移行したい方
  • マルチエージェントシステムの実装方法を学びたい方

前提環境

  • Node.js 24.13.0以上（npm 11.8.0以上）
  • TypeScript 5.x
  • Google AI StudioのAPIキー（Geminiモデル利用）

TL;DR

  • npm install @google/adk でTypeScriptからAIエージェントを構築できる
  • LlmAgent + FunctionTool で基本エージェント、SequentialAgent でワークフロー構築
  • Gemini 3 Pro/Flash対応、Cloud Runへのデプロイも対応
  • ADK Go 1.0は同時にOpenTelemetryトレーシングとHITLセキュリティを追加

Google ADK TypeScriptとは

Agent Development Kit（ADK）は、Googleがオープンソースで提供するAIエージェント開発フレームワークです。2025年にPython版が公開され、2026年にTypeScript/JavaScript対応の @google/adk パッケージが公式リリースされました。

特徴

機能 内容
コードファーストアプローチ エージェントのロジック・ツール・オーケストレーションをTypeScriptで直接定義
型安全 TypeScriptの強い型付けで、エージェント間のデータ契約を明確に管理
デプロイ非依存 ローカル、Dockerコンテナ、Google Cloud Runなどに対応
モデル非依存 Gemini 3 Pro/Flash、その他サードパーティモデルも対応
MCP統合 MCP Toolbox for Databasesとのネイティブ統合
A2Aプロトコル Agent2Agentプロトコルでリモートエージェントとの通信が可能

Python版との比較

観点 Python版 TypeScript版
パッケージ google-adk @google/adk
実行環境 Python 3.9+ Node.js 24.13.0+
型システム 型ヒント（任意） TypeScript（強制型付け）
エコシステム 科学系・ML系が豊富 Web/クラウド系が豊富
デプロイ Cloud Run, Vertex AIなど Cloud Run, Serverlessなど

インストールと環境構築

1. プロジェクトの初期化

mkdir my-adk-agent
cd my-adk-agent

# npm初期化（ESモジュール対応）
npm init --yes
npm pkg set type="module"
npm pkg set main="agent.ts"

# ADKライブラリのインストール
npm install @google/adk zod

# 開発用ツールのインストール
npm install -D @google/adk-devtools typescript

2. TypeScript設定

tsconfig.json を以下の内容で作成します：

{
  "compilerOptions": {
    "target": "es2020",
    "module": "nodenext",
    "moduleResolution": "nodenext",
    "esModuleInterop": true,
    "strict": true,
    "outDir": "./dist"
  },
  "include": ["*.ts"]
}

3. APIキーの設定

Google AI Studio から取得したAPIキーを環境変数に設定します：

export GEMINI_API_KEY=<あなたのAPIキー>

または .env ファイルを使用する場合（dotenv利用時）：

GEMINI_API_KEY=your_api_key_here

基本的なLlmAgentの実装

シンプルなエージェントの作成

agent.ts を以下の内容で作成します：

import { LlmAgent, FunctionTool } from '@google/adk';
import { z } from 'zod';

// ツールの定義（FunctionToolオブジェクト形式）
const getCurrentTime = new FunctionTool({
  name: 'get_current_time',
  description: '現在の日時（JST）を返します',
  parameters: z.object({}),
  execute: () => {
    return { time: new Date().toLocaleString('ja-JP', { timeZone: 'Asia/Tokyo' }) };
  },
});

const getWeather = new FunctionTool({
  name: 'get_weather',
  description: '指定した都市の天気情報を返します',
  parameters: z.object({
    city: z.string().describe('天気を調べる都市名'),
  }),
  execute: ({ city }) => {
    // 実際の実装ではWeather APIを呼び出す
    return { city, weather: '晴れ', temperature: 25 };
  },
});

// エージェントの定義
export const rootAgent = new LlmAgent({
  name: 'assistant',
  model: 'gemini-2.5-flash',
  description: '日本語で質問に答えるアシスタント',
  instruction: `
    あなたは丁寧な日本語アシスタントです。
    ユーザーの質問に対して、必要に応じてツールを使って回答してください。
  `,
  tools: [getCurrentTime, getWeather],
});

エージェントの起動

# インタラクティブCLIで起動
npx adk run agent.ts

# Webインターフェースで起動（http://localhost:8000）
npx adk web agent.ts

adk web コマンドでブラウザベースのチャットUIが立ち上がります。エージェントとのやりとりをリアルタイムで確認できるため、開発中のデバッグに便利です。

FunctionToolの詳細

Zodスキーマによるパラメータ定義

ADK TypeScriptでは、ツールのパラメータをZodスキーマで定義します。Zodの型定義がそのままGeminiへの引数スキーマとして機能し、TypeScriptの型安全も保たれます：

import { FunctionTool } from '@google/adk';
import { z } from 'zod';

const searchTool = new FunctionTool({
  name: 'search_documents',
  description: 'ドキュメントを全文検索します',
  parameters: z.object({
    query: z.string().describe('検索クエリ文字列'),
    maxResults: z.number().optional().describe('取得する最大件数（デフォルト: 5）'),
    language: z.string().optional().describe('検索言語コード（例: ja, en）'),
  }),
  execute: async ({ query, maxResults = 5, language = 'ja' }) => {
    // 実際の検索ロジック
    return { results: `"${query}"の検索結果（最大${maxResults}件、言語: ${language}）` };
  },
});

マルチエージェントシステム

ADK TypeScriptの強みは、複数のエージェントをコードで組み合わせられる点です。

SequentialAgent — 順次実行

SequentialAgent はサブエージェントを順番に実行します。前のエージェントの出力が次のエージェントへ渡されます。

import { LlmAgent, SequentialAgent } from '@google/adk';

// コードを書くエージェント
const codeWriterAgent = new LlmAgent({
  name: 'code_writer',
  model: 'gemini-2.5-flash',
  description: '仕様書からコードを生成するエージェント',
  instruction: `
    提供された仕様をもとにTypeScriptコードを生成してください。
    コードのみを出力し、説明は不要です。
  `,
});

// コードをレビューするエージェント
const codeReviewerAgent = new LlmAgent({
  name: 'code_reviewer',
  model: 'gemini-2.5-pro',
  description: 'コードをレビューしてフィードバックを提供するエージェント',
  instruction: `
    提供されたコードをレビューし、以下を確認してください:
    - バグや論理的な誤り
    - TypeScriptのベストプラクティス違反
    - セキュリティ上の懸念点
    問題点と改善提案をリストアップしてください。
  `,
});

// コードを修正するエージェント
const codeRefactorAgent = new LlmAgent({
  name: 'code_refactor',
  model: 'gemini-2.5-flash',
  description: 'レビューフィードバックをもとにコードをリファクタリングするエージェント',
  instruction: `
    提供されたコードとレビューフィードバックをもとに、
    問題点を修正した最終版のコードを生成してください。
  `,
});

// パイプラインエージェント（順次実行）
export const codePipelineAgent = new SequentialAgent({
  name: 'code_pipeline',
  description: 'コード生成→レビュー→修正のパイプライン',
  subAgents: [codeWriterAgent, codeReviewerAgent, codeRefactorAgent],
});

コーディネータパターン — 並列・動的実行

LlmAgent に subAgents を設定することで、モデルが状況に応じて適切なサブエージェントを選択・実行する「コーディネータ」を構築できます：

import { LlmAgent } from '@google/adk';

// 専門エージェントを定義
const translatorAgent = new LlmAgent({
  name: 'translator',
  model: 'gemini-2.5-flash',
  description: '日本語←→英語の翻訳を担当するエージェント',
  instruction: '与えられたテキストを指定された言語に翻訳してください。',
});

const summarizerAgent = new LlmAgent({
  name: 'summarizer',
  model: 'gemini-2.5-flash',
  description: '長文テキストを要約するエージェント',
  instruction: 'テキストを3〜5行に要約してください。重要なポイントを網羅すること。',
});

const analyzerAgent = new LlmAgent({
  name: 'analyzer',
  model: 'gemini-2.5-pro',
  description: 'データや文書を詳細に分析するエージェント',
  instruction: '提供されたデータ・文書を多角的に分析し、洞察と結論を提供してください。',
});

// コーディネータ（動的にサブエージェントを選択）
export const coordinatorAgent = new LlmAgent({
  name: 'coordinator',
  model: 'gemini-2.5-pro',
  description: 'ユーザーの意図に応じて適切なエージェントを選択するコーディネータ',
  instruction: `
    ユーザーのリクエストを理解し、以下のサブエージェントから最適なものを選んでタスクを委任してください:
    - 翻訳が必要な場合: translator
    - 要約が必要な場合: summarizer
    - 詳細な分析が必要な場合: analyzer
    複数のサブエージェントを組み合わせることも可能です。
  `,
  subAgents: [translatorAgent, summarizerAgent, analyzerAgent],
});

Geminiモデルの選択

ADK TypeScriptでは、エージェントごとに異なるGeminiモデルを指定できます：

モデル 用途 特徴
gemini-2.5-flash 高速レスポンス 低レイテンシ、低コスト
gemini-2.5-pro 高精度な推論 複雑な分析・推論タスク
gemini-3-flash-preview 最新モデル高速版 ADK最新対応モデル
gemini-3.1-pro-preview 最新モデル高性能版 最高品質の出力

利用可能なモデルIDは変更される可能性があります。最新の正確なIDはGoogle AI Studioのモデルドキュメントで確認してください。

MCP Toolboxとの統合

ADK TypeScriptはMCP（Model Context Protocol）Toolbox for Databasesとネイティブに統合されています。公式ドキュメントのMCP tools - ADKでは、MCPサーバー経由でデータベースなどの外部リソースをエージェントのツールとして利用する手順が解説されています。

MCPToolboxの具体的なAPIと設定方法は、MCP tools公式ドキュメントで最新情報を確認してください。

Google Cloud Runへのデプロイ

Dockerfileの作成

FROM node:24-slim

WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production

COPY dist/ ./dist/
COPY agent.ts ./

EXPOSE 8080
CMD ["node", "--experimental-vm-modules", "dist/agent.js"]

Cloud Runへのデプロイ

# ビルド
npm run build

# Cloud Buildでイメージ作成
gcloud builds submit --tag gcr.io/PROJECT_ID/adk-agent

# Cloud Runにデプロイ
gcloud run deploy adk-agent \
  --image gcr.io/PROJECT_ID/adk-agent \
  --platform managed \
  --region asia-northeast1 \
  --allow-unauthenticated \
  --set-env-vars GEMINI_API_KEY=$GEMINI_API_KEY

ADK Go 1.0 — 合わせて知りたい機能

ADK Go 1.0も同時期にリリースされました。GoエンジニアがAIエージェントを本番運用する際の重要機能を紹介します。

ネイティブOpenTelemetryトレーシング

import (
    "go.opentelemetry.io/otel"
    "github.com/google/adk-go/agent"
)

// TraceProviderをプラグインするだけでトレーシング有効化
tp := initTraceProvider()
otel.SetTracerProvider(tp)

myAgent := agent.New(
    agent.WithModel("gemini-2.5-flash"),
    agent.WithName("go_agent"),
)
// これだけで全モデル呼び出しとツール実行にトレースが生成される

Human-in-the-Loop（HITL）

金融取引やDBへの書き込みなど、重要な操作に人間の確認を挟む機能：

// ツールをRequireConfirmationとしてマーク
tool := agent.NewTool(
    agent.WithName("transfer_funds"),
    agent.WithRequireConfirmation(true), // 実行前に確認イベントを発行
)

A2Aプロトコルによるクロスランゲージ通信

ADK Go 1.0はA2Aプロトコルをサポートしており、GoエージェントがJava・Python・TypeScriptエージェントとシームレスに通信できます。

まとめ

Google ADK TypeScriptの主要ポイントをまとめます：

  • インストール: npm install @google/adk で即座に利用開始できる
  • LlmAgent + FunctionTool: TypeScriptの型安全を活かした明確なツール定義
  • SequentialAgent: 複数エージェントのパイプライン（生成→レビュー→修正など）を宣言的に構築
  • コーディネータパターン: subAgents により、モデルが動的にエージェントを選択・実行
  • デプロイ非依存: Cloud Run等のサーバーレス環境へのデプロイが容易

TypeScript開発者にとって、ADKは既存のNode.jsエコシステムを活かしながらAIエージェントを構築する実践的な選択肢です。公式ドキュメントのクイックスタートから始めることを推奨します。

参考リンク

0
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?