watsonx OrchestrateのAPIにアクセスする際は、APIリファレンスマニュアルページの違いとSaaS版ページのURL記載誤りに注意が必要です。

1. ローカルとSaaSのAPIマニュアルの違い

watsonx OrchestrateのAPIは、ローカル環境で利用できるDeveloper Editionと、有償のSaaS版で、それぞれ別のマニュアルページとAPIエンドポイントの構造を持ちます。

マニュアルページの違い

• Developer Edition（ローカルアクセス）: https://developer.watson-orchestrate.ibm.com/getting_started/wxOde_overview

• SaaS版（IBM Cloud版、オンプレミス版、AWS版） : https://developer.ibm.com/apis/catalog/watsonorchestrate--custom-assistants/Introduction

Developer Editionに記載されているAPIがすべてSaaS版で利用できるとは限らない点に注意が必要です。
＊ただし、マニュアルに記載がない機能でもDeveloper Editionで動作するものは、SaaS版でも実行可能である可能性があります。

アクセスポイントURLの違い

マニュアルの所在だけでなく、URLの構造も異なります。

• Developer Edition（ローカルアクセス）: {api_endpoint}/api/v1/{resource}

• SaaS版: {api_endpoint}/v1/{resource}《注意：ただしこれは誤り（次章参照）》

/api/v1と/v1といった違いがあるため、単にローカルをSaaS版のエンドポイントに置き換えるだけでは、アクセスは成功しません。

2. SaaS版マニュアルの記載誤り

SaaS版のマニュアルページには、APIエンドポイントの記載に誤りがあります。Request URLの記述は/v1/となっていますが、正しくは/v1/orchestrate/です。

例: Get Orchestrate settings

• 誤：マニュアル記載のRequest URL: {api_endpoint}/v1/default-agent-settings

• 正：正しいRequest URL: {api_endpoint}/v1/orchestrate/default-agent-settings

誤ったURLは 404 Not Found エラーの原因になります。

3. 不具合の発見経緯と今後の対応予定

このマニュアルの記載誤りは、私がAPIを試した際にエラーに直面し、IBMサポートに問い合わせたことで不具合として発覚しました。

現在、この不具合はIBMにより既知の問題（Known Issues）として認識されており、ドキュメントの修正が計画されています。（記事投稿日現在）

• Known Issue: DT448359

4. まとめ

watsonx OrchestrateのAPI接続では、以下への考慮が必要です。

• アクセスする方式により参照するAPIリファレンスページが異なる

• SaaS版（IBM Cloud版など）はアクセスポイントの記載に誤りが含まれるため注意が必要