ツールの作成方法

このページで学べること

完全カスタムツールを使用してカスタマーエージェントをHTTPエンドポイントに接続する方法、カスタマーエージェントが実際に使用するツールの説明の書き方、スキルに追加する前にツールをテストする方法について説明します。

始める前に

必要なもの：

• カスタマーエージェントが有効
• 公開ホスト名経由で到達できるHTTPエンドポイントです。プライベートネットワークのアドレス、localhost、およびホスト名ではなくIPアドレスを使用するURLはサポートされていません。エンドポイントにAPIキーまたはトークンが必要な場合は、シークレットとして保存します（Steps 1 and 6を参照）。
• ツールを取り付ける先を指定できる、手順を編集可能なスキル

スキルに追加する前に、ツールを作成してテストできます。会話で使用するには、スキルの手順に追加してください。新しいスキルが必要な場合は、スキルを作成する方法をご覧ください。

完全にカスタムのツールとは

完全にカスタムのツールとは、会話中にカスタマーエージェントが実行できるHTTP リクエストです。カスタマーエージェントに付属のツールでは必要な内容をカバーできない場合に使用します。例えば、Shopify ではなく自社の注文管理システムで注文を検索する、カスタム倉庫システムで在庫を確認する、またはKlaviyo がネイティブに連携していないヘルプデスクでチケットを作成する場合などです。

基礎となる概念については、Understanding Toolsをご覧ください。

完全にカスタムなツールを作成するタイミング

完全にカスタムなツールを使うのは次の場合です：

• Klaviyo がまだ連携していないシステムからのリアルタイムデータが必要です
• 外部システムでカスタマーエージェントにアクションを実行させたい（独自システムでサブスクリプションをキャンセルする、チケットを作成する、レコードを更新するなど）
• 既存のツールが適していない — 例えば、注文に Shopify ではなくカスタム OMS を使用している場合

情報が頻繁に変わらず、すべてのお客様で同じである場合は、代わりにコンテンツとして追加してください。ツールは、お客様ごとの動的なデータとアクションのためのものです。

設定

1.カスタムツールページを開く

1. [カスタマーエージェント] > [コネクタ] に移動し、[カスタム]カードを開きます。
2. エンドポイントに認証情報が必要な場合は、Secretsに移動し、Add secretをクリックしてください。名前とシークレット値を入力し、シークレットを追加をクリックしてください。シークレットがすでに保存されている場合、またはエンドポイントでシークレットが不要な場合は、この手順をスキップしてください。
3. [ツールを作成]をクリックします。

2. ツールに名前を付けて説明します

• ツール名 — 「在庫を取得」や「返品チケットを作成」などの短い識別子です。
• 説明 — ツールの機能と使用すべきタイミングを自然言語で説明します。カスタマーエージェントはこの説明を読み、特定のリクエストに対してツールを使用するかどうかを判断します。具体的に記載してください。

適切な説明の例：

倉庫システムから、指定した商品 SKU のリアルタイム在庫数を取得します。購入者が特定の商品が在庫にあるかどうかを尋ねたときに使用します。

不明確な説明の例（避けてください）：

商品情報を取得します。

3. HTTP リクエストを設定する

• HTTPメソッド — GET、POST、PUT、DELETE、またはPATCH。
• URLテンプレート — エンドポイントURLの全体です。動的な値のプレースホルダーを含めることができます（手順5を参照してください）。
• ヘッダー — Content-Type や認証ヘッダーなど、エンドポイントで必要なすべてのヘッダー。
• クエリパラメーター — エンドポイントでクエリ文字列内の値が必要な場合は、ここにそれらの名前と値を入力してください。値にはプレースホルダーを使用できます（ステップ5を参照してください）。

4. リクエストボディ（POST、PUT、PATCH の場合）を設定します

本文テンプレートで、JSONオブジェクトを指定してください。実行時にカスタマーエージェントが入力する必要がある値にはプレースホルダーを使用してください。

本文の例：

{
  "customer_id": "{{profile_id}}",
  "sku": "{{product_sku}}"
}

5. 動的な値の変数を定義する

各プレースホルダーには、変数の下に一致する変数が必要です。上記の本文例について：

1. 変数を追加をクリックし、変数名としてprofile_idを入力します。ソースをKlaviyoプロファイルに設定し、KlaviyoプロパティをKlaviyo IDに設定します。これにより、認証済みの購入者のKlaviyoプロファイルIDが提供されます。
2. product_skuという名前の変数をもう1つ追加します。ソースを動的変数に設定し、タイプとして文字列を選択して、説明にカスタマーエージェントが提供すべきSKUを記載します。エンドポイントで必要な場合は、必須を選択します。

エンドポイントで必要となるorder_idなど、他の値についても同様に繰り返してください。変数名はプレースホルダーと完全に一致している必要があります。conversation_idという名前の変数には、現在の会話IDは自動的には入力されません。

URL、ヘッダー、クエリパラメーター、または本文で、{{profile_id}}や{{product_sku}}などの変数をプレースホルダーとして使用します。Klaviyoプロファイル変数を使用するツールには認証済みの購入者が必要です。必須のプロファイル値が欠落していると、リクエストは実行されません。

6. 認証

エンドポイントにAPIキー、ベアラートークン、またはその他の認証情報が必要な場合は、シークレットとして保存してください。シークレットは暗号化され、その値がカスタマーエージェントに表示されることはなく、保存後は再度表示できません。

1. ツール内の Variables の下で、Add variables をクリックします。変数に名前（例：api_key）を付け、Source を Secret に設定して、保存したシークレットを選択します。
2. エンドポイントが認証情報を想定している場所（ヘッダー、URL、クエリパラメーター、または本文）で、その変数を参照してください。例えば、名前がAuthorizationで値がBearer {{api_key}}のヘッダーを追加してください。

キーをローテーションするには、シークレットの行メニューを開き、更新をクリックして置き換え値を入力し、次に更新をクリックします。シークレットを使用するすべてのツールで新しい値が反映されます。使用中列には、各シークレットを参照しているツールが表示されるため、削除する前に確認してください。

7. ツールを保存してテストする

保存する前に、設定のタイムアウト（秒）と最大再試行回数を確認してください。一時的な障害に備えて、全体の制限時間を1–10秒、再試行回数を0–3回に設定できます。ツールがデータを変更する場合は、エンドポイントが繰り返しのリクエストを安全に処理できることを確認してください。

ツールを作成するには保存をクリックしてください。保存したツールは、テストセクションから開きます。

テストではエンドポイントに実際のリクエストが送信され、データが変更される可能性があります。テスト用プロファイルとテストレコードを使用してください。保存してテストを実行では、ライブスキルですでに使用されているツールを含め、ツールに加えた編集内容も保存されます。

テストで、動的変数にサンプル値を入力します。ツールでKlaviyoプロファイル変数を使用している場合は、プロファイルでテスト用プロファイルを選択します。保存してテストを実行をクリックします。

応答を確認し、次の点をチェックしてください：

• レスポンスが正常に返されます
• このレスポンスには、スキルが必要とするデータが含まれています
• 想定されるエラーケースでは、有用なステータスコードとメッセージが返されます。

8. ツールをスキルにアタッチする

1. [カスタマーエージェント] > [スキル]に移動し、ツールを使用するスキルを開きます。手順が読み取り専用の場合は、完全にカスタムのスキルを作成します。
2. How to respondで、ツールを使用する場所に/を入力し、メニューからツールを選択してください。呼び出すタイミング、指定する値、および結果またはエラーの処理方法を説明してください。
3. 手順の準備ができたら、スキルが下書きの場合は公開をクリックし、スキルが公開中の場合は更新をクリックしてください。

適切なツール説明を作成する

明確な説明があると、カスタマーエージェントはいつツールを使用するか判断しやすくなります。スキルの手順は、呼び出すツールと、結果の使用方法も決定します。良い説明：

• ツールが何をするものかを 1 文で説明してください
• いつ使うかを 1 文で述べてください。
• 返されるデータまたは実行されるアクションが具体的である

説明が不適切な場合、あいまい（“顧客情報を取得”）であったり、範囲が広すぎる（“注文に関連するあらゆることを処理”）であったり、ツールが何をするかではなくカスタマーエージェントがどう振る舞うべきかを伝えていたりします。

セキュリティに関する考慮事項

• 認証情報をシークレットとして保存します。APIキーやトークンは、ヘッダー、URL、または本文に直接貼り付けないでください。シークレットとして追加し、シークレット変数で参照します（ステップ6を参照）。
• 可能な場合はIP許可リストを使用してください。エンドポイントは引き続きパブリックホスト名経由で到達可能である必要があります。プライベートネットワークのアドレスとlocalhostはブロックされます。認証に加えて、保護の追加レイヤーとして許可リストを使用してください。
• 送信するデータに注意してください。リクエスト設定と変数ソースによって、どの値がエンドポイントに送信されるかが決まります。スキルの手順は、動的変数に対してカスタマーエージェントが提供する値の指針となります。エンドポイントが受信するフィールドを確認します。
• レート制限。エンドポイントにレート制限がある場合は、想定される会話量を処理できるように十分高いことを確認してください。

トラブルシューティング

問題：カスタマーエージェントがツールをまったく使用しません。
考えられる原因： 説明があいまいすぎるか、そのツールがスキルの公開済み手順に含まれていません。
修正方法： 使用すべきタイミングが具体的に伝わるように説明を書き直してください。対応方法で、/を使用してツールを挿入し、いつ呼び出すべきかを説明してください。手順を適用するには、公開または更新をクリックしてください。

症状：テスト中にツールがエラーを返します。
考えられる原因：URLが誤っている、本文の形式が不正である、必須のプロファイルデータが不足している、またはエンドポイントが受け付けないペイロードである可能性があります。
修正：テストで、リクエストのプレビューとレスポンスを確認してください。URL、ヘッダー、本文が、エンドポイントで想定される入力と一致していることを確認してください。ツールでKlaviyoプロファイル変数を使用している場合は、必要な値を含むテストプロファイルを選択してください。

問題：カスタマーエージェントがツールを使用しているが、誤ったパラメーターを渡しています。
考えられる原因： 変数のソースまたはプロファイルプロパティが誤っている、またはスキルの手順で渡す内容が不明確である。
修正： 変数の下で、変数名、ソース、選択したプロファイルプロパティを確認します。変数の説明とスキルの手順を更新し、提供すべき内容を明確にします。

症状：ツールが遅く、応答が遅延します。
考えられる原因：エンドポイントのレイテンシー。
修正：エンドポイントを最適化します。自社側で結果をキャッシュできるか確認してください。

FAQ

1つのツールを複数のスキルで使用できますか？
はい。作成後、ツールは複数のスキルで使用できます。各スキルの編集可能な手順に挿入し、各スキルを公開または更新してください。

サポートされている認証方法は何ですか？
ベアラートークンやAPIキーヘッダーなど、リクエストとともに静的な認証情報を送信する方法であれば、どれでも使用できます。認証情報はシークレットとして保存し、Secret変数で参照してください（手順6を参照）。OAuthなど、リクエスト時にトークンの取得または更新が必要なフローは、完全にカスタムのツールではサポートされません。

エンドポイントがダウンしている、またはエラーを返す場合はどうなりますか？
Klaviyoはツールの障害をカスタマーエージェントに報告します。一時的な障害は、ツールのタイムアウトおよび再試行制限の範囲内で再試行できます。スキルの指示では、ツールがリクエストを完了できない場合の対応（例：引き継ぎを提案する）について説明してください。信頼できるエンドポイントを使用し、ツールの動作を注意深く監視してください。

作成後にツールを編集できますか？
はい。カスタマーエージェント > コネクタ > カスタムからツールを開き、名前、説明、またはリクエスト設定を編集してから、保存をクリックします。各スキルの手順でツールを追加または削除します。

ツールにバージョンを付けられますか？
現時点では、バージョン管理はまだサポートされていません。保存した変更は、それを参照しているすべてのスキルで使用される共有ツールに適用されます。保存してテストを実行では変更も保存されるため、編集する前に、どのライブスキルがそのツールを使用しているかを確認してください。

その他のリソース