ツール（ベータ）の作成方法

ベータ版の機能ゼロから完全にカスタムのツールを作成する機能はオープンベータとして提供されており、すべてのカスタマーエージェントアカウントでご利用いただけます。登録は不要です。カスタマーエージェントで [ツール] ページを確認できます。この機能は現在も拡張中であり、変更される可能性があります。

このページで学べること

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

始める前に

必要なもの：

• カスタマーエージェントが有効
• カスタマーエージェントに呼び出してほしい HTTP エンドポイント — 現時点でアクセスにシークレット認証情報（API キー、ベアラートークンなど）を必要としないもの（認証済みエンドポイントは近日対応予定です。下記の警告をご覧ください）
• ツールをアタッチするスキル。カスタマーエージェントに付属するスキル、または作成した完全カスタムスキルのいずれかです。

まだスキルを設定していない場合は、まず作成してください。ツールは単体では何もしないため、スキルに関連付ける必要があります。

警告: API キーやその他のシークレットの安全な保管は近日提供予定です。提供されるまで、API キー、ベアラー トークン、またはその他の機密性の高い認証情報を完全にカスタム ツールに入れないでください。ツール設定は、まだそれらを安全に保管できる場所ではありません。現時点では、シークレット認証なしでも安全に呼び出せるエンドポイント（例: IP 許可リストの背後にある内部エンドポイント、または機密性のない識別子を受け付けるエンドポイント）のツールのみを使用してください。認証済みエンドポイントのサポートも近日提供予定です。

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

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

基礎となる概念については、「カスタマーエージェントのツール解説」の記事をご覧ください。

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

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

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

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

設定

1. ツールページを開きます

[カスタマーエージェント] > [ツール] に移動し、[ツールを作成] をクリックします。

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

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

適切な説明の例：

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

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

商品情報を取得します。

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

• メソッド — GET、POST、PUT、DELETE、または PATCH。
• URL — エンドポイント URL の完全な値。動的な値のプレースホルダーを含めることができます（手順 5 を参照）。
• ヘッダー — Content-Type や認証ヘッダーなど、エンドポイントで必要なすべてのヘッダー。

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

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

本文の例：

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

5. 動的な値にはプレースホルダーを使用する

カスタマーエージェントは、プレースホルダーを使用して実行時に値を入力できます。一般的なプレースホルダー：

• {{profile_id}} — 会話内の顧客の Klaviyo プロファイル ID
• {{conversation_id}} — 現在の会話 ID
• 入力スキーマで定義する任意のパラメーター（例：{{product_sku}}、{{order_id}}）

プレースホルダーは URL、ヘッダー、本文で使用できます。

6. 認証

認証済みエンドポイントのサポートは近日提供予定です。それまでは、API キー、ベアラー トークン、その他のシークレットを完全なカスタムツールに入れないでください。シークレット認証情報なしで安全に呼び出せるエンドポイントのみを使用してください。たとえば、IP 許可リストで保護された内部エンドポイント、または機密性のない識別子を受け付ける公開エンドポイントです。

安全なシークレット ストレージは近日提供予定で、認証済みエンドポイントが利用可能になります。

7. ツールをテストする

[テストツール] をクリックします。任意の入力パラメータにサンプル値を指定します。次を確認してください：

• レスポンスが正常に返されます
• レスポンス形式はカスタマーエージェントが想定するものです。
• エラーケースはすべて処理されます

8. 保存してスキルに添付します。

[保存] をクリックします。カスタマーエージェントに実際にツールを使用させるには、使用するスキルを開き、そこでツールを追加します。

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

説明は最も重要なフィールドです。カスタマーエージェントは、名前ではなく説明に基づいて使用するツールを完全に選択します。良い説明：

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

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

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

• シークレット認証情報が必要なエンドポイントには、まだ完全にカスタムツールを使用しないでください。認証が必要なエンドポイントのサポートは近日中に提供予定です。提供されるまでは、シークレット認証なしで呼び出しても安全なエンドポイントのみを使用してください。
• 可能な場合は IP の許可リストを使用してください。エンドポイントが内部用の場合は、シークレットに依存するのではなく、Klaviyo の IP 範囲にアクセスを制限してください。
• 送信するデータに注意してください。カスタマーエージェントは、スキルの指示内容に基づいて顧客データをツールに渡します。エンドポイントが受信するフィールドを確認します。
• レート制限。エンドポイントにレート制限がある場合は、想定される会話量を処理できるように十分高いことを確認してください。

トラブルシューティング

問題：カスタマーエージェントがツールをまったく使用しません。
考えられる原因： 説明があいまいすぎるか、そのツールを使用するスキルにツールが関連付けられていません。
修正方法： 使用すべきタイミングが具体的に伝わるように説明を書き直してください。ツールがスキルのツールリストに表示されていることを確認します。

症状： テスト中にツールがエラーを返します。
考えられる原因： URL が誤っている、本文の形式が正しくない、またはエンドポイントが受け付けないペイロードである。
修正： テストツールの機能を使用して、生のリクエストとレスポンスを確認します。エンドポイントで想定される入力に対して、URL と本文の形式を確認してください。

問題：カスタマーエージェントがツールを使用しているが、誤ったパラメーターを渡しています。
考えられる原因： プレースホルダー名がスキーマと一致しない、またはスキルの手順で渡す内容が不明確である。
修正方法： プレースホルダー名が完全に一致していることを確認してください。スキルの手順を更新し、ツールを使用するタイミングと提供するパラメータを明確にしてください。

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

FAQ

1 つのツールを複数のスキルで使用できますか？
はい。作成後、ツールは任意の数のスキルにアタッチできます。

サポートされている認証方法は何ですか？
認証済みエンドポイントのサポートは近日提供予定です。現時点では、シークレット認証情報を必要としないエンドポイントを使用してください（IP 許可リストを使用する内部エンドポイント、または機密性のない識別子を使用する公開エンドポイント）。

エンドポイントがダウンしている、またはエラーを返す場合はどうなりますか？
完全にカスタムのツール向けのエラー処理は、まだ実装されていません。エンドポイントで障害が発生した場合、カスタマーエージェントは品質が低下した、または分かりにくい応答を生成する可能性があります。エラー処理が提供されるまでは、信頼できるエンドポイントのみを使用し、ツールの動作を注意深く監視してください。

作成後にツールを編集できますか？
はい。名前、説明、構成、および関連付けられているスキルは、いつでも編集できます。

ツールをバージョン管理できますか？
バージョン管理はまだサポートされていません。ツールの編集は、それを使用するすべてのスキルに対して直ちに反映されます。

その他のリソース