カスタマーエージェントAPI（ベータ版）

このページで学べること

カスタマーエージェントAPIとは何か、各エンドポイントグループが何をするか、そして呼び出しを開始する方法についてご案内します。APIを使用すると、カスタマーエージェントを設定し、本番環境での動作を読み取り、HTTP経由で、Klaviyo 他の公開APIと並行してプログラムから実行できます。

注意：カスタマーエージェントAPIはベータ版です。エンドポイントとスキーマは、一般提供前に変更される場合があります。ベータ版 API は本番環境での使用を想定していません。詳細については、Klaviyo のバージョニングおよび廃止ポリシーをご覧ください。

API でできること

カスタマーエージェントのAPIは、次の4つの作業をカバーしています。

1. エージェントを設定 — エージェント自体に加え、そのスキル、ツール、ナレッジソース、シークレットを読み取り、または更新します。
2. 本番環境の会話を読む — カスタマーエージェントの会話を一覧表示して確認します。
3. パフォーマンスをレポート — ボリューム、解決率、スキル別のメトリックを取得します。
4. エージェントを 1 ターン実行 — 会話の 1 ターンを送信し、エージェントからの応答を取得します。これはヘッドレス プリミティブです。独自のサーフェスにエージェントを埋め込む場合に便利です。

これら 4 つのジョブはすべて 1 つの API の背後にあるため、継続的なトレーニング ループに組み込むことができます。発生した内容を取得し、うまくいったこととうまくいかなかったことを診断したうえで、設定変更を戻して適用します。Claude や ChatGPT などの AI アシスタントに API キーを渡すと、代わりにループをエンドツーエンドで実行できます。会話を読み取り、失敗のパターンを見つけ、スキル、ツール、ナレッジ、ガイダンスに対する変更を提案（または適用）します。

認証とアクセス

カスタマーエージェントAPIの呼び出しには、KlaviyoのプライベートAPIキーを使用します。Klaviyoの[設定] > [API キー]でキーを生成し、agentsスコープを付与します。

キーを作成するときに、agents スコープのアクセスレベルを選択します：

外部連携でエージェントを観察するだけでよい場合は、読み取り専用を選択します（例：レポート作成用ダッシュボード）。エージェントを設定したり会話のターンを実行したりする必要がある場合は、読み取り/書き込みを選択します。

すべてのリクエストには、ベータ版リビジョン ヘッダーも含める必要があります：

revision: 2026-07-15.pre

ベータ版改訂ヘッダーがない場合、リクエストは拒否されます。

レート制限

すべてのエンドポイントは同じ上限を共有します：

• バースト：10 リクエスト/秒
• 安定：150 リクエスト/分

リクエスト形式

すべてのエンドポイントは、Klaviyo の API の他の箇所で使用されている JSON:API 規約に従っています：

• コンテンツタイプ: application/vnd.api+json
• page[cursor] と page[size] によるページネーション（デフォルト 50、最大 100、前方のみ）
• フィルタリングと並べ替えは、Klaviyo の標準フィルタ構文に従います。

エンドポイント グループ

エージェント

各企業に１つのカスタマーエージェントとなります。エージェントはシングルトンです。URL内のIDは認証トークンから解決されます。

エージェント スキル

エージェントツール

エージェントのナレッジ

ナレッジソースには 3 種類あり、作成時に source_type により設定されます：snippet、webpage、または file。

エージェント シークレット

カスタムツールで使用される暗号化されたシークレット。リストのエンドポイントは安全なメタデータのみを返します。シークレット値自体は返されません。

会話

エージェントが購入者と交わした会話を読む。会話はチケットの形になっており、1 つの会話は長期間にわたり多数のメッセージにまたがる場合があります。

レポート

要求元の企業にスコープされた集計メトリック。どちらのレポートも POST エンドポイントです。レポート パラメータは本文で渡します。

エージェントを実行する

これは、カスタマーエージェントを独自のサーフェス（アプリ、ヘルプセンター、パートナーが構築したサポートパネル）に埋め込むためのプリミティブです。

引き続き Klaviyo UI が必要なもの

一部の設定手順は、まだ API にはありません。

• チャネル設定（ウェブチャット、メール、SMS、WhatsApp）— チャネルのセットアップは Klaviyo プラットフォーム設定にあります。
• 各チャネルで公開する — チャネルごとのオン/オフ スイッチは UI に残ります。
• ヘルプデスク選択 — エスカレーションを受けるヘルプデスクは、エージェント側ではなくヘルプデスク外部連携のセットアップで設定します。

一般的なワークフロー

1 回設定すれば、その後はメンテナンスするだけ

1. Klaviyo で agents スコープの プライベート API キーを作成します。
2. 現在の状態を取得 — エージェントとスキル/ツール/ナレッジ リストを GET します。
3. 変更を加える — 必要に応じてスキル、ツール、ナレッジ、シークレットを作成または更新します。
4. 本番環境を確認 — 最近の会話を一覧表示し、値レポートを取得して、エージェントのパフォーマンスを確認します。
5. 反復します。

ループでエージェントをトレーニングします。

API は、本番環境でエージェントが行ったことと、その設定内容を結び付けるために設計されています。一般的なループ：

1. 最近の会話を取得 — created_at と status でフィルタリングされた会話を GET します。それぞれからメッセージを取得します。
2. 診断 — 各会話について、成功か失敗かを分類します。パターンを探してください：エスカレーションが特定のトピックに集中していますか？不要なはずのスキルがルーティングされていますか？担当者に必要なナレッジが不足していますか？
3. メトリックを取得 — ボリュームと解決率の値レポートに加え、スキル別内訳のためのスキル値レポート。集計全体でパターンが維持されていることを確認します。
4. 変更案 — 失敗パターンに基づいて、何を変更するかを決定します。スキルの手順を編集する、ナレッジスニペットを追加する、新しいカスタムツールを作成する、トーンルールを厳格化する、エスカレーショントリガーを追加する。
5. 変更を適用 — 影響を受けるスキルに PATCH を適用し、新しいナレッジ ソースを POST するなど。
6. Loop.次の会話ウィンドウに対して繰り返します。

AI 支援による運用に非常に適しています。API キーと概要を Claude、ChatGPT、または Cursor に渡し、会話を取得して不足箇所を見つけ、具体的な編集案を提案し、（承認後に）適用させます。これらのエンドポイントが MCP やコーディング エージェントに適した形（JSON:API、予測可能なリソース パス、完全な CRUD）になっているのは意図的です。

独自のサーフェスにエージェントを埋め込む

1. agents スコープ（読み取り/書き込み）で キーを作成 します。
2. UI で会話を開く — 購入者の入力を収集します。
3. ターンを実行 — /api/customer-agent-responses に POST し、買い物客の入力と会話コンテキスト（ある場合）を渡します。
4. surface で応答をレンダリングしてください。
5. 会話の各ターンで繰り返します。

FAQ

MCP サーバーはありますか？

このベータでは対象外です。API は REST 専用です。

これは構築の基盤として十分に安定していますか？

ベータ版であることは、スキーマが変更される可能性があることを意味します。エンドポイントは完全に呼び出し可能ですが、長期的な安定性についてはまだ確約していません。ベータ リビジョンに対して本番環境で重要な外部連携を構築してリリースしないでください。

完全なスキーマはどこで確認できますか？

完全なリファレンスは、https://developers.klaviyo.com/en/reference/ のKlaviyo開発者ポータルにあります。カスタマーエージェントのエンドポイントは、現在のリビジョン（2026-07-15.pre）のベータ API に表示されます。

関連記事