オブザーバビリティ

すべてのデプロイメントと通話を監視します。

通話オブザーバビリティのデモ

デプロイメント

各デプロイメントには一意の ID が生成されます。ログはコンソールで確認できます。

コールログ

通話をクリックして、推論コードが生成したログ出力を確認できます。

コールログ

トランスクリプト

各通話には、書き起こされた音声と生成されたテキストが独立して分かれたトランスクリプトがあります。これらのトランスクリプトを API または CLI でエクスポートすると、より詳細なターン単位のタイムスタンプも含まれます。

ロギング可能なイベント

ツール呼び出しに紐付けずにイベントを記録します。

SDK

SDK では、エージェントまたはツールから LogMessage イベントを yield することでカスタムイベントを記録できます：

from line.events import LogMessage

@loopback_tool
async def process_order(ctx, order_id: Annotated[str, "Order ID"]):
    """Process a customer order."""
    result = await api.process_order(order_id)

    # Log a custom event
    yield LogMessage(
        name="order_processed",
        level="info",
        message=f"Processed order {order_id}",
        metadata={"status": result.status, "order_id": order_id}
    )

    return f"Order {order_id} processed: {result.status}"

yield されたイベントは自動的にプラットフォームへ送信されます。

Websocket

SDK を使わずに素の WebSocket を使用している場合、ロギングイベントは次のようになります：

{
  "type": "log_event",
  "event": "event_name",
  "metadata": {
    "key": "value"
  }
}

Playground

プレイグラウンドでは通話の Transcript タブからこれらのイベントを確認できます。

ロギング可能なメトリクス

ワークフロー内の任意のポイントでメトリクスを記録します。

SDK

SDK では、LogMetric イベントをブロードキャストすることでメトリクスを記録できます。これを示すフォーム入力テンプレートからの抜粋：

# Record the answer in form manager
success = self.form_manager.record_answer(answer)

if success:
  # Log metric for the answered question
  if current_question:
    metric_name = current_question["id"]
    yield LogMetric(name=metric_name, value=answer)
    logger.info(f"📊 Logged metric: {metric_name}={answer}")

ユーザーブリッジはデフォルトで LogMetric イベントを購読しており、LogMetric がブロードキャストされたことを検出すると、デフォルトでそれを WebSocket 経由でログとして送信します。

Websocket

SDK を使わずに素の WebSocket を使用している場合、メトリクスのロギングは次のようになります：

{
  "type": "log_metric",
  "name": "metric_name",
  "value": "metric_value"
}

Playground

プレイグラウンドでは通話の Transcript タブからこれらのイベントを確認できます。

通話の録音

通話の録音はプレイグラウンドからダウンロードできます。

Webhook

Cartesia は通話のライフサイクル全体を通じて、お客様の HTTPS エンドポイントに Webhook イベントを送信します。POST + application/json を公開し、x-webhook-secret ヘッダーが保存済みのシークレットと一致することを検証してください。

Webhook シークレットの検証

Python
TypeScript

if request.headers.get("x-webhook-secret") != os.environ["LINE_WEBHOOK_SECRET"]:
    return jsonify({"error": "unauthorized"}), 401

if (req.headers["x-webhook-secret"] !== process.env.LINE_WEBHOOK_SECRET)
  return res.status(401).json({ error: "unauthorized" });

イベントタイプ

イベント	発生タイミング	型付きフィールド
`call_started`	通話セッションが開始される	`call`
`call_completed`	通話が正常に終了する	`call`
`call_failed`	通話がエラーで終了する	`call`
`call_turn`	各会話ターン	`turn`
`post_call_analysis`	非同期分析の完了後	`analysis`

エンベロープフィールド

すべての Webhook イベントには、以下のトップレベルフィールドが含まれます：

フィールド	説明
`type`	イベントタイプ（上記の表を参照）。
`call_id`	通話の識別子。
`agent_id`	通話を処理したエージェント。
`webhook_id`	Webhook 設定 ID。
`timestamp`	RFC 3339 形式のイベント時刻。

`call`

call_started、call_completed、call_failed イベントに含まれます。GET /agents/calls/{call_id} のレスポンスと一致します。一部のイベント（例：call_started）では、まだ有効な値を持たない end_time などのフィールドが省略される場合があります。

フィールド	説明
`id`	通話の識別子。
`agent_id` / `agent_name`	エージェントの詳細。
`status`	`started`、`completed`、または `failed`。
`start_time` / `end_time`	RFC 3339 形式のタイムスタンプ。
`end_reason`	通話終了の理由（例：`client_hangup`、`agent_hangup`、`inactivity`）。すべての値については EndReason を参照。
`transcript`	ターンの配列（下記の `turn` を参照）。
`telephony_params`	`from`、`to`、`direction`、`call_sid`、`connection_type`。
`telephony_account_type`	`cartesia`、`twilio`、または `sip_trunk`。
`deployment_id` / `deployment_version_id`	通話を処理したデプロイメント（該当する場合）。
`deployment_region`	`US`、`EU`、または `APAC`。
`error_message`	エラーの詳細（失敗した通話のみ）。
`metadata`	通話開始時に渡されたユーザー指定のメタデータ。
`summary`	通話の要約（イベント発生時に利用可能な場合）。

`turn`

call_turn イベントに含まれます。エージェントまたはユーザーの発話ごとに 1 ターン。

フィールド	説明
`role`	`assistant` または `user`。
`text`	ターンのテキスト。
`start_timestamp` / `end_timestamp`	通話開始からの秒数。
`stt_ttfb`	ユーザー音声認識（STT）のタイム・トゥ・ファースト・バイト（秒）、利用可能な場合。
`tts_ttfb`	エージェント TTS のタイム・トゥ・ファースト・バイト（秒）、利用可能な場合。
`tool_calls`	このターン中に行われたツール呼び出し、利用可能な場合。

`analysis`

post_call_analysis イベントに含まれます。非同期分析の完了後に送信されます（現時点では要約の生成。今後、評価とメトリクスがここに追加される予定です）。

フィールド	説明
`summary`	1〜2 文の通話要約。

例: `call_completed`

{
  "type": "call_completed",
  "call_id": "ac_sid_gqkgRWUz2u64qFUjA1mZyr",
  "agent_id": "agent_rwh4HGMgyhK7rM5ucVqbiC",
  "webhook_id": "agent_webhook_P3MgdLf1cpaucZJ7xWehCC",
  "end_reason": "client_hangup",
  "timestamp": "2026-04-16T01:08:50.061907836Z",
  "call": {
    "id": "ac_sid_gqkgRWUz2u64qFUjA1mZyr",
    "agent_id": "agent_rwh4HGMgyhK7rM5ucVqbiC",
    "agent_name": "My Agent",
    "status": "completed",
    "start_time": "2026-04-16T01:08:37.413659Z",
    "end_time": "2026-04-16T01:08:50.036327Z",
    "end_reason": "client_hangup",
    "telephony_params": {
      "from": "websocket",
      "to": "agent_rwh4HGMgyhK7rM5ucVqbiC",
      "connection_type": "websocket"
    },
    "transcript": [
      {
        "role": "assistant",
        "text": "Hi there! How can I help you today?",
        "start_timestamp": 0.41,
        "end_timestamp": 3.2,
        "tts_ttfb": 0.065
      },
      {
        "role": "user",
        "text": "I want to schedule an appointment.",
        "start_timestamp": 3.5,
        "end_timestamp": 5.8
      }
    ]
  }
}

例: `post_call_analysis`

{
  "type": "post_call_analysis",
  "call_id": "ac_sid_gqkgRWUz2u64qFUjA1mZyr",
  "agent_id": "agent_rwh4HGMgyhK7rM5ucVqbiC",
  "webhook_id": "agent_webhook_P3MgdLf1cpaucZJ7xWehCC",
  "timestamp": "2026-04-16T01:08:50.955058787Z",
  "analysis": {
    "summary": "The caller requested to schedule an appointment. The agent confirmed availability and booked a slot."
  }
}

エンドポイントのテスト

curl -sS -X POST "https://your-server.example/webhooks/cartesia" \
  -H "Content-Type: application/json" \
  -H "x-webhook-secret: YOUR_WEBHOOK_SECRET" \
  -d '{
    "type": "call_completed",
    "call_id": "ac_test_123",
    "agent_id": "agent_demo",
    "webhook_id": "agent_webhook_test",
    "timestamp": "2026-01-01T00:00:00.000000000Z",
    "call": {
      "id": "ac_test_123",
      "agent_id": "agent_demo",
      "agent_name": "Test Agent",
      "status": "completed",
      "end_reason": "client_hangup",
      "transcript": []
    }
  }'

後方互換性のため：

call_completed および call_failed イベントには、トップレベルの body（トランスクリプト配列）とトップレベルの end_reason も含まれます。代わりに call.transcript と call.end_reason を使用してください。
call_turn イベントには、生のターンペイロードを含むトップレベルの body も含まれます。代わりに turn を使用してください。

これらの非推奨フィールドは将来のリリースで削除されます。

はじめに

オーディオ連携

デプロイとモニタリング

評価

開発者ツール

オブザーバビリティ

デプロイメント

コールログ

トランスクリプト

ロギング可能なイベント

SDK

Websocket

Playground

ロギング可能なメトリクス

SDK

Websocket

Playground

通話の録音

Webhook

Webhook シークレットの検証

イベントタイプ

エンベロープフィールド

`call`

`turn`

`analysis`

例: `call_completed`

例: `post_call_analysis`

エンドポイントのテスト

​デプロイメント

​コールログ

​トランスクリプト

​ロギング可能なイベント

​SDK

​Websocket

​Playground

​ロギング可能なメトリクス

​SDK

​Websocket

​Playground

​通話の録音

​Webhook

​Webhook シークレットの検証

​イベントタイプ

​エンベロープフィールド

​call

​turn

​analysis

​例: call_completed

​例: post_call_analysis

​エンドポイントのテスト

デプロイメント

コールログ

トランスクリプト

ロギング可能なイベント

SDK

Websocket

Playground

ロギング可能なメトリクス

SDK

Websocket

Playground

通話の録音

Webhook

Webhook シークレットの検証

イベントタイプ

エンベロープフィールド

`call`

`turn`

`analysis`

例: `call_completed`

例: `post_call_analysis`

エンドポイントのテスト