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

# エージェント設定

> エージェントがどのように振る舞い、聞き、話し、行動するかを設定します。

エージェントの `config` は、その挙動、モデル、オーディオ、ツールを制御します。[エージェントの作成](/ja-jp/api-reference/agents/create)時に設定します。変更するには、更新したいフィールドのみを [`PATCH /v1/agents/{agent_id}`](/ja-jp/api-reference/agents/update) で送信します。

<Frame caption="プレイグラウンドでの同じ設定：指示、ウェルカムメッセージ、音声、LLM。">
  <img src="https://mintcdn.com/cartesia-2650f86a/wJ-UNaUxIYqQcebi/assets/images/agents/playground-configure.png?fit=max&auto=format&n=wJ-UNaUxIYqQcebi&q=85&s=f10eb51915951d857cec45275a19203a" alt="指示、ウェルカムメッセージ、音声、LLM の設定を表示するプレイグラウンドのエージェント設定ページ" width="2000" height="1017" data-path="assets/images/agents/playground-configure.png" />
</Frame>

```json theme={null}
{
  "name": "Acme Support",
  "config": {
    "instructions": "You are Acme's support agent. Help callers with orders and returns. Be warm and concise.",
    "initial_message": "Hi, thanks for calling Acme. How can I help?",
    "timezone": "America/Los_Angeles",
    "model": { "id": "gpt-5.4-mini" },
    "language": { "primary": "en" },
    "audio": {
      "input": {
        "noise_suppression": "auto",
        "keyterms": ["Acme", "ProGrip"]
      },
      "output": {
        "voice_id": "e07c00bc-4134-4eae-9ea4-1a55fb45746b",
        "speed": 1.0
      }
    },
    "turn": {
      "inactivity_end_call_secs": 240,
      "inactivity_check_in_secs": 8
    },
    "tools": [{ "id": "agent_tool_5RkP2wZmQ8xTnLc4vB7dHy" }],
    "system_tools": {
      "end_call": {
        "description": null,
        "pre_tool_speech": "force"
      }
    }
  }
}
```

## 指示とあいさつ

`instructions` を使って、エージェントの役割、話し方、目的、制約を定義します。短い構成にすると、プロンプトのレビューと保守が容易になります：

```text theme={null}
# Identity and personality
You are Acme's friendly and concise support agent.

# Speaking rules
Use short sentences. Ask one question at a time.

# Objectives
Help callers check orders and start returns.

# Guardrails
Never invent order details. Ask for an order number before using the lookup tool.
```

`initial_message` は、通話開始時にエージェントが話す内容です。`null` に設定すると、発信者が先に話すのを待ちます。

どちらのフィールドも、`{{customer_name}}` のような[動的変数](/ja-jp/agents/dynamic-variables)を受け付けます。エージェントの指示は、モデルが応答するたびに最新の値を使用します。ウェルカムメッセージは、通話開始時に利用可能な値を使用します。値が更新されても、会話内の以前のメッセージが書き換えられることはありません。

テスト通話用のサンプルを保存するには、プレイグラウンドの **Variables** を使用するか、API から `config.dynamic_variable_placeholders` を設定します。本番の通話で保存されたサンプルが使われることはありません。

## タイムゾーン

`config.timezone` に `America/Los_Angeles` のような IANA タイムゾーンを設定して、`{{system__time}}` を制御します。デフォルトは `UTC` です。プレイグラウンドでは、**Settings** でタイムゾーンを選択します。

## モデル

`model.id` は、エージェントの応答を生成する LLM を選択します。`model.temperature` と `model.max_output_tokens` は出力を調整します。利用可能なモデルと設定については [LLM](/ja-jp/agents/models) を参照してください。

## 言語

`language.primary` は、音声認識、エージェントの応答、音声合成に使用する言語を設定します。`en`、`es`、`de` などのサポートされている ISO 639-1 コードを使用してください。

## オーディオ入力

* `noise_suppression` は、入力音声のクリーンアップを制御します。ほとんどの通話には `auto` を、騒がしい環境には `max` を、無効にするには `off` を使用します。
* `keyterms` は、Ink が名前やドメイン固有のフレーズを認識するのに役立ちます。[keyterms による文字起こしの改善](/ja-jp/use-the-api/stt/keyterms)を参照してください。keyterms は認識に影響し、発音辞書はエージェントが単語をどう発話するかを変更します。

keyterms 内の動的変数は、起動時に利用可能な値を使用します。その後の代入（assignments）で更新されることはありません。

## オーディオ出力

| フィールド | 説明 |
| - | - |
| `voice_id` | エージェントの発話に使用する音声。必須。 |
| `speed` | `0.6` から `1.5` までの発話速度。`null` は音声のデフォルトを使用します。 |
| `volume` | `0.5` から `2` までの発話音量。`null` はデフォルトを使用します。 |
| `emotion` | 選択した音声がサポートする感情。利用可能な値は [API リファレンス](/ja-jp/api-reference/tts/bytes)を参照してください。 |
| `pronunciation_dictionary_id` | エージェントの発話時に使用する[発音辞書](/ja-jp/api-reference/pronunciation-dicts/create)。 |
| `background_sound` | `file_id` と `0` から `2` までの音量を持つ環境音。`null` で無効になります。 |

## ターン設定

以下のフィールドを `config.turn` の下に設定します：

* `inactivity_end_call_secs`：エージェントが別れのメッセージを話して通話を終了するまでの無応答時間（秒）。`20` から `240` の範囲で、デフォルトは `240` です。`null` にはできません。
* `inactivity_check_in_secs`：エージェントが声かけを行うまでの無応答時間（秒）。`5` から `60` の範囲で、デフォルトは `8` です。`null` に設定すると声かけを無効にできます。有効にする場合は、`inactivity_end_call_secs` より小さい値にする必要があります。

## ツール

`tools` は、エージェントが呼び出せる共有の Webhook ツールとクライアントツールを ID で列挙します。`system_tools` は組み込みアクション（通話の終了、DTMF トーンの送信、電話番号への転送）を有効にします。各種類の仕組みと設定方法については[ツール](/ja-jp/agents/tools)を参照してください。

## バージョン

エージェントの設定を挙動に影響する形で変更すると、Cartesia は完全な設定スナップショットをバージョンとして保存します。新しい通話は最新バージョンを使用し、進行中の通話は開始時のバージョンを使い続けます。

新しい設定を保存するには、API またはプレイグラウンドから公開してください。プレイグラウンドの「Preview」ボタンでボイスエージェントを実行しても、公開はされません。

### バージョンの内容

バージョンには、完全な設定スナップショットと作成メタデータが含まれます：

```jsonc theme={null}
{
  "id": "av_7Hq2mXbK9cLdNfPzR3tWvE",
  "description": "Updated the model",
  "created_at": "2026-08-14T12:34:56.789Z",
  "created_by": "user_123",
  "config": { /* complete agent configuration */ }
}
```

新しいバージョンにラベルを付けるには、エージェント更新時に `version_description` を設定します。バージョンレコードは、このラベルを `description` として返します。エージェント名の変更など、メタデータのみの更新ではバージョンは作成されず、その場合 `version_description` は指定できません。

### バージョン履歴を閲覧する

[`GET /v1/agents/{agent_id}/versions`](/ja-jp/api-reference/agents/versions/list) は、バージョンを新しい順に一覧表示します。[`GET /v1/agents/{agent_id}/versions/{version_id}`](/ja-jp/api-reference/agents/versions/get) は、完全な設定を含む単一のバージョンを返します。

### バージョンを復元する

バージョンを復元するには、そのバージョンの `config` を読み取り、[`PATCH /v1/agents/{agent_id}`](/ja-jp/api-reference/agents/update) で送信します。これにより、履歴を書き換えるのではなく、新しいバージョンが作成されます。

Cartesia は設定を再度検証します。その後削除されたリソースを参照している場合は、復元する前にその参照を置き換えてください。

### 参照されるリソース

バージョンには、ツールと音声の ID が保存され、それらのリソースのコピーは保存されません。ツールを編集すると、それを参照するすべてのエージェントに影響しますが、エージェントバージョンは作成されません。以前のバージョンの挙動を変えないようにするには、新しいツールを作成してアタッチしてください。


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