> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cartesia.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook ツール

> エージェントがお客様のサーバー上の HTTPS エンドポイントを呼び出せるようにします。

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

## Webhook ツールを定義する

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

```json POST /v1/agents/tools theme={null}
{
  "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` でアタッチします。共有の実行設定については[ツール](/ja-jp/agents/tools#execution-settings)を参照してください。

<div id="request-schema" />

## 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` に[変数の名前](/ja-jp/agents/dynamic-variables)を設定する |

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

たとえば、このツールはリクエストごとに現在の `customer_id` を送信します：

```json POST /v1/agents/tools theme={null}
{
  "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}`](/ja-jp/api-reference/agents/tools/update) でヘッダーを追加します：

```json PATCH /v1/agents/tools/{tool_id} theme={null}
{
  "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}`](/ja-jp/api-reference/agents/tools/update) で設定します：

```json PATCH /v1/agents/tools/{tool_id} theme={null}
{
  "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"` を使用してください。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.