Gemini Enterprise × shopifyで作るEC運用エージェント

未分類

Shopifyの管理画面で商品を一つずつ登録し、スプレッドシートからCSVをエクスポートしてフォーマットを整え、インポートする。EC運用に携わったことがある方なら、こうしたルーチン作業の負担は実感されているのではないでしょうか。

今回、Gemini Enterpriseとshopifyを使って、Shopifyストアを自然言語で操作できるAIエージェントを構築しました。スプレッドシートからの一括登録もチャットだけで完結します。

この記事では、実際に動くエージェントを構築する過程で得た知見と、開発中に直面した課題をまとめています。

Before/After：工数の変化

操作 手動 エージェント
商品1件の登録 管理画面で2〜3分 チャットで約10秒
50件の一括登録 CSV整形+インポートで30分〜 スプレッドシートURL指定で数分
商品情報の検索 管理画面でフィルタ操作 「〇〇の商品はありますか？」で即回答
注文・顧客データの確認 各画面を行き来 チャットで横断的に質問可能

特にスプレッドシートからの一括登録は大きな改善です。CSVフォーマットへの変換が不要で、日本語のヘッダー（「商品名」「価格」「タグ」など）をそのまま認識してShopifyのフィールドにマッピングします。

技術スタック

全体のアーキテクチャは以下の構成です。

┌─────────────────────────────────────────────┐
│          Vertex AI Agent Engine              │
│  ┌───────────────────────────────────────┐   │
│  │         root_agent (Gemini 2.5 Flash) │   │
│  │                                       │   │
│  │  Tools:                               │   │
│  │  ├─ shopify_tool (Integration Connector)  │
│  │  │   └─ Orders / Customers / Variants │   │
│  │  ├─ Shopify REST API (カスタムツール)     │
│  │  │   └─ Products CRUD                 │   │
│  │  ├─ Google Sheets API                 │   │
│  │  │   └─ read_sheet / list_sheets      │   │
│  │  └─ import_products_from_sheet        │   │
│  │      └─ スプシ → Shopify 一括登録      │   │
│  └───────────────────────────────────────┘   │
│                                              │
│  GCP: ky-gemini-enterprise                   │
│  Region: asia-northeast1                     │
└──────────┬──────────────┬────────────────────┘
           │              │
    Shopify REST API   Google Sheets API
           │              │
    ┌──────┴──────┐  ┌───┴──────────┐
    │  Shopify    │  │ Google       │
    │  Store      │  │ Spreadsheet  │
    └─────────────┘  └──────────────┘

主な技術要素は以下の通りです。

  • Google ADK（Agent Development Kit）：エージェントのフレームワーク。Pythonで記述できます
  • Gemini 2.5 Flash：LLMモデル。高速かつコスト効率に優れています
  • Vertex AI Agent Engine：エージェントのホスティング基盤。コマンド1つでデプロイ可能です
  • Integration Connectors：GCPのコネクタ機能。Shopifyの注文・顧客データはこちらを経由しています
  • Shopify REST Admin API：商品操作はREST APIを直接呼び出しています（理由は後述）
  • Google Sheets API：スプレッドシートの読み取り。ADC認証を使用しています
  • Secret Manager：Shopifyのアクセストークン管理に使用しています

エージェントの中身

ADKのエージェント定義はシンプルです。agent.pyにモデル・instruction・ツール一覧を記述します。

root_agent = Agent(
    model="gemini-2.5-flash",
    name="root_agent",
    description="Shopifyストアの在庫・注文・顧客データを自然言語で操作するエージェント",
    instruction=(
        "あなたはShopifyストア管理アシスタントです。"
        "ユーザーの自然言語による指示に基づき、Shopifyストアのデータを操作してください。\n"
        "\n"
        "## ツール使い分け\n"
        "- 商品の操作: list_products, get_product, create_product, ...\n"
        "- 注文・顧客: shopify ツールを使用\n"
        "- スプシ→Shopify一括登録: import_products_from_sheet を使用\n"
        "\n"
        "## 重要: 作成・更新・削除の確認ルール\n"
        "商品・注文・顧客の作成・更新・削除を実行する前に、\n"
        "必ずユーザーに確認を求め、承認を得てから実行する\n"
    ),
    tools=[
        shopify_tool,
        list_products, get_product, create_product,
        update_product, delete_product,
        import_products_from_sheet,
        read_sheet, list_sheets,
    ],
)

ポイントはinstructionの設計です。「ツールの使い分けルール」と「確認フロー」をプロンプトに記述しておくと、LLMが自律的にツールを選択し、破壊的な操作の前にはユーザーへ確認を行います。

UIは一切作成していません。Agent Engineのチャットインターフェースをそのまま利用しています。

開発中に直面した3つの課題

「ADKでShopifyに繋ぐだけ」と思いがちですが、実際にはいくつかの課題がありました。同様の構成を検討される方の参考になれば幸いです。

1. Integration ConnectorのProducts問題

GCPのIntegration ConnectorsにはShopifyコネクタがあり、ADKからApplicationIntegrationToolsetで簡単に利用できます。注文や顧客はこれで問題なく動作します。

しかし、Productsエンティティだけはエラーになりました。コネクタが返すフィールドに「パブリケーション関連」の項目が含まれており、Shopifyのカスタムアプリではこの権限がないためです。Shopify Plus以外ではパブリケーションAPIにアクセスできないことが原因でした。

解決策として、商品操作のみREST APIを直接呼び出す構成にしています。

# tools.py - コネクタ側（注文・顧客はこちらで対応）
shopify_tool = ApplicationIntegrationToolset(
    project="ky-gemini-enterprise",
    location="asia-northeast1",
    connection="shopifyagenttool",
    entity_operations={
        # Products はカスタムツールで対応（コネクタのパブリケーション問題回避）
        "Orders": ["LIST", "GET", "CREATE", "UPDATE", "DELETE"],
        "Customers": ["LIST", "GET", "CREATE", "UPDATE", "DELETE"],
        "ProductVariant": ["LIST"],
    },
)
# shopify_products_tool.py - REST API直接呼び出し側
def _shopify_request(method, path, body=None):
    token = _get_shopify_token()  # Secret Managerから取得
    url = f"https://{_SHOP_DOMAIN}/admin/api/{_API_VERSION}/{path}"

    req = urllib.request.Request(
        url, data=json.dumps(body).encode("utf-8") if body else None,
        method=method,
        headers={
            "X-Shopify-Access-Token": token,
            "Content-Type": "application/json",
        },
    )
    with urllib.request.urlopen(req) as resp:
        return json.loads(resp.read().decode("utf-8"))

コネクタとREST直接呼び出しのハイブリッド構成です。やや泥臭い方法ではありますが、現時点では最も確実なアプローチでした。

2. Google Sheets APIのADCスコープ

ローカル環境でadk web（ADKの開発サーバー）を起動し、スプレッドシートの読み取りを試したところ、403 Forbiddenが発生しました。

原因は、ADC（Application Default Credentials）にGoogle Sheets APIのスコープが含まれていなかったことです。gcloud auth application-default loginのデフォルトスコープではSheets APIにアクセスできません。

# 以下のようにスコープを明示的に指定する必要があります
gcloud auth application-default login \
  --scopes="https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/spreadsheets.readonly"

Agent Engine上ではサービスアカウントが使用されるためこの問題は発生しませんが、ローカル開発時にはスコープの指定を忘れないよう注意が必要です。

3. シート名「Sheet1」問題

スプレッドシートの読み取りでデフォルトシート名を"Sheet1"と指定していたところ、400 Bad Requestが返されました。

日本語環境で作成されたスプレッドシートでは、最初のシート名が「シート1」になります。「Sheet1」は英語環境でのデフォルト名です。

対処として、シート名が省略された場合はSpreadsheets APIで最初のシート名を動的に取得する仕組みを実装しました。

def _get_first_sheet_name(spreadsheet_id):
    service = _get_sheets_service()
    result = service.spreadsheets().get(spreadsheetId=spreadsheet_id).execute()
    sheets = result.get("sheets", [])
    if sheets:
        return sheets[0]["properties"]["title"]
    return "Sheet1"

def read_sheet(spreadsheet_id, range_name=""):
    if not range_name:
        range_name = _get_first_sheet_name(spreadsheet_id)  # 自動検出
    # ...

小さな問題ですが、こうした「実際に運用して初めて気づく落とし穴」は少なくありません。

スプレッドシートからShopifyへの一括登録

今回のエージェントで特に実用性が高い機能が、スプレッドシートからの一括商品登録です。スプレッドシートのURLを指定して「登録して」と伝えるだけで、商品がShopifyに一括で登録されます。

ポイントはヘッダー行の自動マッピングです。

_HEADER_MAP = {
    "title": "title",   "タイトル": "title",  "商品名": "title",
    "body_html": "body_html", "説明": "body_html", "description": "body_html",
    "vendor": "vendor",  "ベンダー": "vendor",
    "product_type": "product_type", "商品タイプ": "product_type",
    "tags": "tags",      "タグ": "tags",
    "price": "price",    "価格": "price",
}

日本語・英語どちらのヘッダーにも対応しています。スプレッドシート側で「商品名」「価格」「タグ」と記載しておけば、そのままShopifyの対応フィールドにマッピングされます。

エージェントの動作としては、いきなり登録を実行するのではなく、まずread_sheetでスプレッドシートの内容をユーザーに提示し、確認を得てからimport_products_from_sheetを実行します。この手順はinstructionに記述してあるため、LLMが自動的にこのフローを踏みます。

Agent Engineを使ってみた所感

実際にAgent Engineを使用して感じた利点と制約をまとめます。

利点

  • デプロイが1コマンド：adk deploy agent_engineでVertex AI上にデプロイが完了します。Dockerfileやインフラ設定は不要です
  • GCPネイティブ：IAM、Secret Manager、Integration Connectorsとシームレスに統合されており、認証・認可を自前で実装する必要がありません
  • ローカル開発が容易：adk webコマンドでローカルにチャットUIが起動し、試行錯誤のサイクルを高速に回せます
  • Pythonだけで完結：フロントエンドやインフラの構築なしにエージェントを開発できます

制約・注意点

  • チャットUIのみ：Agent Engine上ではチャットベースのインタラクションに限定されます。カスタムUIやダッシュボードが必要な場合は別途開発が必要です
  • Shopify APIのレート制限：REST APIは2リクエスト/秒のため、一括登録は理論上600件程度/5分が上限です。大量データを扱う場合はバッチ処理の設計が必要になります
  • google_searchとの共存制約：ADKのgoogle_searchツールは他のツールと同時に使用できません。利用する場合はサブエージェントへの分離が必要です
  • ローカル開発時のADC：前述の通り、スコープ指定を忘れると認証エラーが発生します

総合的に、GCP環境を利用しているプロジェクトであれば、エージェント開発の有力な選択肢になると感じました。特にIntegration Connectorsを通じて既存のSaaSと接続できる点は大きな強みです。

次の展開

今回のShopifyエージェントはEC運用の自動化が目的でしたが、同じADK + Agent Engineの構成でコンテンツ生成エージェントの開発も進めています。

こちらはマルチエージェント構成を採用しており、コンテキスト収集・トピック提案・本文生成・品質チェックをそれぞれ専門のサブエージェントが担当します。スプレッドシート上のブランドガイドラインやペルソナ情報を読み込み、ブランドのトーンに沿った記事を自律的に生成する仕組みです。

ADKのマルチエージェント機能（sub_agents）を使うと、エージェント間の役割分担を明確に定義できます。単一エージェントでは扱いにくい複雑なワークフローも、分割統治の考え方で対応可能になります。

まとめ

Google ADK + Agent Engineは、想定以上に実用的な組み合わせでした。

  • Pythonだけでエージェントを構築できる
  • GCPのサービスとネイティブに統合できる
  • デプロイが容易
  • instructionの設計次第で、確認フローやツール選択をLLMに委ねられる

EC運用に限らず、「SaaSの管理画面を繰り返し操作するタイプの業務」であれば、同様のアプローチで自動化が可能です。GCP環境をお使いであれば、まずはadk webで試してみることをおすすめします。

プロフィールを見る
PAGE TOP
タイトルとURLをコピーしました