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

# オブザーバビリティ

> エージェントのパフォーマンスを完全に可視化します。

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

<Frame caption="通話オブザーバビリティのデモ">
  <iframe src="https://www.youtube.com/embed/LNQXi4C4JUk?si=BtuCc2fwCjHdInzi" frameBorder="0" webkitallowfullscreen mozallowfullscreen allowFullScreen style={{ width: "100%", height: "400px" }} />
</Frame>

## デプロイメント

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

<Frame>
  <img src="https://mintcdn.com/cartesia-2650f86a/hwxvcrAswl9LXrPR/assets/images/agents/deployment_logs.png?fit=max&auto=format&n=hwxvcrAswl9LXrPR&q=85&s=aa1c9d52b33564fa685b323f6c968c67" alt="デプロイメントログのサンプル" width="1960" height="1042" data-path="assets/images/agents/deployment_logs.png" />
</Frame>

## コールログ

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

<Frame caption="コールログ">
  <iframe src="https://www.youtube.com/embed/H713r_K0yaU?si=WXIhZdLKZYKk7-Ns" frameBorder="0" webkitallowfullscreen mozallowfullscreen allowFullScreen style={{ width: "100%", height: "400px" }} />
</Frame>

## トランスクリプト

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

<Frame>
  <img src="https://mintcdn.com/cartesia-2650f86a/hwxvcrAswl9LXrPR/assets/images/agents/call-transcripts.png?fit=max&auto=format&n=hwxvcrAswl9LXrPR&q=85&s=ad32e5c3a910630d9ff471d652a2dc19" alt="通話トランスクリプトのサンプル" width="2006" height="1190" data-path="assets/images/agents/call-transcripts.png" />
</Frame>

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

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

### SDK

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

```python theme={null}
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 を使用している場合、ロギングイベントは次のようになります：

```json theme={null}
{
  "type": "log_event",
  "event": "event_name",
  "metadata": {
    "key": "value"
  }
}
```

### Playground

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

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

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

### SDK

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

```python theme={null}
# 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 を使用している場合、メトリクスのロギングは次のようになります：

```json theme={null}
{
  "type": "log_metric",
  "name": "metric_name",
  "value": "metric_value"
}
```

### Playground

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

<Frame>
  <img src="https://mintcdn.com/cartesia-2650f86a/hwxvcrAswl9LXrPR/assets/images/agents/playground-loggable-metrics.png?fit=max&auto=format&n=hwxvcrAswl9LXrPR&q=85&s=02b131baeaa4fae0da13a848ef8ff4df" alt="プレイグラウンドのロギング可能なメトリクス" width="3680" height="2214" data-path="assets/images/agents/playground-loggable-metrics.png" />
</Frame>

## 通話の録音

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

<Frame>
  <img src="https://mintcdn.com/cartesia-2650f86a/hwxvcrAswl9LXrPR/assets/images/agents/call-recordings.png?fit=max&auto=format&n=hwxvcrAswl9LXrPR&q=85&s=5fc5f92433c1b06fa34dd773fd78f550" alt="通話録音のサンプル" width="1908" height="956" data-path="assets/images/agents/call-recordings.png" />
</Frame>

## Webhook

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

<Frame>
  <img src="https://mintcdn.com/cartesia-2650f86a/3qRJCfaKlXiuJi78/assets/images/agents/webhooks.png?fit=max&auto=format&n=3qRJCfaKlXiuJi78&q=85&s=7cf56fb9fd329e8b114c19e89c495133" alt="通話 Webhook のサンプル" width="2188" height="1520" data-path="assets/images/agents/webhooks.png" />
</Frame>

### Webhook シークレットの検証

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    if request.headers.get("x-webhook-secret") != os.environ["LINE_WEBHOOK_SECRET"]:
        return jsonify({"error": "unauthorized"}), 401
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    if (req.headers["x-webhook-secret"] !== process.env.LINE_WEBHOOK_SECRET)
      return res.status(401).json({ error: "unauthorized" });
    ```
  </Tab>
</Tabs>

### イベントタイプ

| イベント                 | 発生タイミング       | 型付きフィールド   |
| -------------------- | ------------- | ---------- |
| `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}](/api-reference/agents/calls/get-call) のレスポンスと一致します。一部のイベント（例：`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](/api-reference/agents/calls/get-call) を参照。 |
| `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`

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

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

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

```bash theme={null}
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": []
    }
  }'
```

<Note>
  後方互換性のため：

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

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