この記事を見て、私が以前に試したときはうまくいかなかったのに上手いことできるんだ……と驚愕したので、あえて失敗談を共有します。
ただ、実際うまくいかなかったので正解が分からないのと、正直うろ覚えなので、正確ではないかもしれません。またそもそもこうした宣言チックな外部連携はあまり経験がなく、勘所もわかってません。書いたことだけがダメな原因ではないかも。また時間のある時にトライして追記するかもしれません。
Swagger の定義が長すぎる
Copilot StudioのカスタムコネクタはOAS 2.0（Swagger）形式のみ受け付けます。
そのため、次のkintoneのAPIドキュメントをベースに、Swagger形式のYAMLを作成します。ゼロから書くのは手間がかかるため、LLMを活用しました。
以下に参考としてYAMLの例を示します。
記事ではここでレコード取得の API のみを定義していますが、以前私は すべての API を網羅した Swagger 定義 を作成して読み込ませようとしました。
結果、定義のサイズが大きすぎてコネクタの登録ができず。機能を削ってレコード操作のみに限定したところ、コネクタの宣言はできました。
ただ、そもそも Outlook や Sharepoint などのコネクタが操作ごとに分かれている (ex. 予定を登録する / 1件の予定を取得する / 予定を検索する etc…) ので、この記事のように取得 / 登録 / 編集 / 削除みたいに操作ごとにコネクタを用意するほうがよかったのかもしれません。管理が大変ですが。
OpenAPI 2.0 の制約
当時は Copilot を使って kintone REST API の OpenAPI 定義を生成したのですが、何も指示しないとバージョンが 2.0 ではなく 3 系 (?) で生成されてしまいました。
要するに Copilot のコネクタとして登録できるのは OpenAPI 2.0 なのに、そのバージョンでは対応してない機能を使って記述されてしまい、構文エラーと認識されてしまいました。
特にフィールドやフォームのプロパティなどは定義を 名前参照 かつ内部で 再帰参照 するところが厄介で、結構そういう箇所があって修正に苦労しました。
あと、確かドメインの指定も 2.0 と後続バージョンでプロパティ名が違って、それでうまくいかなかったのも覚えています……。
複数ドメイン対応はできないと思う
Swagger 定義の中にこんな感じの記述を含めると、エージェントを作成するときにドメインを指定できるみたいです。
x-ms-parameterized-host:
hostTemplate: '{subdomain}.cybozu.com'
useSchemePrefix: true
parameters:
- name: subdomain
description: 'kintone サブドメイン（例: mycompany → mycompany.cybozu.com）'
required: true
x-ms-summary: kintone サブドメイン
x-ms-url-encoding: single
in: path
type: string
ただ OAuth2 の設定をパラメータにすることが可能かどうかが分かってない です。もしかしたら同じようにパラメータにできる構文があるのかもしれませんが、ちょっと調べ切れてません。
で、気づいたら私は ホストは可変なのに OAuth2 は特定ドメイン専用 とかいう意味不明なコネクタが爆誕させてました。つまり正しいドメインを指定しないと動かない。悲しい。
ナレッジを作らなかった / コネクタ側の説明文が不十分だったかも
とりあえず検証しようと先走って、コネクタを作って動かしてみらそれっぽく通信はできた。
けど何かを検索させたりするのはまったくもってできなくて、特に検索用のクエリの生成や戻り値の解読が全然できませんでした。
今回記事を見て ナレッジを作成する というところが根本的に足りてないことに気づきました。確かにこれがあれば AI 側で迷わず行けるのかも。
走り書きにはなりますが、もし試してみようと思われた方がいらっしゃったら、ご参考程度に。