config は、その挙動、モデル、オーディオ、ツールを制御します。エージェントの作成時または更新時に設定します。
プレイグラウンドの Configuration ページ。
プレイグラウンドの Advanced ページ。
指示とあいさつ
instructions を使って、エージェントの役割、話し方、目的、制約を定義します。短い構成にすると、プロンプトのレビューと保守が容易になります：
initial_message は、通話開始時にエージェントが話す内容です。null に設定すると、発信者が先に話すのを待ちます。
どちらのフィールドも、{{customer_name}} のような動的変数を受け付けます。エージェントの指示は、モデルが応答するたびに最新の値を使用します。ウェルカムメッセージは、通話開始時に利用可能な値を使用します。値が更新されても、会話内の以前のメッセージが書き換えられることはありません。
プレビュー通話用のサンプル値を設定するには、プレイグラウンドのヘッダーにある Vars をクリックするか、API から config.dynamic_variable_placeholders を設定します。本番の通話で保存されたサンプルが使われることはありません。
タイムゾーン
config.timezone に America/Los_Angeles のような IANA タイムゾーンを設定して、{{system__time}} を制御します。デフォルトは UTC です。プレイグラウンドでは、Advanced ページの Time zone で設定します。
モデル
model.id は、エージェントの応答を生成する LLM を選択します。model.temperature と model.max_output_tokens は出力を調整します。利用可能なモデルと設定については マネージド LLM を参照してください。
言語
language.primary は、各通話の開始時の言語を設定します。en などのサポートされている言語またはロケールを使用してください。地域のアクセントを使う場合は en-GB のように指定します。
language.additional を設定すると、発信者の求めに応じて、エージェントが設定済みの言語間で切り替えられるようになります。設定しない場合、通話はプライマリ言語のまま進みます。
言語ごとに別の音声を使用するには、language.presets を使用します。
オーディオ入力
noise_suppressionは、入力音声のクリーンアップを制御します。ほとんどの通話にはautoを、騒がしい環境にはmaxを、無効にするにはoffを使用します。keytermsは、Ink が名前やドメイン固有のフレーズを認識するのに役立ちます。keyterms による文字起こしの改善を参照してください。keyterms は認識に影響し、発音辞書はエージェントが単語をどう発話するかを変更します。
オーディオ出力
ターン設定
以下のフィールドをconfig.turn の下に設定します：
inactivity_end_call_secs：エージェントが別れのメッセージを話して通話を終了するまでの無応答時間（秒）。20から240の範囲で、デフォルトは240です。nullにはできません。inactivity_check_in_secs：エージェントが声かけを行うまでの無応答時間（秒）。5から60の範囲で、デフォルトは8です。nullに設定すると声かけを無効にできます。有効にする場合は、inactivity_end_call_secsより小さい値にする必要があります。
投機的生成
応答レイテンシーを下げるには、config.speculative_generation を有効にします。有効にすると、音声認識モデルが発信者の発話終了を予測して早期ターン終了イベントを送出した時点で、LLM が応答の生成を開始します。エージェントは、ターンの終了をモデルが確定するまで発話もツールの実行も行いません。発信者が再び話し始めた場合、エージェントは投機的な応答をキャンセルします。破棄された応答も LLM トークンを消費するため、この設定を有効にすると LLM のコストが増える可能性があります。
この設定は、新しいエージェントではデフォルトで true です。無効にするには、AGENT_ID と CARTESIA_API_KEY を設定してから、エージェントを更新します：
true に設定します。更新時にこのフィールドを省略すると、エージェントの現在の設定が維持されます。
ツール
tools は、エージェントが呼び出せる共有の Webhook ツールとクライアントツールを ID で列挙します。system_tools は組み込みアクション（通話の終了、DTMF トーンの送信、ターンのスキップ、留守番電話の検出、電話番号または SIP URI への通話転送）を有効にします。各種類の仕組みと設定方法についてはツールを参照してください。
バージョン
エージェントの設定を挙動に影響する形で変更すると、Cartesia は完全な設定スナップショットをバージョンとして保存します。新しい通話は最新バージョンを使用し、進行中の通話は開始時のバージョンを使い続けます。 API による更新は、成功した時点で反映されます。プレイグラウンドでは、Publish をクリックするまで編集内容は下書きのまま保持され、Publish をクリックすると各変更点が一覧表示されて確認できます。Preview はブラウザで下書きを実行しますが、速度、発音辞書、無音タイムアウト、タイムゾーンは公開後に反映されます。電話通話では常に公開済みのバージョンが使用されます。
Publish では、反映前に各変更点が一覧表示されます。
バージョンの内容
バージョンには、完全な設定スナップショットと作成メタデータが含まれます：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 は設定を再度検証します。削除されたリソースや現在は提供されていないモデルを参照している場合は、復元する前にその参照を置き換えてください。