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

# Line SDK からの移行

> Line SDK エージェントを機能ごとに Managed Agents へ移行します。

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

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

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

## 引き継がれるもの

* **電話番号。** 現在の番号をそのまま保持し、マネージドエージェントに[割り当て](/ja-jp/line/integrations/telephony/phone-numbers#assigning-an-inbound-agent)られます。
* **料金。** 音声エージェントの分単価は変わりません。
* **通話履歴。** 録音とトランスクリプトはそのまま残り、[`GET /agents/calls/{call_id}`](/ja-jp/api-reference/agents/calls/get-call) がこれまでどおり返します。
* **API。** [Calls](/ja-jp/api-reference/agents/calls/create-outbound-call)、[バッチ発信](/ja-jp/api-reference/agents/call-batches/create-call-batch)、[電話番号](/ja-jp/api-reference/agents/phone-numbers/list)、[メトリクス](/ja-jp/line/evaluations/metrics)はマネージドエージェントに対して動作します。

## 新しくなったこと

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

<Tip icon="gift">
  **期間限定（2026年10月1日まで）で、LLM の使用は無料です。**
</Tip>

## 提供予定

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

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

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

セルフホスト型のエージェントコードは、12月1日以降も動作し続けます。移行が必要なのは Cartesia がホストするエージェントのみです。エージェントサーバーを自分で運用し、その URL を Cartesia に指定している場合は、何も変わりません。

Line SDK は [GitHub でオープンソース](https://github.com/cartesia-ai/line)として公開されており、セルフホスト型エージェントで動作するため、現在のコードをそのまま使い続けられます。自前のサーバーでのホスティングについては、[support@cartesia.ai](mailto:support@cartesia.ai) までご相談ください。

エージェントに [`self_hosted_deployment_url`](/ja-jp/api-reference/agents/agents/update#body-self-hosted-deployment-url-one-of-0) を設定します：

<CodeGroup>
  ```bash cURL theme={null}
  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" }'
  ```

  ```bash CLI theme={null}
  cartesia connect --agent-id $AGENT_ID --url https://my-agent.example.com
  ```
</CodeGroup>

エージェントとコードの接続を解除するには、`self_hosted_deployment_url` に `null` を送信するか、[`cartesia disconnect`](/ja-jp/line/cli#self-hosted-agent-code) を実行します。

## 移行の手順

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

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

```python main.py theme={null}
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)
```

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

```bash theme={null}
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}`](/ja-jp/api-reference/agents/update) のリクエストボディです。変更するフィールドだけを送信してください。それ以外の設定はそのまま維持されます。

### 設定の対応表

**プロンプトとモデル**

| Line SDK | Managed Agents |
| - | - |
| `LlmConfig.system_prompt` | `config.instructions` |
| `LlmConfig.introduction` | `config.initial_message` |
| `LlmAgent(model=..., api_key=...)` | `config.model.id`（[LLM カタログ](/ja-jp/agents/models)から選択） |
| `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 ツール](/ja-jp/agents/webhook-tools) |
| `end_call` | `config.system_tools.end_call` |
| `transfer_call` | `config.system_tools.transfer_to_number` |
| `send_dtmf` | `config.system_tools.send_dtmf` |
| `AgentSendCustom` などのアプリ内アクション | [クライアントツール](/ja-jp/agents/client-tools) |
| `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` | 設定変更で[バージョン](/ja-jp/agents/configuration#バージョン)が公開される |
| `cartesia deployments ls` | [`GET /v1/agents/{agent_id}/versions`](/ja-jp/api-reference/agents/versions/list) |
| `cartesia env set` | [シークレットは使用するツール側に保存](/ja-jp/agents/webhook-tools#headers-and-authentication) |
| `wss://api.cartesia.ai/agents/stream/{agent_id}` | [`wss://api.cartesia.ai/v1/agents/websocket/{agent_id}`](/ja-jp/line/integrations/websocket-api) |

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

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

```json theme={null}
{
  "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 音声を上書きできました。マネージドエージェントでは、これは設定の一部になります：

```json theme={null}
{
  "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` は新しい設定です。全項目については[エージェントの設定](/ja-jp/agents/configuration)を参照してください。

### ツール

#### Webhook ツール

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

```python theme={null}
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 で表すと次のようになります：

```bash theme={null}
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` を設定してください。更新と削除については[ヘッダーと認証](/ja-jp/agents/webhook-tools#headers-and-authentication)を参照してください。

#### 組み込みツール

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

```python theme={null}
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 では次のようになります：

```json theme={null}
{
  "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."
          }
        ]
      }
    }
  }
}
```

各ツールで利用できる設定については[システムツール](/ja-jp/agents/system-tools)を参照してください。

#### クライアントツール

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

```python theme={null}
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})
```

これは[クライアントツール](/ja-jp/agents/client-tools)になり、同じ [`POST /v1/agents/tools`](/ja-jp/api-reference/agents/tools/create) エンドポイントで作成します：

```json theme={null}
{
  "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` を送信し、アプリがカートを開きます：

```javascript theme={null}
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` に追加します。このリストは更新のたびに全体が置き換えられます：

```json theme={null}
{
  "config": {
    "tools": [
      { "id": "agent_tool_5RkP2wZmQ8xTnLc4vB7dHy" },
      { "id": "agent_tool_9dK3xQm7VbNs2PfR4tLwZa" }
    ]
  }
}
```

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

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

ビルドやデプロイは不要です。すべての設定変更は検証され、不変の[バージョン](/ja-jp/agents/configuration#バージョン)として保存され、即座に新しい通話に適用されます。進行中の通話は、開始時のバージョンのまま最後まで実行されます。

ロールバックするには、古いバージョンの `config` を読み取り、`PATCH` で送信します。これにより、履歴を書き換えるのではなく、ロールバックが新しいバージョンとして記録されます。

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

エージェント WebSocket は [`/v1/agents/websocket/{agent_id}`](/ja-jp/api-reference/agents/agent-websocket) に移動しました。認証は変わりません。サーバーからは `X-API-Key`、ブラウザからは [`/access-token` エンドポイントの `agent` グラント](/ja-jp/api-reference/auth/access-token#body-grants-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` | 同じ名前、フラットなフィールド |

```javascript theme={null}
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](/ja-jp/line/integrations/websocket-api) にすべてのイベントが詳しく記載されています。

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

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


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