Custom Actionの利用
このチャプターのゴール
- Custom Actionの概要と利用方法が理解できている
- JavaScriptを使用して独自の機能を実装する方法が理解できている
※本チャプターでは、JavaScriptプログラミングの基礎知識が必要になります。
Custom Actionとは?
Custom Actionとは、miiboのエージェントに独自の機能を追加するための仕組みです。JavaScriptを使用して実装した機能を、Webhookと連携させることで、エージェントの応答をカスタマイズしたり、様々なActionを実装することができます。

Custom Actionを利用することで、以下のような機能を実現できます:
- 外部APIとの連携による情報取得や更新
- データの加工や変換処理
- 独自のビジネスロジックの実装
- 複雑な条件分岐や計算処理
Custom Actionは「外部サービス連携」の一覧からご利用いただけます。

miibo JSについて
Custom ActionのJavaScriptコードは「miibo JS」という独自の実行環境で動作します。miibo JSは特殊な実行環境のため、一般的なJavaScript環境とは異なる制約や仕様があります。
具体的なコーディング規約やルール、制約事項については、後続の「miibo JSの実装」チャプターをご参照ください。
https://miibo.readme.io/docs/miibo-js%E3%81%AE%E5%AE%9F%E8%A3%85-1
そちらでmiibo JS特有の実行環境や、推奨される実装パターンについて詳しく解説しています。
Custom Actionの構成要素
Custom Actionは以下の要素で構成されています:
-
基本情報
- 名前(必須)
- 説明
- サムネイルURL
-
miibo JSコード(必須)
- 処理内容をJavaScriptで記述
- 処理結果は戻り値として返却
-
入力パラメータ(Input Parameters)
- 名前
- データ型(String、Number、Boolean、Object)
- デフォルト値
- 必須/任意の指定
- 説明
-
環境変数
- キー
- 値
- シークレット指定(機密情報の場合)
コードの実装例
const result = {
success: false,
error: null
};
try {
// 外部API呼び出しの例
const response = fetch('https://api.example.com/data', {
method: 'POST',
headers: {
'Authorization': `Bearer ${env.API_TOKEN}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
param: input.value
})
});
if (response.status !== 200) {
throw new Error(`API request failed: HTTP ${response.status}`);
}
result.success = true;
} catch (err) {
result.error = err.message;
}
return result;
変数とパラメータの参照方法
-
入力パラメータの参照
input.パラメータ名
の形式で参照- 例:
input.value
、input.userId
-
環境変数の参照
env.変数名
の形式で参照- 例:
env.API_TOKEN
、env.SECRET_KEY
特殊関数
GoogleのサービスアカウントからAccessTokenを取得する
Google Cloud Platforの提供するサービスアカウントのJsonを利用し、認証を行うことができます。
環境変数にJSONの値を登録し、下記のように呼び出すことでtokenを取得できます。
const tokenInfo = getGoogleAccessToken(env.GOOGLE_APPLICATION_CREDENTIALS_JSON);
下記はBigQueryのAPIを呼び出す例です。
try {
// サービスアカウントJSONからGoogle OAuth2トークンを取得
const tokenInfo = getGoogleAccessToken(env.GOOGLE_APPLICATION_CREDENTIALS_JSON);
// BigQuery APIへのリクエスト
const response = fetch(`${env.BIGQUERY_API_URL}/projects/${env.BIGQUERY_PROJECT_ID}/queries`, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': `Bearer ${tokenInfo.access_token}`
},
body: JSON.stringify({
query: input.query,
useLegacySql: false
})
});
if (response.status !== 200) {
throw new Error(`BigQuery API request failed: ${response.status}`);
}
result.success = true;
result.messages = ['Query executed successfully', response.body];
} catch (err) {
result.error = err.message;
}
Webhookとの連携
Custom ActionはWebhook機能と連携することで、以下のようなケースで利用できます:
- ユーザーの発話をトリガーとした実行
- エージェントの応答をトリガーとした実行
- Function Callingによる条件付き実行
Webhook連携の設定手順
- Webhooks画面でWebhookを新規作成
- 連携タイプで「Custom Actionと連携」を選択
- 使用するCustom Actionを選択
- パラメータの設定
- トリガー条件の設定
テンプレートの利用
Custom Actionには、一般的な用途向けにテンプレートが用意されています。テンプレートを利用することで、基本的な機能をすぐに実装できます。

テンプレートの種類
各テンプレートには以下の情報が含まれています:
- テンプレート名
- 機能の説明
- サンプルコード
- 必要な環境変数の定義
- 入力パラメータの定義
テンプレートの利用手順
-
テンプレート選択画面の表示
- Custom Action一覧画面で「テンプレートを利用する」ボタンをクリック
- 利用可能なテンプレート一覧が表示されます
-
テンプレートの選択
- テンプレートの説明を確認
- 目的の機能に合ったテンプレートの「インポート」ボタンをクリック
-
環境変数の設定
- テンプレートで定義された環境変数の入力画面が表示されます
- 必須の環境変数を入力(例:API KEY、エンドポイントURLなど)
- シークレット情報は「シークレット」としてマークされます
-
カスタマイズと保存
- テンプレートのコードをニーズに合わせて修正
- 必要に応じて入力パラメータを追加・変更
- 名前や説明を編集
- 「保存」ボタンをクリックして完了
テンプレート利用のベストプラクティス
-
環境変数の管理
- APIキーなどの認証情報は必ずシークレットとして設定
- 環境変数の名前は用途が分かりやすいものに変更可能
-
コードのカスタマイズ
- テンプレートコードは自由にカスタマイズ可能
- 必要な機能の追加や不要な機能の削除を検討
- コメントを適切に追加して可読性を向上
-
テスト
- カスタマイズ後は動作確認を実施
- Webhook連携での動作も確認
-
ドキュメント
- カスタマイズした内容を説明に反映
- パラメータの説明を明確に記載
セキュリティと注意点
-
APIキーの管理
- APIキーは適切に管理し、漏洩に注意
- 必要に応じて定期的に再発行
-
環境変数の管理
- 機密情報はシークレットとして設定
- 本番環境の認証情報は慎重に管理
-
エラーハンドリング
- try-catchによる適切なエラー処理
- エラーメッセージの適切な返却
-
リソース使用
- 実行時間は適切な範囲に収める
- メモリ使用量に注意
トラブルシューティング
-
コードが動作しない場合
- シンタックスエラーがないか確認
- 環境変数が正しく設定されているか確認
- 実行環境の制限事項に抵触していないか確認
- Curlを利用してエラーが起きていないかを確認
-
Webhook連携で期待通りに動作しない場合
- トリガー条件が適切か確認
- パラメータが正しく設定されているか確認
- エラーレスポンスを確認
-
外部API連携で問題が発生する場合
- API認証情報が正しいか確認
- ネットワーク接続に問題がないか確認
- ログ画面でAPIのレスポンスステータスを確認

重要な注意事項
外部APIの利用について
- 各種サービスのAPIキーやトークンの取得方法は、それぞれのサービスの公式ドキュメントをご確認ください
- APIの利用制限や料金体系は各サービスによって異なります
- 新しいAPIを利用する際は、該当サービスの最新のドキュメントを必ず確認してください
- 各APIの利用規約を必ず確認し、遵守してください
コードの管理とメンテナンスについて
- Custom Actionで実装したコードは、実装者の責任の下でメンテナンスしてください
- 外部APIの仕様変更やアップデートへの対応は適宜必要です
- 実装したコードのバグ修正や機能改善は自己責任で行ってください
- 重要なコードは別途バックアップを取ることを推奨します
セキュリティ上の注意点
- APIキーなどの認証情報は適切に管理し、第三者に漏洩しないよう注意してください
- 認証情報が漏洩した場合は、速やかに該当サービスで無効化・再発行などの対応を行ってください
- 個人情報や機密情報を扱う場合は、各種法令やガイドラインに従って適切に処理してください
Updated about 2 hours ago