galaxy-automation

BioBlend と Planemo による Galaxy ワークフローの自動化

目的

このスキルでは、BioBlend（Python 用 Galaxy API ライブラリ）と Planemo（Galaxy ワークフローのテストおよび実行ツール）を使用して Galaxy ワークフローを自動化するための専門知識を提供します。

このスキルを使用するタイミング

次の場合にこのスキルを使用してください：

• API 経由で Galaxy ワークフローの実行を自動化する場合
• Galaxy 用のバッチ処理システムを構築する場合
• BioBlend を使用して Galaxy とやり取りする場合
• Planemo でワークフローをテストする場合
• Galaxy の履歴、データセット、コレクションをプログラムで管理する場合
• ワークフローの実行状態をポーリングする場合
• Galaxy の操作に対するエラー処理と再試行ロジックを実装する場合
• Galaxy 自動化パイプラインを作成する場合
• 大規模なバイオインフォマティクスのワークフローに Galaxy を統合する場合

このスキルは特定のプロジェクト専用ではありません。あらゆる Galaxy 自動化プロジェクトで役立ちます。

参考ファイル

詳細な参考資料は、別々のファイルに分かれています。

• bioblend-reference.md -- BioBlend API のパターン：接続、履歴管理、ワークフローの実行、状態確認、エラー処理、再実行 API、データセット操作、コレクション
• planemo-reference.md -- Planemo コマンドの構造、ジョブ YAML 形式、プログラムによるコマンド生成、出力の解析、Galaxy API の curl／認証パターン
• automation-patterns.md -- スレッドセーフな操作、バッチ処理、再開機能、デバッグ（履歴の調査、実行ステップの分析）

---

セキュリティのベストプラクティス

1. API キーの管理

環境変数に保存します：

import os

api_key = os.environ.get('GALAXY_API_KEY')
if not api_key:
    raise ValueError("GALAXY_API_KEY environment variable not set")

gi = GalaxyInstance(url, api_key)

ログ内でマスクします：

def mask_api_key(key):
    """Mask API key for display"""
    if len(key) <= 8:
        return '*' * len(key)
    return f"{key[:4]}{'*' * (len(key) - 8)}{key[-4:]}"

masked_key = mask_api_key(api_key)
print(f"Using API key: {masked_key}")

---

2. パスの処理

シェルコマンドでは、常にパスを引用符で囲みます：

# Good - handles spaces
command = f'planemo run "{workflow_path}" "{job_yaml}"'

# Bad - breaks with spaces
command = f'planemo run {workflow_path} {job_yaml}'

---

よくある落とし穴

1. Planemo の失敗と Galaxy の失敗

   • Planemo の戻りコード != 0：ワークフローは起動されておらず、実行情報もありません
   • 実行状態 = 'failed'：ワークフローは起動されましたが、Galaxy のジョブが失敗しました
   • この 2 種類の失敗を混同しないでください

2. 同時アップロード

   • 同時アップロードが多すぎると、Galaxy に過大な負荷がかかる可能性があります
   • max_concurrent の上限を設定します（通常は 3～5）
   • --simultaneous_uploads を使用するか、順次アップロードするかを検討してください

3. データセットの状態確認

   • アップロードが完了する前にワークフローを実行しないでください
   • データセットの状態が = 'ok' になるまで、必ず待機してください

4. 履歴名の競合

   • 一意の履歴名を使用します（タイムスタンプやサフィックスを追加します）
   • 作成する前に、既存の履歴を確認します

5. 戻りコードの解釈

   • os.system() は終了コードをシフトします（終了コード 1 → 戻り値 256）
   • 実際の終了コードを取得するには、return_code >> 8 を使用します

6. 実行 ID の復元

   • ターミナルが切断されると、実行 ID が失われます
   • 実行 ID は必ずすぐにファイルへ保存します
   • Planemo では --test_output_json を使用します

7. 重大：管理者 API キーでは、すべてのユーザーのデータが表示されます

   • フィルターなしで get_invocations() を実行すると、自分のものだけでなく、すべてのユーザーの実行情報が返されます
   • 広範なクエリ（例：「最近の実行中のもの」）に基づいて、実行をキャンセル、削除、変更してはいけません
   • 必ず、自分のツール出力に含まれる特定の実行 ID を使用します（Planemo は Invocation <hex_id> を出力します）
   • 破壊的な操作を行う前に、履歴／実行情報の所有者が自分のユーザーと一致することを確認します
   • 広範なクエリが必要な場合は、自分が所有する履歴 ID で絞り込みます
   • キャンセルした実行は復旧できません。取り消し操作もありません

8. Planemo テストの実行追跡

   • テスト実行中、Planemo は実行 ID を出力します：Invocation <52bc9f6134abd589>
   • 強制終了された Planemo テストの孤立した実行をキャンセルする場合は、これらの ID のみを使用します
   • サーバー上のすべての実行を調べ、時刻をもとに自分のものだと推測してはいけません

---

ベストプラクティスのまとめ

1. API キーには環境変数を使用します
2. ログと出力では API キーをマスクします
3. シェルコマンド内のファイルパスはすべて引用符で囲みます
4. 並行操作のためにスレッドセーフを実装します
5. 再開できるように状態をこまめに保存します
6. ワークフローを呼び出す前に、データセットのアップロードが完了するまで待ちます
7. 妥当な間隔（30～60 秒）で呼び出しステータスをポーリングします
8. planemo の失敗と Galaxy の失敗を区別します
9. 適切なエラー処理と再試行ロジックを実装します
10. 履歴名には一意の名前を使用して、競合を避けます

---

Galaxy MCP 接続

Galaxy MCP ツール（mcp__Galaxy__*）を使用するときは、各セッションの開始時に接続します。

接続パターン

MCP ツールはシェル環境変数を直接読み取れません。まず Bash で値を解決します。

# Resolve env vars
echo "$GXYVGP"   # Galaxy instance URL
echo "$TESTKEY"   # API key for testing
echo "$MAINKEY"   # Admin API key (only for admin tasks, NEVER for testing)

次に、解決した値を渡します。

mcp__Galaxy__connect(url="<resolved_url>", api_key="<resolved_key>")

重要：すべてのテストとワークフローの実行には $TESTKEY を使用してください。$MAINKEY は管理者キーであり、すべてのユーザーのデータを参照・変更できます。$MAINKEY は管理者アクセスが特に必要な場合にのみ使用してください。

既知のインスタンス

環境変数	インスタンス	備考
$GXYVGP	https://vgp.usegalaxy.org	VGP の本番環境、ユーザー：delphinel（管理者）
$TESTKEY	VGP のテスト用 API キー	すべての planemo テストとワークフローの実行に使用してください
$MAINKEY	VGP の管理者 API キー	管理者タスク専用 — すべてのユーザーのデータを参照できます。テストには絶対に使用しないでください

---

browser-use によるブラウザー自動化

browser-use を使用して Galaxy UI の操作を自動化する場合：

LLM のセットアップ

• browser-use 0.12+ には独自の ChatAnthropic ラッパーがあります。langchain_anthropic.ChatAnthropic ではなく、browser_use.llm.anthropic.chat.ChatAnthropic を使用してください。langchain 版には、browser-use が必要とする provider プロパティがありません。
• API キーは明示的に渡す必要があります：ChatAnthropic(model="claude-sonnet-4-20250514", api_key=os.environ["ANTHROPIC_API_KEY"])

ブラウザー接続

• ユーザーが管理するブラウザーへの CDP 接続を使用します：BrowserSession(cdp_url="http://localhost:9222")
• Chrome は次のコマンドで起動します：chrome --remote-debugging-port=9222
• Cookie の挿入による自動ログインは、Galaxy のセッション管理では安定して動作しません。接続する前にユーザー自身でログインしてもらいます
• browser-use は Playwright のコンテキストではなく CDP を直接使用するため、Playwright の record_video_dir は使用できません。代わりに ffmpeg で画面をキャプチャします。

Galaxy UI エージェントのヒント

• Galaxy にはツールバーのボタンの近くにソーシャルメディアのアイコンがあり、エージェントが Upload ではなく LinkedIn／Twitter を誤ってクリックする場合があります
• ホバーして確認する指示を追加します：「要素をクリックする前に、まずその要素にカーソルを合わせ、ツールチップが表示されるまで 2 秒待ってください」
• 動画の品質を重視した記録では、意図的にゆっくり操作するよう指示を追加します
• 「履歴を作成」する手順は、エージェントの開始前に bioblend API で処理し、ブラウザー上では省略します
• Zenodo の URL からのファイルアップロードでは、bioblend の upload_file() よりブラウザーの Upload ダイアログのほうが適切に動作します

---

関連スキル

• galaxy-tool-wrapping：Galaxy ツールラッパーを作成する場合
• galaxy-workflow-development：Galaxy ワークフローを作成する場合
• vgp-pipeline：VGP 固有のオーケストレーション（このスキルを依存関係として使用）

---

リソース

• BioBlend のドキュメント：https://bioblend.readthedocs.io/
• Planemo のドキュメント：https://planemo.readthedocs.io/
• Galaxy API：https://docs.galaxyproject.org/en/master/api/
• Galaxy トレーニング：https://training.galaxyproject.org/