Container Service for Kubernetes:AgentScope を使用した Knative サービスへのエージェントアプリケーションのデプロイ

仕組み

agentscope deploy knative コマンドは、エージェントアプリケーションのコンテナ化およびクラスターへのデプロイという複雑な手順をラップします。そのコアワークフローは以下のとおりです：

1. アプリケーションのパッケージ化：指定された Python エージェントアプリケーションのコード、依存関係（requirements.txt に記述）および環境変数をバンドルします。

2. イメージのビルド：指定されたベースイメージおよびローカルの Docker 環境を用いて、エージェントアプリケーションを含むコンテナイメージをビルドします。

3. イメージのプッシュ：ビルド済みのイメージを、ACR などのコンテナレジストリにプッシュします。

4. サービスのデプロイ：宛先クラスター内で Knative Service (ksvc) リソースのマニフェストを生成・適用します。Knative はこのマニフェストを用いてデプロイメントおよび Pod を作成し、ネットワークルーティング、ロードバランシング、および自動スケーリングポリシーを自動的に設定します。

事前準備

• クラスター内に Knative コンポーネントをデプロイ済みである必要があります。詳細については、「Knative コンポーネントのデプロイ」をご参照ください。

• コンテナイメージのビルドのため、ローカルに Docker をインストール・起動済みである必要があります。

• pip コマンドを使用して、AgentScope Runtime をインストール済みである必要があります。

  # 基本的なインストール
  pip install agentscope-runtime>=1.1.0
  
  # Kubernetes デプロイメント向けの依存関係
  pip install "agentscope-runtime[ext]>=1.1.0"

ステップ 1：エージェントプロジェクトの作成

まだエージェントアプリケーションをお持ちでない場合は、以下のサンプルのディレクトリ構造およびコードをご利用ください。

1. プロジェクトのディレクトリ構造を作成します：

   my-agent-project/
   ├── app_agent.py          # エージェントアプリケーションのメインファイル
   ├── requirements.txt      # Python 依存関係（任意）
   └── .env                  # 環境変数（任意）

2. app_agent.py ファイルにエージェントコードを記述します。

   以下のコードは、Qwen モデルを活用し、コード実行およびマルチターン対話に対応するエージェントを作成します。

   # -*- coding: utf-8 -*-
   import os
   from contextlib import asynccontextmanager
   
   from fastapi import FastAPI
   from agentscope.agent import ReActAgent
   from agentscope.formatter import DashScopeChatFormatter
   from agentscope.model import DashScopeChatModel
   from agentscope.pipeline import stream_printing_messages
   from agentscope.tool import Toolkit, execute_python_code
   from agentscope.memory import InMemoryMemory
   from agentscope.session import JSONSession
   
   from agentscope_runtime.engine.app import AgentApp
   from agentscope_runtime.engine.schemas.agent_schemas import AgentRequest
   
   @asynccontextmanager
   async def lifespan(app: FastAPI):
       """サービスの初期化処理"""
       app.state.session = JSONSession(
           save_dir="./",  # セッションファイルを保存するディレクトリ
       )
       try:
           yield
       finally:
           print("AgentApp はシャットダウン中です...")
   
   # AgentApp の作成
   agent_app = AgentApp(
       app_name="MyAssistant",
       app_description="役立つアシスタントエージェント",
       lifespan=lifespan,
   )
   
   @agent_app.query(framework="agentscope")
   async def query_func(
       self,
       msgs,
       request: AgentRequest = None,
       **kwargs,
   ):
       """ユーザークエリの処理"""
       session_id = request.session_id
       user_id = request.user_id
   
       # Python 実行機能付きのツールキットを作成
       toolkit = Toolkit()
       toolkit.register_tool_function(execute_python_code)
   
       # エージェントの作成
       agent = ReActAgent(
           name="MyAssistant",
           model=DashScopeChatModel(
               "qwen-turbo",
               api_key=os.getenv("DASHSCOPE_API_KEY"),
               enable_thinking=True,
               stream=True,
           ),
           sys_prompt="あなたは役立つアシスタントです。",
           toolkit=toolkit,
           memory=InMemoryMemory(),
           formatter=DashScopeChatFormatter(),
       )
       agent.set_console_output_enabled(False)
   
       await agent_app.state.session.load_session_state(
           session_id=session_id,
           user_id=user_id,
           agent=agent,
       )
   
       async for msg, last in stream_printing_messages(
           agents=[agent],
           coroutine_task=agent(msgs),
       ):
           yield msg, last
   
       await agent_app.state.session.save_session_state(
           session_id=session_id,
           user_id=user_id,
           agent=agent,
       )
   
   
   if __name__ == "__main__":
       agent_app.run()

ステップ 2：エージェントアプリケーションのデプロイ

agentscope deploy コマンドを用いて、ローカルのエージェントアプリケーションをワンクリックで Knative サービスとしてデプロイします。

ステップ 3：デプロイ済みエージェントへのアクセス

1. アクセスゲートウェイを取得します。

   1. ACK クラスター ページで、ご利用のクラスター名をクリックします。クラスターの詳細ページ左側のナビゲーションウィンドウで、Applications > Knative をクリックします。

   2. サービス管理 または コンポーネント管理 ページで、ゲートウェイ を取得します。

      

2. curl コマンドを使用して、エージェントサービスにリクエストを送信します。

   以下のコマンド内の 115.29.xxx.xxx を、Knative アクセスゲートウェイの IP アドレスに置き換えます。Host には、先ほど記録した URL を指定します。

   curl -i -X POST "http://115.29.xxx.xxx:80/process" \
     -H "Content-Type: application/json" \
     -H "Host: agent-03e*****.default.example.com" \
     -d '{
       "input": [
         {
           "role": "user",
           "content": [
             {
               "type": "text",
               "text": "こんにちは、お元気ですか？"
             }
           ]
         }
       ],
       "session_id": "123"
     }'

3. 応答を確認します。これはストリーミング応答であり、エージェントの推論ステップおよび最終出力を含みます。

ステップ 4：自動スケーリングの確認

• スケールイン：一定期間リクエストがない場合、Knative はリソース節約のため、サービスをゼロ Pod まで自動的にスケールインします。以下のコマンドで Pod の変更を継続的に監視できます。

  # 指定された名前空間内の Pod を継続的に監視
  kubectl get pods -n default -w

  また、Knative ページで サービス管理 をクリックし、サービス名をクリックした後、ページ下部で現在のバージョンの Pod ステータスを確認することもできます。

  

• スケールアウト：新しいリクエストが到着すると、Knative は数秒以内に新しい Pod を起動してリクエストを処理します。

本番環境に適用時の注意点

• 永続性：サンプルコード内の InMemoryStateService および InMemorySessionHistoryService は、Pod の再起動後にすべての状態および会話履歴を失います。本番環境では不適切です。本番環境では、Redis またはその他の永続ストレージソリューションに切り替えてください。

• シークレット管理：API_KEY などの機密情報を、コマンドライン引数やソースコードへの直接記述ではなく、Kubernetes Secrets を使用して Knative Service の構成に環境変数としてマウントしてください。

• リソース計画：ワークロードに基づき、負荷テストを実施して --cpu-request、--cpu-limit、--memory-request、--memory-limit の適切な値を評価・設定してください。これにより、パフォーマンスおよび安定性が確保されます。

• 観測可能性：ログ収集（例：ACK 向け Simple Log Service）、モニタリングおよびアラート（例：ARMS）を設定し、問題のトラブルシューティングおよびサービスの健全性監視を行ってください。

関連操作

• エージェントの更新：コードを変更した後は、新しいイメージタグ（例：--image-tag v1.1）を指定して agentscope deploy knative コマンドを再実行することで、ローリングアップデートを実行できます。

• エージェントのアンインストール：

  # <resource-name> および <namespace> を実際の値に置き換えてください
  kubectl delete ksvc <resource-name> -n <namespace>

  この操作は、Kubernetes 内のサービスのみを削除します。コンテナレジストリ内のコンテナイメージは削除されません。