IBM Cloud 版 watsonx Orchestrate で embedded agent を使う : まだプログラマーですが何か？

IBM Cloud から提供されている生成 AI の自動化ソリューションである watsonx Orchestrate の agent builder を使ってみました。システムプロンプトや RAG 、 MCP 、外部エージェントといった生成 AI の補助機能を簡単に使って独自エージェントを定義したり、定義したエージェントを外部公開したり、といったことが簡単に実現できる IBM の生成 AI ソリューションです（IBM Cloud アカウントがあると１か月間無料トライアルで使えます）：

ここで作成した自分のエージェントを REST API として公開することもできますが、より簡単な外部連携の方法として、小さなスクリプト（JavaScript）を HTML に貼り付けて、その HTML ページ内にチャット機能を埋め込む形でエージェントを使う、といったこともできます（embedded agent 機能と呼びます）：

（agent builder を使って作ったエージェントを・・）

（外部ウェブページに貼り付けてチャットボットとして活用する）

この embedded agent を使うことで HTML 内を編集可能なウェブページであれば（WordPress のような CMS も含めて）作成したエージェントを使ったチャットボット機能を任意のページに埋め込むことができるようになります。比較的簡単な外部連携方法の１つです。

しかし、この embedded agent 機能を私が使おうとしたところうまく動きませんでした。そこで色々調べた所、IBM Cloud 版の watsonx Orchestrate では現状（2025年12月） embedded agent はデフォルト設定のままでは正しく動作しない、ということがわかりました。2026 年初頭のアップデートによって IBM Cloud 画面内からの設定変更が可能になるような予定もあるらしいのですが、現時点では REST API を呼び出す形で watsonx Orchestrate の設定内容を変更（Security を Disabled に変更）しないと embedded agent が使えない、ということが分かりました。

そのためのセキュリティ変更を curl と jq が導入された Linux/macOS 環境で実施するためのシェルスクリプトを独自に作って用意しました。以下の内容を set_watson_embed_security.sh として保存し、実行権限を付けてください：

#!/usr/bin/env bash
# set_watson_embed_security.sh
# IBM Cloud IAM トークンを取得し、Watson Orchestrate Embed Secure Config を更新する。
# Usage:
#   bash set_watson_embed_security.sh --api-key "(API キー)" --instance-id "(インスタンスID）" [--insecure]

set -euo pipefail

IAM_URL="https://iam.cloud.ibm.com/identity/token"
WATSON_BASE_URL="https://api.jp-tok.watson-orchestrate.cloud.ibm.com"
INSECURE_FLAG=""
API_KEY=""

INSTANCE_ID=""

log() { printf '[INFO] %s\n' "$*" >&2; }
err() { printf '[ERROR] %s\n' "$*" >&2; }

# 引数パース
while (( $# )); do
  case "$1" in
    --api-key)
      API_KEY="${2:-}"; shift 2 ;;
    --instance-id)
      INSTANCE_ID="${2:-}"; shift 2 ;;
    --insecure)
      INSECURE_FLAG="--insecure"; shift ;;
    -*)
      err "不明なオプション: $1"; exit 1 ;;
    *)
      err "不明な引数: $1"; exit 1 ;;
  esac
done

# 必須チェック
[[ -n "${API_KEY}" ]] || { err "API KEY が指定されていません。--api-key を指定してください。"; exit 1; }
[[ -n "${INSTANCE_ID}" ]] || { err "INSTANCE ID が指定されていません。--instance-id を指定してください。"; exit 1; }

# jq があるか確認（任意）
JQ_AVAILABLE=0
if command -v jq >/dev/null 2>&1; then
  JQ_AVAILABLE=1
fi

log "IBM Cloud IAM アクセストークンを取得中..."


# IAM トークン取得
# 参考のコマンド例:
# curl --fail -sS --insecure --request POST \
#   --url "https://iam.cloud.ibm.com/identity/token" \
#   --header "Content-Type: application/x-www-form-urlencoded" \
#   --data "grant_type=urn:ibm:params:oauth:grant-type:apikey&apikey=(API KEY)"

IAM_RESP="$(curl --fail -sS ${INSECURE_FLAG} \
  --request POST \
  --url "${IAM_URL}" \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --data "grant_type=urn:ibm:params:oauth:grant-type:apikey&apikey=${API_KEY}" \
  || { err 'IAM トークン取得に失敗しました。API KEY が正しいか、ネットワーク/プロキシ/証明書を確認してください。'; exit 1; })"

# アクセストークン抽出
ACCESS_TOKEN=""
if [[ "${JQ_AVAILABLE}" -eq 1 ]]; then
  ACCESS_TOKEN="$(printf '%s' "${IAM_RESP}" | jq -r '.access_token // empty')"
else
  # jq が無い場合の簡易抽出（最低限の JSON 形式想定）
  ACCESS_TOKEN="$(printf '%s' "${IAM_RESP}" | sed -n 's/.*"access_token"[[:space:]]*:[[:space:]]*"\([^"]\+\)".*/\1/p')"
fi


if [[ -z "${ACCESS_TOKEN}" ]]; then
  err "アクセストークン抽出に失敗しました。応答: ${IAM_RESP}"
  exit 1
fi

log "アクセストークンの取得に成功しました。"

# Watson Orchestrate Embed Secure Config 更新
CONFIG_URL="${WATSON_BASE_URL}/instances/${INSTANCE_ID}/v1/embed/secure/config"
BODY='{"is_security_enabled": false}'

log "Watson Orchestrate の Embed Secure Config を更新します: is_security_enabled=false"
# ステータスコードを取得して判定

HTTP_CODE="$(curl -sS ${INSECURE_FLAG} \
  -X POST "${CONFIG_URL}" \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -d "${BODY}" \
  -w '%{http_code}' -o /tmp/watson_embed_resp.$$ || true)"

if [[ "${HTTP_CODE}" =~ ^2[0-9][0-9]$ ]]; then
  log "設定更新に成功しました。（HTTP ${HTTP_CODE}）"
  printf '\n=== API 応答 ===\n'
  cat /tmp/watson_embed_resp.$$

  printf '\n===============\n'
  rm -f /tmp/watson_embed_resp.$$
else
  err "設定更新に失敗しました。（HTTP ${HTTP_CODE}）応答ボディ:"
  printf '\n=== API 応答 ===\n'
  cat /tmp/watson_embed_resp.$$
  printf '\n===============\n'
  rm -f /tmp/watson_embed_resp.$$
  exit 1
fi

log "一連の処理が完了しました。"
exit 0

実行時は以下のように API キー（※１）と watsonx Orchestrate のインスタンス ID （※２）を指定します：

$ ./set_watson_embed_security.sh --api-key "(API キー)" --instance-id "(インスタンスID）"

※１※２いずれも IBM Cloud で watsonx Orchestrate インスタンスを選択した画面の Manage メニュー内 "Credentials" 部に記載されています。なおインスタンス ID は URL と書かれた文字列内の最後、"/instances/" に続くランダムに見える文字列部分がインスタンス ID です：

これらの情報をコマンドラインで指定して実行すると、API キーからアクセストークンを取得して、セキュリティを無効化するための API が実行されます。

処理が成功すると「設定更新に成功しました。」「一連の処理が完了しました。」というメッセージが表示されます。また API 応答結果のJSON 文字が表示され、その最後に "is_security_enabled": false と表示されていればセキュリティの無効化に成功しています：

現時点では、このセキュリティ無効化に成功できている状況下で watsonx Orchestrate の embedded agent が動きます：

なお watsonx Orchestrate における「セキュリティの有効化／無効化」についてはこちらを参照ください：
https://developer.watson-orchestrate.ibm.com/manage/channels#enabling-security

タグ：: #ibm; #cloud; #watsonx; #orchestrate; #wxo; #embedded; #agent

まだプログラマーですが何か？

プログラマーネタ中心。たまに作成したウェブサービス関連の話も https://twitter.com/dotnsf

IBM Cloud 版 watsonx Orchestrate で embedded agent を使う

コメント

カテゴリなしの他の記事

コメント