Go 用 ADK を含む Agent Starter Pack

1. はじめに

Go を使用した ADK

モデルのトレーニングと研究には Python が依然として人気がありますが、AI エージェントのサービングとオーケストレーションの要件は、Go の強みである低レイテンシ、高並行性、型安全性に合致しています。

プロトタイプから本番環境のエージェントに移行すると、エンジニアリング上の課題が生じますが、Go はこれらの課題に非常にうまく対応できます。Go の静的型指定により、構造化された LLM 出力を解析する際のランタイム エラーがなくなります。軽量な goroutine（OS スレッドの数メガバイトと比較して、スタック メモリが数キロバイトで開始）により、エージェントは重いスレッド管理のオーバーヘッドなしで、数千の同時ツール実行を処理できます。

Google の Agent Development Kit（ADK）は、これらのアーキテクチャ上の利点と生成 AI のギャップを埋めます。このガイドでは、新しいプロジェクトをスキャフォールディングし、Google Cloud に安全なマイクロサービスとしてデプロイします。

手順:

  • Agent Starter Pack を使用して本番環境対応のエージェント プロジェクトをスキャフォールディングする
  • ローカルの Agent Development Kit ウェブ UI を使用してエージェントをデバッグし、テストする
  • Go ベースの ADK エージェント ロジックを開発して理解する
  • 単体テストとエンドツーエンド（E2E）テストを実行する
  • エージェントを Cloud Run に安全にデプロイする

必要なもの:

  • ウェブブラウザ（Chrome など）
  • 課金を有効にした Google Cloud プロジェクト

2. 始める前に

Google Cloud プロジェクトの作成

まだお持ちでない場合は、次の手順を実施します。

  1. Google Cloud コンソールのプロジェクト セレクタ ページで、Google Cloud プロジェクトを選択または作成します。
  2. Cloud プロジェクトで課金が有効になっていることを確認します。

Cloud Shell の起動

Cloud Shell は、必要なツールがプリロードされた Google Cloud で動作するコマンドライン環境です。このラボでは、これが主要な開発環境として使用されます。

  1. Google Cloud コンソールの上部にある [Cloud Shell をアクティブにする] をクリックします。
  2. Cloud Shell に接続したら、次のコマンドを実行して Cloud Shell で認証を確認します。
gcloud auth list
  1. 次のコマンドを実行して、プロジェクトが gcloud で使用するように構成されていることを確認します。
gcloud config get project
  1. プロジェクトが想定どおりであることを確認し、次のコマンドを実行してプロジェクト ID を設定します。
export PROJECT_ID=$(gcloud config get project)

3. Agent Starter Pack を使ってみる

幸いなことに、最初からやり直す必要はありません。Agent Starter Pack は、CI/CD パイプライン、インフラストラクチャ構成、ボイラープレート コードなど、本番環境対応のフォルダ構造をスキャフォールディングする CLI ツールです。

まず、uvx を指定してビルド作成コマンドを実行します。

uvx agent-starter-pack create

CLI に表示される手順に沿ってインタラクティブな設定を行います。このプロジェクトでは、次のオプションを選択します。

  • プロジェクト名: my-first-go-agent
  • テンプレート: オプション 6（Go ADK、A2A を使用した Go エージェント）
  • CI/CD: オプション 3（GitHub Actions）
  • 地域: us-central1

Agent Starter Pack の設定

緑色の「成功」メッセージが表示されたら、次の手順に進みます。

成功メッセージ

4. エージェントをローカルで可視化する

ADK の最も便利な機能の一つは、エージェントをデプロイする前に視覚的にデバッグできることです。次のコマンドを実行すると、組み込み UI を備えたローカル開発用サーバーが起動します。チャット ウィンドウはありますが、イベントやツール呼び出しなどをトレースすることで、それをはるかに超える機能を提供します。

プロジェクト ディレクトリに移動して、プレイグラウンドを開始します。

cd my-first-go-agent
make install
make playground

プレイグラウンドが実行されたら、Cloud Shell でウェブ プレビューを開き、新しく作成したエージェントを操作します。

エージェントは、エージェント AI の基盤となっているフレームワークである ReAct（Reasoning and Acting）パターンで構成されています。ReAct パターンの「思考」、「行動」、「観察」の継続的なループにより、問題解決と解釈可能性が向上し、エージェントの意思決定プロセスが透明になります。

たとえば、天気について質問すると、エージェントは意図を認識し、get_weather ツールを呼び出して、構造化データを返します。

プレイグラウンド UI

5. コードについて

エージェントの動作を確認したので、この動作を実現する Go コードを見てみましょう。ロジックは agent/agent.go にあります。このファイルは、ツールの定義、モデル構成、初期化を処理します。

ADK は標準の Go 構造体を使用して、大規模言語モデル（LLM）がコードとやり取りする方法を定義します。天気ツールの入力パラメータを定義するには、json タグと jsonschema タグを含む構造体を定義します。

type GetWeatherArgs struct {
    City string `json:"city" jsonschema:"City name to get weather for"`
}

GetWeatherResult は、ツール実行後にエージェントに返されるデータの構造を定義します。

// GetWeatherResult defines the output for the get_weather tool.
type GetWeatherResult struct {
	Weather string `json:"weather"`
}

GetWeather は、tool.Context と引数構造体を受け取り、ビジネス ロジックを実行して結果構造体を返す標準の Go 関数です。

// GetWeather returns mock weather data for a city.
func GetWeather(_ tool.Context, args GetWeatherArgs) (GetWeatherResult, error) {
	return GetWeatherResult{
		Weather: "It's sunny and 72°F in " + args.City,
	}, nil
}

NewRootAgent 関数は、アプリ ランチャーに必要な agent.Agent インスタンスを組み立てて返す役割を担います。まず、モデル構成を初期化し、genai.BackendVertexAI に基づく gemini-2.5-flash モデル インスタンスを作成します。

次に、ローカルの GetWeather 関数を functiontool にラップして、Go コードと LLM のギャップを埋めます。このステップでは、ツールを get_weather という名前で登録し、モデルのコンテキストに必要な説明を提供します。最後に、llmagent.New を使用してエージェントを構築します。これにより、初期化された Gemini モデル、エージェントの動作を定義するシステム手順、使用可能なツールのスライスが 1 つのユニットに結合されます。

// NewRootAgent creates and returns the root agent with all configured tools.
func NewRootAgent(ctx context.Context) (agent.Agent, error) {
	model, err := gemini.NewModel(ctx, "gemini-2.5-flash", &genai.ClientConfig{
		Backend: genai.BackendVertexAI,
	})

	weatherTool, err := functiontool.New(functiontool.Config{
		Name:        "get_weather",
		Description: "Get the current weather for a city.",
	}, GetWeather)

	rootAgent, err := llmagent.New(llmagent.Config{
		Name:        "my-first-go-agent",
		Model:       model,
		Description: "A helpful AI assistant.",
		Instruction: "You are a helpful AI assistant designed to provide accurate and useful information.",
		Tools:       []tool.Tool{weatherTool},
	})
	// ... (additional logic omitted for brevity)
	return rootAgent, nil
}

6. テスト

このプロジェクトには、内部ロジックの単体テストとサーバー統合のエンドツーエンド テストの両方が含まれています。

agent/agent_test.go では、GetWeather 関数は一連のテストケースで呼び出され、出力文字列が想定どおりであることを検証します。

func TestGetWeather(t *testing.T) {
	// tests struct initialized with "San Francisco" and "New York"

	for _, tt := range tests {
		t.Run(tt.name, func(t *testing.T) {
			// Pass nil for tool.Context since GetWeather doesn't use it
			result, err := GetWeather(nil, GetWeatherArgs{City: tt.city})
			if err != nil {
				t.Fatalf("GetWeather() error = %v", err)
			}
			if !strings.Contains(result.Weather, tt.wantCity) {
				t.Errorf("GetWeather() = %v, want city %v in response", result.Weather, tt.wantCity)
			}
		})
	}
}

エンドツーエンド テストでは、エージェントがサーバーとして実行されているときに正しく動作することを確認します。具体的には、A2A またはエージェント間プロトコルのサポートが正しく動作していることを確認します。E2E テストでは、サーバーの実際のインスタンスを起動し、HTTP リクエストを送信して、レスポンスを確認します。

e2e/integration/server_e2e_test.go から抜粋したスニペットを次に示します。

func TestA2AMessageSend(t *testing.T) {
    if testing.Short() { t.Skip("Skipping E2E test in short mode") }

    // Start server (local variable to avoid race conditions)
    t.Log("Starting server process")
    serverProcess := startServer(t)
    defer stopServer(t, serverProcess)

    if !waitForServer(t, 90*time.Second) {
	    t.Fatal("Server failed to start")
    }
    t.Log("Server process started")
    // ...
}

makefile を使用してすべてのテストをローカルで実行できます。

make test

7. デプロイ

エージェントを公開したり、本番環境のエコシステムに接続したりする準備ができたら、含まれているデプロイ コマンドを実行します。

make deploy

このコマンドは、--source . フラグによってトリガーされ、Google Cloud Buildpacks を使用してソースからアプリケーションを自動的にビルドします。このイメージは、いくつかの本番環境向けに最適化されたフラグ（LLM オペレーションに十分な RAM を提供する --memory "4Gi"、CPU が 24 時間 365 日割り当てられた状態を維持してコールド スタートを防ぎ、エージェントのやり取りで迅速なレスポンスを確保する --no-cpu-throttling）を使用して Cloud Run にデプロイされます。

エージェントが安全に実行されるように、システムは --no-allow-unauthenticated を使用した厳格な構成でデプロイされ、デフォルトですべての一般公開アクセスがブロックされます。リクエストには Identity and Access Management（IAM）認証が必要です。また、GOOGLE_GENAI_USE_VERTEXAI=True などの環境変数も挿入します。

Deployment Service の URL

IAP を有効にする

IAP が有効になり、メールアドレスがプリンシパルとして追加されると、デプロイ後に提供されたサービス URL に移動できます。ベースのサービス URL を表示すると、デプロイされたエージェント カードを確認できます。この JSON 構造はエージェントの標準インターフェースとして機能し、他のエージェント、オーケストレーター、ユーザー向け UI によって動的に検出され、使用されることを可能にします。

エージェント カード

8. クリーンアップ

Google Cloud アカウントに継続的に課金されないようにするには、この Codelab で作成したリソースを削除します。

Cloud プロジェクトを削除すると、そのプロジェクト内で使用されているすべてのリソースに対する課金が停止します。

gcloud projects delete $PROJECT_ID

Cloud Shell ディスクから Codelab プロジェクト ディレクトリを削除することもできます。

rm -rf ~/my-first-go-agent

9. 完了

🎊 ミッション完了！これで、Agent Development Kit を使用して Go で AI エージェントをスキャフォールディング、テスト、デプロイできました。

達成したこと:

  • Agent Starter Pack を使用して、初期の構造化されたベースラインをスキャフォールディングしました
  • エージェントの UI とコードをローカルで検証してテストしました
  • 型付きスキーマと、LLM の動作を Go オブジェクトにマッピングする関数を掘り下げて調査しました
  • Go サービスを Cloud Run にデプロイした

次のステップ

  • ADK ドキュメント: 高度なパターン、マルチエージェント オーケストレーション、メモリ システムに関する完全なガイド
  • エージェント スターター パック: マルチエージェント システムや複雑なアーキテクチャなどのテンプレートを確認する
  • Cloud Run のドキュメント: パフォーマンスの最適化、スケーリング戦略、セキュリティのベスト プラクティスについて詳しく説明します。
  • Go の並行処理パターン: goroutine とチャネルを理解すると、より効率的なエージェント ツールを構築できます。
  • Vertex AI Agent Engine: オーケストレーションとツールが組み込まれたマネージド エージェント インフラストラクチャの場合