[実践ADK] ADKとLyriaとChainlitで音楽生成エージェント - ③ Agent EngineでAgentのホスティング
こんにちは、サントリーこと大橋です。
このシリーズでは、ADK (Agent Development Kit) とLyria、Chainlitを使って音楽生成エージェントを作成する方法を解説してきました。
前回、前々回に引き続き、ADK(Agent Development Kit)、Lyria、Chainlitで音楽生成エージェントを作成し、今回はAgent Engine(AI Agentホスティングサービス)とCloud Runへのデプロイと利用方法を解説します。
前回の記事は以下です。
前回はChainlitを使って、ChatUIを作成しました。
構成や、ADKで作成したAI Agentについては前々回の記事を参照してください。
今回は作成したAI AgentをAgent Engineへデプロイし、Agent Engine経由でのAI Agentの利用方法を解説します。
Agent Engineとは
Agent EngineはGoogle Cloud上でAI Agentを動かすためのフルマネージドサービスです。
ADKやLangChainなどで作成したAI Agentをデプロイすることで、AI AgentをAPI経由で利用できるようになります。
また、Agent Engineはセッション管理、Exampleストア、モニタリング、トレーシングといった周辺機能も提供します（ただし、モニタリングとトレーシングはCloud MonitoringやCloud Traceの機能であり、Cloud Runでも利用可能です）。
Agent Engineの裏側はCloud Runですが、お値段はちょっとだけCloud Runより高めな設定になっています。
Agent Engineを使う利点
Agent Engineを使う利点は
- APIの開発が不要
- セッション管理をAgent Engineに任せられる
- Example Store管理をAgent Engineに任せられる
- Vertex AI SDK経由でAPIを呼び出しできる
という点です。
基本的にAI Agentの開発に集中すれば、AI Agentを利用可能な状態にできるのが利点の一つです。
また、セッション管理については、Cloud Runなどで運用する場合はFirestoreなどのデータベースを用意する必要がありますがAgent Engineではその準備が不要になる点も利点と言えます。
あとはVertex AI SDKを利用していれば、requestsのようなhttp requestライブラリを利用せずに、AI Agentの呼び出しを行うことができるようになります。
AdkApp
AdkAppはADKをAgent Engineで利用するためのラッパークラスで以下のようにADKのagentをコンストラクタに渡して、Agent EngineへデプロイするとAgent Engine上でADKを利用できるようになります。
from vertexai import agent_engines
from google.adk impot Agent
from vertexai.preview import reasoning_engines
agent = Agent(...) # ADKのagentを作成
requirements = [...] # 必須パッケージ
packages = [...] # ローカルパッケージ
display_name = "Agentの表示名"
app = reasoning_engines.AdkApp(agent=agent, enable_tracing=True)
agent_engine_app = agent_engines.create(
agent_engine=adk_app,
display_name=display_name,
requirements=requirements,
extra_packages=packages,
)
agent_engine_app.stream_query(...) # Agentの呼び出し
Vertex AI SDK経由でAgnet Engingeを呼び出す場合は以下のように一度agent_engineインスタンスを取得して実行します。
vertexai.init(project=self.settings.GOOGLE_CLOUD_PROJECT, location=self.settings.GOOGLE_CLOUD_LOCATION)
resource_id = f"projects/{self.GOOGLE_CLOUD_PROJECT}/locations/{self.GOOGLE_CLOUD_LOCATION}/reasoningEngines/{self.GOOGLE_CLOUD_AGENT_ENGINE_ID}"
app = agent_engines.get(resource_id)
agent_engine_app.stream_query(...) # Agentの呼び出し
詳しくは以下を参照してください。
AdkAppのカスタマイズ
ここではAdkAppの標準機能では対応できない課題とその解決方法について書きます。
前回の記事でも紹介しましたが、今回のアプリケーションではAdkAppを直接使わずに、いくつかの機能を追加しています。
これはAdkAppがいくつかの課題を抱えているためです。
- ADK 1.0.0が使えない
- 2025/05/29にリリースされた Vertex AI SDK 1.95.0で解決されました。
- ADKのRunnerにRunConfigが渡せない
- ArtifactをAgent Engine経由で取得する方法がない
1.の問題はちょっとどうしようもないですが、 2.と3.の問題を解決するために今回のアプリケーションではAdkAppを拡張したクラスを利用しています。
[解決済み] ADK 1.0.0が使えない
このアプリケーションを作成した時点では、Agnet EngineではADK 1.0.0が利用できませんでした。
これは、ADKのSessionやArtifactに関するメソッド群がasync/awaitを利用したインターフェースに変更になり、Agent Engine側がそれに対応していなかった為です。
ただ問題は 2025/05/29にリリースされた Vertex AI SDK 1.95.0で解決されました。
ADKのRunnerにRunConfigが渡せない
前回の記事でも紹介していますが、GeminiなどのLLMでは、ストリーム形式のレスポンスをサポートしています。
ストリームモードを用いた場合、返却されるメッセージは一部分ずつ連続的にストリームで返却されます。
ADKでこのモードを動かすためには
-
adk webやadk api-serverで起動したAPIの場合はPOSTするJSONパラメータにstream: true を渡す - ADKのRunnerの場合はRunConfigにStreamingMode.SSEを渡す
必要があります。
ただ、Agent EngineのAdkAppではRunConfigを渡すことができません。
このため、標準のままでは、ストリームモードでLLMを起動することができません。
この課題はVertex AI SDKのissueに登録済みです。
ArtifactをAgent Engine経由で取得する方法がない
今回のアプリケーションではArtifactに音楽データを保存しますが、
AdkAppではArtifactを取得する手段を用意していません。
そもそもAdkAppではデフォルトでInMemoryArtifactServiceを利用するようになっています。
これは名前の通りArtifactがインメモリが保存されますが、Agentのレスポンス経由でArtifactを返却しなかった場合、後からArtifactを取得しようとしても、Cloud Run上で動作しているため、アクセス先のサーバーがスケールアップ/ダウンしている可能性があります。
そのため、Artifactを保存しているサーバーにアクセスできるとは限らず、結果としてArtifactが取得できなくことがあります。
このため、AdkAppでは使用する ArtifactServiceを切り替えることが可能です。
具体的には以下のようにArtifactServiceのビルダー関数をAdkAppに渡してあげます。
bucket = os.environ.get('ARTIFACT_BUCKET')
def generate_artifact_service():
return GcsArtifactService(bucket)
adk_app = AdkApp(agent=root_agent, enable_tracing=True, artifact_service_builder=generate_artifact_service)
上記の設定により、ArtifactはGCSに保存されるようになります。そのため、クライアントはGCS経由で直接Artifactを取得し、ダウンロードすることが可能になります。
ただ個人的には、Artifactの保存場所を知っているのはAI Agent(Artifact Service)であって、
クライアントが直接ダウンロードするのは、設計思想として必ずしも適切ではないように感じています。
この課題についても以下にissue登録してあります。
カスタムAdkApp
これらの課題を解決するためには、AdkAppを拡張する必要があります。
そもそもAgent Engineに渡しているこのAdkAppは、純粋なPythonクラスで、お作法に沿って実装すれば、いくらでも拡張することができます。
このあたりの方法を利用してAgent EngineでGenkitを動かしている記事が以下です。
今回は 「ストリームモードのサポート」と「Artifactのダウンロード」を追加したCustomAdkAppを作成しています。
実装内容自体もそれほど複雑ではなく、以下のようにRunConfigを渡すバージョンのメソッドを追加している点と
Artifactのダウンロード処理を追加している点、
最後に、カスタムAdkAppを利用するために必要な関数の登録とクローン処理の上書きをしているだけです。
特にクローン処理は忘れると、拡張前のAdkAppが使われてハマることになるので注意してください。
Agent Engineへデプロイ
これで準備は整いました。
AI AgentをAgent Engineへデプロイしてみます。
Agent Engineへのデプロイは前述の通り、Vertex AI SDK経由で行います。
以下のような簡単なデプロイスクリプトを用意しておくと便利です。
なお今回のデプロイスクリプトでは、少し特殊な処理が追加されています。
前々回の記事でも書きましたが、Agent EngineではPyPIに登録されているライブラリは取得できるものの、ffmpegのようなOSレベルのパッケージは直接インストールすることができません。
今回のアプリケーションでは音楽データのmp3化の為に、pydubを利用しており、pydubがffmpeg経由で処理を行っているため、ffmpegのバイナリが必要になります。
このため、デプロイスクリプト中でffmpegのバイナリをパッケージ内にダウンロードし、Agent Engineへパッケージごとデプロイをするようにしています。
この辺りは、そのうち解決方法が出るかもしれません。
後はこのデプロイスクリプトを実行すればAgent EngineへAI Agentがデプロイされます。
uv run deploy_agentengine.py
なお、上記のデプロイスクリプトを初めて実行すると、.agentengine.jsonというファイルが作成されます。
これは、2回目以降のデプロイ時に、同じAgent Engineインスタンスを更新するためのものです。
使ってみる
では、Agent Engine経由でAI Agentを動作させてみましょう。
ChatUIの.envファイルを以下の様に設定し、Agnet Engine経由でAI Agentを実行するようにします。
GOOGLE_CLOUD_PROJECT={your-project}
GOOGLE_CLOUD_LOCATION=us-central1
BACKEND_TYPE=agentengine
GOOGLE_CLOUD_AGENT_ENGINE_ID={AGENT ENGINEのID}
この状態でChatUIを起動すればAgent Engine経由でAI Agentが実行されます。
Agent Engine上で動作させているため、以下のようにCloud Console上でモニタリングが行えるようになります。
またトレース情報も見れます。
SessionもAgent Engineに保存されていますね。
Trace
なお、以下のissueにも登録してあるのですが、Cloud Traceの情報については、まだまだサポートが十分でないのが現状です。
このため、より多くの情報をCloud Trace上に表示するには自身でいくつかの処理を追加する必要があります。
このあたりについては、以下で書いているので、気になる方は読んでみてください。
まとめ
以上でAgnetの作成、UIの作成、Cloud上での実行と一通り、Google Cloud上でAI Agentを動かすためのあれこれが完了しました。
実運用やスケーラビリティを考えると、さらに以下のことが必要になるかなと思います。
- IAMの管理
- オブザーバビリティ周りの強化
- A2A化
特にA2A（Agent-to-Agent）化については残念ながら2025/05/30現在ではAgent EngineではA2Aサーバー化することが(多分)不可能です。そのためComposer AgentのみをCloud Runに持っていきA2Aサーバー化、Agent Engineではセッション管理とユーザーとの対話を行うオーケストレーターAgentを配置する構成が考えられます。。
このあたりの構成についても、そのうち記事にしたいと思います。
ChatUIがCloud Runにデプロイされてない？ ~ちょっとめんどくさかった~ Dockerfileがあるので適当にCloud Runにデプロイしてください。
適当にやればできるはずです。(丸投げ)
なお、デプロイしたCloud Runのサービスアカウントに roles/aiplatform.user権限をつけるのを忘れないようにしてください。 これはAgent EngineのAPIを呼び出すのに必要な権限です。
Discussion