Webhook ツール - Cartesia Docs

Webhook ツールは、エージェントをお客様のシステムに接続します。モデルが Webhook ツールを呼び出すと、Cartesia はお客様のエンドポイントに HTTP リクエストを送信し、そのレスポンスをモデルに返します。

Webhook ツールを定義する

このリクエストボディを POST /v1/agents/tools に送信して、Webhook ツールを作成します。外側のフィールドは、ツールとその実行設定を定義します。ネストされた api_schema は、LLM がツールを呼び出したときに Cartesia がお客様の API に送信する、別個のアウトバウンド HTTPS リクエストを記述します。api_schema には、method と url に加えて、お客様の API が必要とするパスパラメータ、クエリパラメータ、JSON ボディ、ヘッダー、認証を指定します。

POST /v1/agents/tools

{
  "type": "webhook",
  "name": "lookup_order",
  "description": "Looks up an order by its number. Use it when the caller asks about order status or delivery.",
  "pre_tool_speech": "auto",
  "execution_mode": "immediate",
  "response_timeout_secs": 20,
  "api_schema": {
    "url": "https://api.acme.com/orders/{order_id}",
    "method": "GET",
    "path_params_schema": {
      "order_id": {
        "type": "string",
        "description": "Order number provided by the caller."
      }
    },
    "request_headers": {
      "X-Tenant": "acme"
    },
    "authentication": {
      "mode": "bearer",
      "token": {
        "type": "secret",
        "secret_value": "sk_live_..."
      }
    }
  }
}

返されたツール ID を config.tools でアタッチします。共有の実行設定についてはツールを参照してください。

api_schema

api_schema.url は HTTPS を使用する必要があり、プライベートおよび内部ネットワーク範囲へのリクエストはブロックされます。api_schema.method は GET、POST、PUT、PATCH、DELETE をサポートします。

api_schema.path_params_schema は、api_schema.url 内の {order_id} のようなプレースホルダーを埋めます。api_schema.url 内のすべての {placeholder} には、大文字・小文字まで同じ名前のエントリが api_schema.path_params_schema に存在する必要があります。各パスパラメータは必須で、string、integer、number のいずれかです。
api_schema.query_params_schema は、properties とオプションの required リストでクエリパラメータを記述します。各プロパティ名はクエリ文字列のキーになります。これらの名前は api_schema.url 内のプレースホルダーには対応しません。
api_schema.request_body_schema は、POST、PUT、PATCH 用の JSON オブジェクトを記述します。ボディのプロパティはネストできます。

各パラメータがどのように値を取得するかを選択します：

値のソース	設定
モデル	`description` で何を提供すべきかを説明し、必要に応じて `enum` で値を制約する
固定値	テナント ID や API バージョンなどの `constant_value` を設定する
動的変数	`dynamic_variable` に変数の名前を設定する

パラメータの説明は、モデルにどの値を提供すべきかを伝えます。API バージョンなど、モデルに選択させるべきでない値には constant_value を使用します。顧客ごとのコンテキストや実行時に取得する値には dynamic_variable の値を使用します。たとえば、このツールはリクエストごとに現在の customer_id を送信します：

POST /v1/agents/tools

{
  "type": "webhook",
  "name": "track_order",
  "description": "Track an order using the caller's order number and customer account.",
  "pre_tool_speech": "auto",
  "execution_mode": "immediate",
  "api_schema": {
    "url": "https://api.example.com/orders/track",
    "method": "POST",
    "request_body_schema": {
      "type": "object",
      "properties": {
        "order_id": {
          "type": "string",
          "description": "Order number provided by the caller."
        },
        "customer_id": { "type": "string", "dynamic_variable": "customer_id" },
        "region": { "type": "string", "constant_value": "us-east" }
      },
      "required": ["order_id"]
    }
  }
}

動的変数は、オブジェクト内のフィールドを含め、string、number、boolean のフィールドを埋めることができます。オブジェクト全体、リスト、リスト内のフィールドを埋めることはできません。ツールとパラメータの説明でも動的変数を使用できます。たとえば、ツールの説明に Last known status: {{order_status}} を追加すると、モデルもその値を確認できるようになります。

ヘッダーと認証

api_schema.request_headers は、文字列、シークレット、動的変数を受け付けます。ツール ID と API 認証情報を使って、PATCH /v1/agents/tools/{tool_id} でヘッダーを追加します：

PATCH /v1/agents/tools/{tool_id}

{
  "api_schema": {
    "request_headers": {
      "X-Tenant": "acme",
      "X-Api-Key": {
        "type": "secret",
        "secret_value": "..."
      },
      "X-Customer-Id": {
        "type": "dynamic_variable",
        "name": "customer_id"
      }
    }
  }
}

authentication は、リクエスト時に Authorization ヘッダーへ認証情報を追加します。bearer は Authorization: Bearer <token> を送信し、basic_auth は Authorization: Basic <base64(username:password)> を送信します。request_headers に Authorization を重ねて設定しないでください。 API が保存済みのシークレット値を返すことはありません。ツールの更新時、省略したヘッダーと認証設定は変更されません。既存のシークレットフィールドを含める場合は、secret_value なしの { "type": "secret" } を使用すると、その値が維持されます。ヘッダーを削除するには、api_schema.request_headers 内でそのヘッダーを null に設定します。認証を削除するには、api_schema.authentication を null に設定します。 Cartesia は、自身が管理するトランスポートヘッダーを予約しています。ヘッダー名は、大文字・小文字に関係なく一意である必要があります。

レスポンスとタイムアウト

リクエストが成功（2xx）し、レスポンスボディがテキストの場合、そのボディが LLM に渡される結果になります。LLM が必要とするデータのみを返してください。Cartesia はボディを 4096 バイトに制限し、それより長い場合は [cut off: the response was longer than this tool returns] を追加します。 assignments を使うと、レスポンスフィールドを動的変数として保存できます。{"order": {"id": "A-1001", "status": "shipped"}} のようなレスポンスに対して、以下の代入（assignments）は注文 ID とステータスを保存します。プレイグラウンドのツールのサイドパネル、または PATCH /v1/agents/tools/{tool_id} で設定します：

PATCH /v1/agents/tools/{tool_id}

{
  "assignments": [
    { "dynamic_variable": "order_status", "value_path": "order.status" },
    { "dynamic_variable": "order_id", "value_path": "order.id" }
  ]
}

代入は、成功した JSON レスポンスの後に適用されます。リクエストの失敗、フィールドの欠落、null 値の場合、変数の以前の値はそのまま維持されます。オブジェクトとリストは JSON テキストとして保存されます。リクエストは response_timeout_secs の経過後にタイムアウトします（デフォルトは 20 秒）。リクエストがタイムアウトした場合、エンドポイントに到達できない場合、またはエンドポイントが 2xx 以外のステータスを返した場合、Cartesia は失敗内容を説明するエラー結果を LLM に渡し、会話は継続します。現在のターンをブロックする必要のないリクエストには、execution_mode: "async" を使用してください。

​Webhook ツールを定義する

​api_schema

​ヘッダーと認証

​レスポンスとタイムアウト

Webhook ツールを定義する

api_schema

ヘッダーと認証

レスポンスとタイムアウト