Line SDK からの移行

Line SDK でコードファーストのカスタムエージェントを構築している場合、エージェントのプロンプト、モデル、音声、そしてツールの多くには Managed Agents に直接対応するものがあります。変わるのは、カスタムコードをデプロイする代わりに、UI または API でこれらを設定するという点です。このガイドでは、各要素の対応関係を説明します。

Cartesia は 2026年12月1日 に Line SDK エージェントのホスティングを終了します。対象は、Python としてデプロイするコードファーストのエージェントです。Line エージェントはその日まで動作し続けるため、マネージド版を構築してテストし、準備ができたタイミングでトラフィックを切り替えられます。

以前に Playground でエージェントを構築していた場合（カスタムコードをデプロイしていない場合）、そのエージェントはすでに移行済みで、ここで説明する新機能すべてに自動的にアクセスできるはずです。

引き継がれるもの

電話番号。 現在の番号をそのまま保持し、マネージドエージェントに割り当てられます。
料金。 音声エージェントの分単価は変わりません。
通話履歴。 録音とトランスクリプトはそのまま残り、GET /agents/calls/{call_id} がこれまでどおり返します。
API。 Calls、バッチ発信、電話番号、メトリクスはマネージドエージェントに対して動作します。

新しくなったこと

Line エージェントは、ユーザー自身のプロバイダーキーで動作していました。Managed Agents ではキーは不要です。LLM カタログからモデルを選ぶと Cartesia がそのモデルを実行し、トークン使用量をそのまま請求します。維持すべきプロバイダーアカウントも、モデルプロバイダーからの別請求もありません。

期間限定（2026年10月1日まで）で、LLM の使用は無料です。

提供予定

ナレッジベース。 通話中にエージェントが参照できるドキュメントの添付。
エージェントごとの複数言語対応。 現在、エージェントは単一の language.primary のみを受け付けます。
通話イベント Webhook。 通話のライフサイクルイベントをお使いのエンドポイントに配信。

これらのいずれかが移行の妨げになる場合や、ここに記載されていない機能が必要な場合は、support@cartesia.ai までお知らせください。

セルフホスト型エージェントコード

セルフホスト型のエージェントコードは、12月1日以降も動作し続けます。移行が必要なのは Cartesia がホストするエージェントのみです。エージェントサーバーを自分で運用し、その URL を Cartesia に指定している場合は、何も変わりません。 Line SDK は GitHub でオープンソースとして公開されており、セルフホスト型エージェントで動作するため、現在のコードをそのまま使い続けられます。自前のサーバーでのホスティングについては、support@cartesia.ai までご相談ください。エージェントに self_hosted_deployment_url を設定します：

curl -X PATCH https://api.cartesia.ai/agents/$AGENT_ID \
  -H "X-API-Key: $CARTESIA_API_KEY" \
  -H "Cartesia-Version: 2026-08-14" \
  -H "Content-Type: application/json" \
  -d '{ "self_hosted_deployment_url": "https://my-agent.example.com" }'

cartesia connect --agent-id $AGENT_ID --url https://my-agent.example.com

エージェントとコードの接続を解除するには、self_hosted_deployment_url に null を送信するか、cartesia disconnect を実行します。

移行の手順

マネージドエージェントを構築する

まず小さなエージェントから始めて、機能を1つずつ追加していきましょう。基本的な Line エージェントは次のとおりです：

main.py

import os
from line.llm_agent import LlmAgent, LlmConfig, end_call
from line.voice_agent_app import VoiceAgentApp

async def get_agent(env, call_request):
    return LlmAgent(
        model="anthropic/claude-haiku-4-5-20251001",
        api_key=os.getenv("ANTHROPIC_API_KEY"),
        tools=[end_call],
        config=LlmConfig(
            system_prompt="You are Acme's support agent.",
            introduction="Hi, thanks for calling Acme. How can I help?",
        ),
    )

app = VoiceAgentApp(get_agent=get_agent)

同じエージェントを設定として表すと次のようになります：

curl -X POST https://api.cartesia.ai/v1/agents \
  -H "X-API-Key: $CARTESIA_API_KEY" \
  -H "Cartesia-Version: 2026-08-14" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Support",
    "config": {
      "instructions": "You are Acme'\''s support agent.",
      "initial_message": "Hi, thanks for calling Acme. How can I help?",
      "model": { "id": "claude-haiku-4.5" },
      "audio": {
        "output": { "voice_id": "e07c00bc-4134-4eae-9ea4-1a55fb45746b" }
      },
      "system_tools": { "end_call": {} }
    }
  }'

このガイドの以降の設定例は、PATCH /v1/agents/{agent_id} のリクエストボディです。変更するフィールドだけを送信してください。それ以外の設定はそのまま維持されます。

設定の対応表

プロンプトとモデル

Line SDK	Managed Agents
`LlmConfig.system_prompt`	`config.instructions`
`LlmConfig.introduction`	`config.initial_message`
`LlmAgent(model=..., api_key=...)`	`config.model.id`（LLM カタログから選択）
`LlmConfig.temperature`	`config.model.temperature`
`LlmConfig.max_tokens`	`config.model.max_output_tokens`

音声とオーディオ

Line SDK	Managed Agents
`PreCallResult` `tts.voice_id`	`config.audio.output.voice_id`
`PreCallResult` `tts.pronunciation_dict_id`	`config.audio.output.pronunciation_dictionary_id`
`PreCallResult` `tts.language`、`stt.language`	`config.language.primary`
ノイズ抑制レベル	`config.audio.input.noise_suppression`
背景音	`config.audio.output.background_sound`

ツール

Line SDK	Managed Agents
`http_server_tool`	Webhook ツール
`end_call`	`config.system_tools.end_call`
`transfer_call`	`config.system_tools.transfer_to_number`
`send_dtmf`	`config.system_tools.send_dtmf`
`AgentSendCustom` などのアプリ内アクション	クライアントツール
`is_background=True`	`execution_mode: "async"`
`timeout`	`response_timeout_secs`

Managed Agents は、agent_as_handoff や @handoff_tool による Line SDK のエージェント間ハンドオフをまだサポートしていません。これらのハンドオフは同じ会話を別の Line SDK エージェントにルーティングするものです。一方、transfer_to_number は代わりに設定済みの電話番号へ電話をかけます。ほとんどのフローは単一のマネージドエージェントで実現できます。エージェント間ハンドオフが必要な場合は、Line SDK エージェントをセルフホストのまま維持できます。ユースケースをより深く理解したいので、私たちまでご連絡ください。 エージェントの実行 cartesia deploy、cartesia deployments ls、cartesia env set は、ホストされている Line SDK コードとそのデプロイメントを管理するものであり、Managed Agent の設定は管理しません。右列は Managed Agents での置き換え先を示しています。

Line SDK	Managed Agents
`cartesia deploy`	設定変更でバージョンが公開される
`cartesia deployments ls`	`GET /v1/agents/{agent_id}/versions`
`cartesia env set`	シークレットは使用するツール側に保存
`wss://api.cartesia.ai/agents/stream/{agent_id}`	`wss://api.cartesia.ai/v1/agents/websocket/{agent_id}`

プロンプト、モデル、あいさつ

LLM は、自分のプロバイダーキーではなく Cartesia のカタログから利用します。Claude Haiku 4.5 は claude-haiku-4.5 で利用できるようになりました。API キーを指定する必要はなくなり、Cartesia が通話ごとにモデル使用量を請求します。GET /v1/agents/models は、利用可能な ID をレイテンシと料金とともに一覧表示します。

{
  "config": {
    "instructions": "You are Acme's support agent.",
    "initial_message": null,
    "model": { "id": "claude-haiku-4.5", "temperature": 0.3 }
  }
}

音声とオーディオ

Line では、pre_call_handler で設定済みの TTS 音声を上書きできました。マネージドエージェントでは、これは設定の一部になります：

{
  "config": {
    "language": { "primary": "en" },
    "audio": {
      "input": { "noise_suppression": "auto", "keyterms": ["Acme", "ProGrip"] },
      "output": {
        "voice_id": "e07c00bc-4134-4eae-9ea4-1a55fb45746b",
        "speed": 1.0,
        "pronunciation_dictionary_id": "your-dict-id"
      }
    }
  }
}

language.primary は音声認識と音声合成の両方をカバーし、個別の tts.language と stt.language の設定を置き換えます。keyterms、speed、volume、emotion は新しい設定です。全項目についてはエージェントの設定を参照してください。

ツール

Webhook ツール

http_server_tool は Webhook ツールになります。Cartesia が HTTPS エンドポイントを呼び出し、レスポンスをエージェントに返します。バックエンドサービス、サードパーティ API、あるいは HTTPS で到達できる任意のサーバーエンドポイントに向けられます。

from line.llm_agent import http_server_tool

get_order_status = http_server_tool(
    name="get_order_status",
    description="Looks up the current status of an order. Use it whenever the caller asks where an order is.",
    url="https://api.acme.com/orders/{order_id}",
    method="GET",
    path_params_schema={
        "order_id": {"type": "string", "description": "The order number the caller provides."},
    },
    auth={"X-Api-Key": "${ACME_API_KEY}"},
    timeout=5.0,
)

同じツールを Managed Agents で表すと次のようになります：

curl -X POST https://api.cartesia.ai/v1/agents/tools \
  -H "X-API-Key: $CARTESIA_API_KEY" \
  -H "Cartesia-Version: 2026-08-14" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "webhook",
    "name": "get_order_status",
    "description": "Looks up the current status of an order. Use it whenever the caller asks where an order is.",
    "pre_tool_speech": "auto",
    "execution_mode": "immediate",
    "response_timeout_secs": 5,
    "api_schema": {
      "url": "https://api.acme.com/orders/{order_id}",
      "method": "GET",
      "path_params_schema": {
        "order_id": { "type": "string", "description": "The order number the caller provides." }
      },
      "request_headers": {
        "X-Api-Key": { "type": "secret", "secret_value": "sk_live_..." }
      }
    }
  }'

フィールドごとの対応は次のとおりです：

`http_server_tool`	Webhook ツール
`url`、`method`	`api_schema.url`、`api_schema.method`
`path_params_schema`	`api_schema.path_params_schema`
`query_params_schema`	`api_schema.query_params_schema`
`request_body_schema`	`api_schema.request_body_schema`
`headers`	`api_schema.request_headers`
`auth={"X-Api-Key": "${VAR}"}`	保存済みシークレットを使った `api_schema.request_headers`
`timeout`	`response_timeout_secs`（1〜120 の整数秒）
`is_background=True`	`execution_mode: "async"`
`constant_value`	`constant_value`

認証情報は cartesia env set からツール側へ移ります。Cartesia は各認証情報をシークレットとして保存し、シークレット値は書き込み専用のため、読み取り時には値ではなくプレースホルダーが返されます。標準的なベアラートークンやベーシック認証には、ヘッダーではなく api_schema.authentication を設定してください。更新と削除についてはヘッダーと認証を参照してください。

組み込みツール

Line の組み込みツールはシステムツールになります。インポートするコードではなく、設定上のフィールドです。

from line.llm_agent import end_call, send_dtmf, transfer_call

tools = [
    end_call(
        description="Ends the call. Use it once the order is confirmed and the customer says goodbye."
    ),
    send_dtmf,
    transfer_call,
]

Managed Agents では次のようになります：

{
  "config": {
    "system_tools": {
      "end_call": {
        "description": "Ends the call. Use it once the order is confirmed and the customer says goodbye.",
        "pre_tool_speech": "force"
      },
      "send_dtmf": {},
      "transfer_to_number": {
        "transfers": [
          {
            "destination": { "type": "phone", "phone_number": "+18005551234" },
            "condition": "The caller asks to speak with a person."
          }
        ]
      }
    }
  }
}

各ツールで利用できる設定についてはシステムツールを参照してください。

クライアントツール

Line では、エージェントはパススルーツールからカスタムイベントを yield（生成）することでアプリ側に働きかけていました：

from typing import Annotated
from line.events import AgentSendCustom
from line.llm_agent import passthrough_tool

@passthrough_tool
async def open_cart(ctx, cart_id: Annotated[str, "Cart to open"]):
    """Opens the shopping cart. Use it when the user wants to review or check out their cart."""
    yield AgentSendCustom(metadata={"action": "open_cart", "cart_id": cart_id})

これはクライアントツールになり、同じ POST /v1/agents/tools エンドポイントで作成します：

{
  "type": "client",
  "name": "open_cart",
  "description": "Opens the shopping cart. Use it when the user wants to review or check out their cart.",
  "pre_tool_speech": "auto",
  "execution_mode": "async",
  "expects_response": false,
  "parameters": {
    "type": "object",
    "properties": {
      "cart_id": { "type": "string", "description": "Cart to open." }
    },
    "required": ["cart_id"]
  }
}

エージェントがツールを使用すると、Cartesia は WebSocket 経由で client_tool_call を送信し、アプリがカートを開きます：

ws.onmessage = (message) => {
  const event = JSON.parse(message.data);
  if (event.type !== "client_tool_call") return;

  if (event.tool_name === "open_cart") {
    openCart(event.parameters.cart_id);
  }
};

この例では expects_response が false なので、何も返しません。エージェントが結果を必要とする場合は true に設定し、client_tool_result で応答してください。

ツールをエージェントにアタッチする

Webhook ツールやクライアントツールを作成しただけでは、どこにもアタッチされません。ツールの ID をエージェントの config.tools に追加します。このリストは更新のたびに全体が置き換えられます：

{
  "config": {
    "tools": [
      { "id": "agent_tool_5RkP2wZmQ8xTnLc4vB7dHy" },
      { "id": "agent_tool_9dK3xQm7VbNs2PfR4tLwZa" }
    ]
  }
}

システムツールは別枠で、config.system_tools に設定します。

デプロイメントに代わるバージョン

ビルドやデプロイは不要です。すべての設定変更は検証され、不変のバージョンとして保存され、即座に新しい通話に適用されます。進行中の通話は、開始時のバージョンのまま最後まで実行されます。ロールバックするには、古いバージョンの config を読み取り、PATCH で送信します。これにより、履歴を書き換えるのではなく、ロールバックが新しいバージョンとして記録されます。

クライアントを接続する

エージェント WebSocket は /v1/agents/websocket/{agent_id} に移動しました。認証は変わりません。サーバーからは X-API-Key、ブラウザからは /access-token エンドポイントの agent グラントによる短期トークンを使用します。

旧 API	Managed Agents
`start`	`session_create`
`ack`	`session_ready`
`media_input`	`audio_input`
`media_output`	`audio_output`
`clear`	`audio_output_clear`
`dtmf`	`dtmf_input`
`turn_started`、`turn_output_text_delta`、`turn_ended`	同じ名前、フラットなフィールド

const ws = new WebSocket(
  `wss://api.cartesia.ai/v1/agents/websocket/${agentId}` +
    `?cartesia_version=2026-08-14&access_token=${accessToken}`
);

ws.onopen = () => {
  ws.send(JSON.stringify({
    type: "session_create",
    audio: { input_format: "pcm_44100" },
  }));
};

ws.onmessage = (msg) => {
  const data = JSON.parse(msg.data);
  if (data.type === "audio_output") playAudio(atob(data.audio));
  if (data.type === "audio_output_clear") stopPlayback();
};

クライアントで確認すべき点は2つです：

stream_id は廃止されました。 1つの接続が1つの通話に対応します。
ターンのフィールド名が変更されました。 was_interrupted は interrupted に、start_timestamp と end_timestamp は start_time と end_time に、id は turn になりました。

WebSocket API にすべてのイベントが詳しく記載されています。

構築した内容をお聞かせください

Line エージェントが Managed Agents に相当機能のないカスタムロジックを実行している場合は、support@cartesia.ai 宛てに、構築した内容をお知らせください。移植をお手伝いします。

​引き継がれるもの

​新しくなったこと

​提供予定

​セルフホスト型エージェントコード

​移行の手順

​マネージドエージェントを構築する

​設定の対応表

​プロンプト、モデル、あいさつ

​音声とオーディオ

​ツール

​Webhook ツール

​組み込みツール

​クライアントツール

​ツールをエージェントにアタッチする

​デプロイメントに代わるバージョン

​クライアントを接続する

​構築した内容をお聞かせください

引き継がれるもの

新しくなったこと

提供予定

セルフホスト型エージェントコード

移行の手順

マネージドエージェントを構築する

設定の対応表

プロンプト、モデル、あいさつ

音声とオーディオ

ツール

Webhook ツール

組み込みツール

クライアントツール

ツールをエージェントにアタッチする

デプロイメントに代わるバージョン

クライアントを接続する

構築した内容をお聞かせください