Agent EngineのエージェントをAgentspaceに登録するCLIツールを使ってみた（ハマりどころ解説）

はじめに

インフラチームのkuribo-です。

Google CloudのAgentspace、非常に強力で夢が広がりますよね。
今回は、Vertex AIにデプロイしたAgentをAgentspaceに登録・管理できる便利なコマンドラインツール（agent_registration_tool）を試してみました。
一見すると簡単そうに見えたのですが、実はいくつかの「ハマりどころ」が…。

この記事では、ツールの基本的な使い方から、私が実際に遭遇したエラーとの格闘、そして最終的に確立した正しい手順までを、余すところなく共有します。

「CLIでサクッとAgent管理したい」
「よくわからないエラーで登録に失敗した…」

そんな方の助けになれば幸いです。

今回のゴール

最終的な目標はシンプルです。

「Vertex AI Agent Engineにデプロイ済みのcity_time_agentを、CLIツールを使ってAgentspaceアプリケーションに登録する」

これを達成するために、agent_registration_toolというPython製のツールを使っていきます。
公式紹介動画：https://www.youtube.com/watch?v=yxRyVxjKURI&t=51s
リポジトリ：https://github.com/VeerMuchandi/agent_registration_tool

登録までの道のり（エラーとの戦いの記録）

一筋縄ではいかなかった、そのリアルな過程を追体験してみましょう。

1. 【エラー1】リージョンの壁

最初に試したのは、asia-northeast1にデプロイしたAgentを、globalに作成したAgentspaceアプリに登録することでした。
しかし、実行後すぐにエラーが発生。

【エラー1】 Location used for creating agent must align with supported reasoning engine location.

これは「Agentspaceアプリの場所とAgent Engineの場所には互換性が必要」という、AgentspaceにAgent Engineのエージェントを接続する際の最も重要な制約でした。
globalのアプリにasia-northeast1のAgentは登録できなかったのです。

【解決策】
us-central1に新しいAgentをデプロイし直し、接続先のAgentspaceアプリもusリージョンのものを用意することにしました。

2. 【エラー2】リージョン設定の罠

気を取り直して、us-central1のAgentをusのAgentspaceアプリに登録するようconfig.jsonのapi_locationとre_locationの2つを更新。
しかし、次に現れたのは一見不可解な404エラーでした。

【エラー2】 Error 404 (Not Found)

URLのパスは正しいように見え、原因特定は難航しました。
しかし、ログを注意深く見直すと、構築されていたAPIのホスト名が間違っていることに気づきました。

• 誤った設定: config.jsonのapi_locationに、Agentの場所である"us-central1"を設定してしまっていた。
• 誤って生成されたホスト名: us-central1-discoveryengine.googleapis.com（存在しない）
• 正しい設定: api_locationには、Agentspaceアプリの場所である"us"を設定する必要があった。
• 正しく生成されたホスト名: us-discoveryengine.googleapis.com

api_locationという言葉自体が意味がわかりづらいのですが、AgentspaceのAPIエンドポイントのロケーションという意味でした。
ですので、現在Agentspaceが対応しているglobal,eu,usのいずれかを入力する必要があったのです。

3. 【エラー3】無効な認証ID

正しいエンドポイントを叩けるようになったことで、ついに具体的なリクエスト内容の検証が始まりました。
そして、最後のシンプルなエラーにたどり着きます。

【エラー3】 Invalid Authorization name "..."

原因は、config.jsonのauth_idに、テンプレートのyour-oauth-auth-id-if-anyという文字列がそのまま入っていたことでした。
今回は認証が不要だったので、この値を空文字列 "" に修正。

4. 登録成功

今度こそコマンドは正常に実行され、エージェントの情報がJSONで返ってきました。
長かった戦いの末、ついに登録が成功した感動の瞬間です！

登録されるとこんな感じで表示されます。

手順まとめ

数々のエラーを乗り越えて確立した、エージェント登録から管理までの一連の正しい手順を以下にまとめます。

ステップ1: デプロイ済みエージェントのIDを確認する

目的: 登録に必要なadk_deployment_idを特定します。
コマンド:

python3 as_registry_client.py list_deployed_agents --location <リージョン名>

• パラメータ: --locationにはエージェントがデプロイされているリージョン（例: us-central1）を指定します。
• 確認する値: 出力されたJSONの"name"フィールドの値（projects/...から始まる完全なリソース名）がIDです。

ステップ2: config.jsonを設定する

目的: エージェント登録に必要な情報を設定します。
設定項目:

• "project_id": Google CloudプロジェクトID。
• "location": ステップ1で指定したリージョン。
• "app_id": 登録先のAgentspaceアプリケーションID。
• "ars_display_name": エージェントの表示名。
• "description": ユーザー向けのエージェントの説明。
• "tool_description": LLM向けの使い方説明。
• "adk_deployment_id": ステップ1で取得したID。
• "api_location": Agentspaceアプリの場所（例: "us"）。
• "re_location": Reasoning Engineの場所（通常は"location"と同じ）。
• "auth_id":（任意）不要な場合は ""。
• "icon_uri":（任意）アイコンURL。

ステップ3: エージェントを登録する

目的: 設定に基づきエージェントを登録します。
コマンド:

python3 as_registry_client.py register_agent

• 成功すると、登録情報が返されます。この中の"name"の末尾にある数字がAgentspaceのエージェントIDとなり、次のステップで使います。

ステップ4: （必要な場合）エージェントの登録を解除する

目的: 誤って登録したエージェントを解除します。
手順:

1. config.jsonの更新: "agent_id"キーに、ステップ3で取得したAgentspaceのエージェントIDを設定します。
2. コマンドの実行:

   python3 as_registry_client.py unregister_agent

   • 確認プロンプトにyesと答えると登録が解除されます。

おわりに

今回は、CLIツールを使ったAgentspaceへのエージェント登録という、一見シンプルな作業の裏に潜む落とし穴と、その解決プロセスをご紹介しました。

元々用意されているconfig.jsonに具体的に何を設定したら良いかがわからず試行錯誤の連続でした。
模索する過程でツールの内部実装を読み解き、APIの仕様を推測しながらエラーを1つずつ潰していく作業は、まさにエンジニアリングの醍醐味（？）ですね。
この記事が、同じような問題に直面した方の助けとなり、デバッグ時間の大幅な短縮に繋がれば、これほど嬉しいことはありません。

便利なツールも、その裏側にある仕組みを少し理解するだけで、より深く、そしてスムーズに使いこなせるようになりますね。
今後もAgentspaceの動向に注目していきます。