> ## 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.

# 動的変数

> 顧客データやツールから得た値で、各通話をパーソナライズします。

動的変数を使うと、マネージドエージェントが通話中に顧客の詳細情報やその他の値を利用できます。エージェントのテキストで変数を使うには、変数名を二重波かっこで囲んで記述します。たとえば、エージェントの[ウェルカムメッセージ](/ja-jp/agents/configuration#instructions-and-greeting)を次のように設定します：

```text theme={null}
Hi {{customer_name}}, how can I help you today?
```

`customer_name` として `Jordan` を渡すと、エージェントは「Hi Jordan, how can I help you today?」と話します。

カスタム値は、通話リクエストまたは Webhook ツールのレスポンスから供給されます。`{{system__caller_id}}` などのシステム変数は、Cartesia が自動的に提供します。

<Accordion title="値を挿入できる場所">
  | 場所 | 方法 |
  | - | - |
  | 指示プロンプト、ウェルカムメッセージ、keyterms、ツールとパラメータの説明、転送条件 | テキスト内に `{{variable_name}}` と記述する |
  | [電話転送の宛先](/ja-jp/agents/system-tools#transfer-to-number) | 電話番号の代わりに `{{variable_name}}` を使用する |
  | [Webhook のパス・クエリ・ボディパラメータ](/ja-jp/agents/webhook-tools#request-schema)と[ヘッダー](/ja-jp/agents/webhook-tools#headers-and-authentication) | 波かっこなしの変数名を使い、値のソースとして動的変数を設定する |
</Accordion>

名前は大文字と小文字を区別します。英字、数字、アンダースコアを使用できますが、数字で始めることはできません。

## 値の供給元

### 自分で渡す値

[アウトバウンド通話リクエスト](/ja-jp/api-reference/agents/calls/create-outbound-call)で `dynamic_variables` を渡します。上記のウェルカムメッセージを設定したエージェントを、お客様自身の電話番号 ID と宛先とともに使用します：

```json POST /agents/calls theme={null}
{
  "agent_id": "agent_Fo7pKNBUwLZxrTd6jvhpaE",
  "from_number_id": "ap_Q8PRh7lXyZsawXJmN2KcT5",
  "outbound_calls": [{
    "to_number": "+14155550123",
    "dynamic_variables": {
      "customer_name": "Jordan"
    }
  }]
}
```

[バッチ通話](/ja-jp/api-reference/agents/call-batches/create-call-batch)では、各受信者の `dynamic_variables` に値を入れます。[WebSocket セッション](/ja-jp/api-reference/agents/agent-websocket)では、お客様のサーバーから送信する `session_create` に含めます。

値には、テキスト、数値、true/false の値を使用できます。

### システム変数

Cartesia は通話コンテキストを自動的に提供します。たとえば、`system__caller_id` には発信者の電話番号が、`system__time` には現在の現地時刻が入ります：

```text theme={null}
The local time is {{system__time}}. Use it when discussing opening hours.
```

エージェントのタイムゾーンは、プレイグラウンドの **Settings** で選択します。デフォルトは UTC です。

<Accordion title="利用可能なシステム変数">
  | 変数 | 値 |
  | - | - |
  | `system__caller_id` | 発信側の電話番号 |
  | `system__called_number` | 着信側の電話番号 |
  | `system__call_direction` | 電話通話の場合は `inbound` または `outbound` |
  | `system__conversation_id` | Cartesia の通話 ID |
  | `system__agent_id` | エージェント ID |
  | `system__agent_version_id` | 通話に使用されたエージェントのバージョン |
  | `system__time` | エージェントのタイムゾーンでの現在時刻 |
  | `system__time_utc` | 現在の UTC 時刻。例：`2026-09-07T15:30:00Z` |
  | `system__timezone` | エージェントのタイムゾーン |

  電話番号と通話方向は、ブラウザでのプレビューを含め、利用できない場合は空になります。時刻の値は通話中に更新されます。
</Accordion>

### ツールのレスポンス

Webhook ツールは、レスポンスに含まれる値を保存して、通話の残りの間使用できます。**代入（assignment）** を追加して、どのレスポンスフィールドを保存し、どの変数を更新するかを選択します。

注文検索が次を返すとします：

```json theme={null}
{
  "order": { "id": "A-1001", "status": "shipped" }
}
```

プレイグラウンドで Webhook ツールを開き、次の代入を追加します：

| 変数名 | レスポンスパス |
| - | - |
| `order_id` | `order.id` |
| `order_status` | `order.status` |

検索が成功すると、指示とツールの説明の中で `{{order_status}}` が `shipped` になります。他の Webhook ツールは、`order_id` を[パラメータ値](/ja-jp/agents/webhook-tools#request-schema)として使用できます。

インバウンド通話では、「Thanks for calling. How can I help?」のように、発信者が誰か分かる前でも機能するウェルカムメッセージから始めてください。[検索ツール](/ja-jp/agents/webhook-tools#request-schema)で、電話番号のパラメータに `system__caller_id` を使用するよう設定し、返された顧客情報を保存する代入を追加します。いつ検索ツールを呼び出すかをエージェントに指示してください。これらの情報が利用可能になるのはツールの完了後であり、ウェルカムメッセージの前ではありません。

## プレイグラウンドで試す

1. ウェルカムメッセージに `Hi {{customer_name}}, how can I help?` を追加します。`{{` と `}}` の間に変数名を入力すると、エディターがカスタム変数とシステム変数を提案します。
2. **Variables** を開き、`customer_name` のサンプル値を `Jordan` に設定します。
3. **Preview** をクリックして、これらのサンプル値でテスト通話を開始します。

サンプルはテスト通話専用です。本番の通話でサンプルが使われることはありません。サンプルは [`config.dynamic_variable_placeholders`](/ja-jp/api-reference/agents/update) からも保存できます。

## 重要な挙動

* ウェルカムメッセージで使用するカスタム変数は、通話の開始前に利用可能である必要があります。
* Webhook や電話転送が必要とする値が欠落しているか無効な場合、エージェントはツールエラーを受け取ります。リクエストや転送は行われません。
* 空のテキスト、`0`、`false` は、供給済みの値として扱われます。

代入が更新するのは現在の通話の値のみです。エージェントの保存済み設定を変更したり、次の通話に値を供給したりすることはありません。

プレイグラウンドで **Calls** を開いて通話を選択すると、最終的な変数の値と代入を確認できます。これらは [Get call](/ja-jp/api-reference/agents/calls/get-call) からも取得できます。


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