エージェント設定

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

{
  "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 を使って、エージェントの役割、話し方、目的、制約を定義します。短い構成にすると、プロンプトのレビューと保守が容易になります：

# 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}} のような動的変数を受け付けます。エージェントの指示は、モデルが応答するたびに最新の値を使用します。ウェルカムメッセージは、通話開始時に利用可能な値を使用します。値が更新されても、会話内の以前のメッセージが書き換えられることはありません。テスト通話用のサンプルを保存するには、プレイグラウンドの 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 を参照してください。

言語

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

オーディオ入力

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

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

オーディオ出力

フィールド	説明
`voice_id`	エージェントの発話に使用する音声。必須。
`speed`	`0.6` から `1.5` までの発話速度。`null` は音声のデフォルトを使用します。
`volume`	`0.5` から `2` までの発話音量。`null` はデフォルトを使用します。
`emotion`	選択した音声がサポートする感情。利用可能な値は API リファレンスを参照してください。
`pronunciation_dictionary_id`	エージェントの発話時に使用する発音辞書。
`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 トーンの送信、電話番号への転送）を有効にします。各種類の仕組みと設定方法についてはツールを参照してください。

バージョン

エージェントの設定を挙動に影響する形で変更すると、Cartesia は完全な設定スナップショットをバージョンとして保存します。新しい通話は最新バージョンを使用し、進行中の通話は開始時のバージョンを使い続けます。新しい設定を保存するには、API またはプレイグラウンドから公開してください。プレイグラウンドの「Preview」ボタンでボイスエージェントを実行しても、公開はされません。

バージョンの内容

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

{
  "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 は、バージョンを新しい順に一覧表示します。GET /v1/agents/{agent_id}/versions/{version_id} は、完全な設定を含む単一のバージョンを返します。

バージョンを復元する

バージョンを復元するには、そのバージョンの config を読み取り、PATCH /v1/agents/{agent_id} で送信します。これにより、履歴を書き換えるのではなく、新しいバージョンが作成されます。 Cartesia は設定を再度検証します。その後削除されたリソースを参照している場合は、復元する前にその参照を置き換えてください。

参照されるリソース

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

​指示とあいさつ

​タイムゾーン

​モデル

​言語

​オーディオ入力

​オーディオ出力

​ターン設定

​ツール

​バージョン

​バージョンの内容

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

​バージョンを復元する

​参照されるリソース