はじめに

IBM watsonx OrchestrateのエージェントとツールをGitHub Actionsで自動デプロイする方法を試してみました。手動でのデプロイから解放され、コード変更時に自動的にIBM watsonx Orchestrateへデプロイできるようになります。

※ 本記事では簡単のため、CICDのうちデプロイ（CD: Continuous Deployment）のみを実装しています。

2025/07/31 追記
すみません、自動デプロイと言いつつ、下記手順は「インポート」まででした。そのうち対応してくれることに期待です。
最後の「デプロイ」は下記手順で実施できます。

https://developer.watson-orchestrate.ibm.com/agents/deploy_agent#deploying-agents

APIとしても「リリース」のAPIがあるので、これでもできる気がしてるのですが、未検証です。

https://developer.watson-orchestrate.ibm.com/apis/agent-releases/release-an-agent-by-id

2025/09/03 追記
「デプロイ」できるようになったみたいです！

orchestrate agents deploy -n <agent-name>

https://developer.watson-orchestrate.ibm.com/agents/deploy_agent#deploying-and-undeploying-agents

自動デプロイするメリット

効率化

手動作業を自動化し、開発・デプロイ・運用のスピードを大幅に向上させる

品質向上

ヒューマンエラーを防ぎ、コードレビューやテストを通じて安全性と信頼性を確保する

運用改善

環境の一貫性を保ち、変更履歴の管理と迅速な復旧を実現する

前提条件

IBM Cloud アカウント
IBM watsonx Orchestrate インスタンス
GitHub リポジトリ

プロジェクト構成

.
├── .github/workflows/
│   └── deploy.yml              # GitHub Actions ワークフロー
├── agents/
│   └── hello-agent.yaml        # エージェント定義
├── tools/
│   └── return_hello.py         # ツール実装
└── README.md

手順

1. 認証情報の設定

GitHub リポジトリにSecretsを設定します。

認証情報の取得:

IBM Cloud コンソールにログイン
IBM watsonx Orchestrate インスタンスを選択
「サービス資格情報」からAPI キーを取得
サービスインスタンスURLを確認（https://api.us-south.watson-orchestrate.cloud.ibm.com/instances/your-instance-idの形式）

設定方法:

GitHubリポジトリの「Settings」タブを開く
左メニューの「Secrets and variables」→「Actions」を選択
「New repository secret」をクリック
以下のSecretsを追加
- WO_API_KEY: IBM watsonx Orchestrate API キー
- WO_URL: IBM watsonx Orchestrate インスタンス URL

2. ツールの実装

from ibm_watsonx_orchestrate.agent_builder.tools import tool


@tool
def return_hello(name: str) -> str:
    """
    Returns a greeting with the provided name

    :param name: The name to include in the greeting
    :returns: A greeting string in the format "Hello [name]"
    """

    return "Hi " + name

3. エージェントの定義

spec_version: v1
style: default
name: hello_agent
llm: watsonx/meta-llama/llama-3-2-90b-vision-instruct
description: >
  名前を確認してあいさつを返すエージェント
instructions: >
  あいさつされたら、名前を確認してreturn_helloに名前を渡して、結果を返して。
collaborators: []
tools:
  - return_hello

4. GitHub Actions ワークフロー

name: Deploy watsonx Orchestrate Agent

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: "3.11"

      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install ibm-watsonx-orchestrate

      - name: Configure watsonx Orchestrate environment
        env:
          WO_API_KEY: ${{ secrets.WO_API_KEY }}
          WO_URL: ${{ secrets.WO_URL }}
        run: |
          orchestrate env add -n production -u "$WO_URL"
          orchestrate env activate production --api-key "$WO_API_KEY"

      - name: Import tools
        run: |
          orchestrate tools import -k python -f tools/return_hello.py

      - name: Import agents
        run: |
          orchestrate agents import -f agents/hello-agent.yaml

作成したエージェントの動作

デプロイが完了すると、IBM watsonx Orchestrateでエージェントが利用できるようになります。

シンプルなhello-agentですが、以下のような動作を確認できます：

ユーザーからの挨拶に対してツールを使用した応答

GitHub Actionsの実行確認

mainブランチにプッシュまたはプルリクエストを作成すると、GitHub Actionsが自動的に実行されます。

自動実行される処理:

Python環境のセットアップ
IBM watsonx Orchestrate ADKのインストール
環境設定と認証
ツールのデプロイ
エージェントのデプロイ

ローカルでの動作確認

デプロイ前にローカルで動作確認することも可能です。

# IBM watsonx Orchestrate ADKをインストール
pip install ibm-watsonx-orchestrate

# 環境設定
orchestrate env add -n test -u YOUR_URL
orchestrate env activate test --api-key YOUR_API_KEY

# ツールをインポート
orchestrate tools import -k python -f tools/return_hello.py

# エージェントをインポート
orchestrate agents import -f agents/hello-agent.yaml

まとめ

GitHub ActionsとIBM watsonx Orchestrate ADKを組み合わせることで、エージェントとツールの自動デプロイが実現できました。これにより開発効率が大幅に向上し、継続的な改善が可能になります。

コード変更から本番環境への反映までが自動化されるため、開発者はエージェントとツールの作成に集中できるようになります。

参考文献