Koei's Digital Garden

Agents Framework Introduction

6 min read

Agents Framework Introduction

参照元: LiveKit Agents Documentation ロードマップ: 学習ロードマップ ソース: https://docs.livekit.io/agents/

What（何についてか）

LiveKit Agents フレームワークの全体像。 Python または Node.js で書いたプログラムを LiveKit の Room にリアルタイム参加者（participant）として追加するための仕組みと、その周辺インフラ（agent server / dispatch / job）の概念説明。

Why（なぜ必要か）

AIモデルはデータセンターで動いているが、ユーザーはモバイル等の不安定なネットワークから繋いでくる。 WebRTC（LiveKit SFU）を使うことで、この非対称なネットワーク状況でも安定したリアルタイム通信が成立する。 Agents フレームワークはその WebRTC の複雑さを隠蔽しつつ、STT→LLM→TTS パイプライン・ターン検出・ツール呼び出し・マルチエージェントなどの「よくある課題」をすでに実装した状態で提供してくれる。

How（どう動くか）

Agent の全体フロー

graph TD
    FC["自前コントローラ\n（お前のバックエンドサーバー）"]
    LC["LiveKit Cloud\n（自動dispatch）"]
    AS["Agent server\n（常駐プロセス）"]
    JB["Job\n（Agent実体・participant）"]
    LS["LiveKit Server\n（SFU）"]
    UF["User Frontend"]

    FC -->|"Dispatch API"| LS
    LC -->|"自動dispatch"| AS
    LS -->|"dispatch"| AS
    AS -->|"job起動"| JB
    JB -->|"WebRTC join"| LS
    UF -->|"WebRTC join"| LS
    LS -->|"メディア転送"| JB
    LS -->|"メディア転送"| UF

登場人物の整理

役割正体何をするか
LiveKit ServerWebRTC SFU（インフラ）Room 管理・メディア転送・シグナリング・TURN
LiveKit SDKクライアントライブラリLiveKit Server と通信するためのライブラリ（JS/Python 等）
Agent server常駐バックエンドプロセスdispatch を受けて job を起動・管理・スケーリング
Job（Agent実体）Room に join するプロセス音声受信・STT→LLM→TTS・出力トラックのパブリッシュ
自前コントローラお前のアプリのバックエンドサーバーLiveKit Dispatch API を叩いて特定 Room に agent を送り込む

LiveKit Server と Agent server は別物。 LiveKit Server = 通信インフラ。Agent server = エージェントのオーケストレータ。

Dispatch の3パターン

  1. 自動 dispatch（デフォルト） — Room が作成されたら LiveKit Cloud が自動でエージェントを dispatch
  2. 明示的 dispatch（REST API） — 自前バックエンドが Dispatch API を呼び出して特定 Room にエージェントを送り込む
  3. エージェント間 dispatch — マルチエージェント構成でエージェントが別エージェントを呼ぶ

フロントエンドから直接 dispatch することは技術的には可能だが、API キーをフロントに置くことになるので設計上やらない。

Job が Room に join するまで

sequenceDiagram
    participant C as コントローラ/LiveKit Cloud
    participant AS as Agent server
    participant JB as Job
    participant LS as LiveKit Server
    participant UF as User Frontend

    AS->>LS: 起動・登録（待機状態）
    C->>AS: dispatch（RoomXに入れ）
    AS->>JB: subprocess起動
    JB->>LS: WebRTC join（認証トークン）
    UF->>LS: WebRTC join
    LS-->>JB: 入力トラック（ユーザー音声）
    JB->>JB: STT → LLM → TTS
    JB->>LS: 出力トラック（エージェント音声）
    LS-->>UF: エージェント音声配信

SFU だから P2P じゃない

方式メディアの経路LiveKit
P2P端末 ↔ 端末（直接）✗
SFU端末 → SFU → 各端末（転送）✅
MCU端末 → MCU（混合）→ 端末✗

SFU を選ぶ理由：

  • 参加者が増えても接続数がサーバー 1 本で済む（P2P は N*(N-1)/2 本必要）
  • サーバーが全トラックを把握 → エージェントがトラックをサブスクライブしやすい
  • サーバーサイドで録音・処理・観測が自然にできる
graph LR
    subgraph P2P_Model
        P1((User A)) ---|Direct| P2((User B))
        P1 ---|Direct| P3((Agent))
        P2 ---|Direct| P3
    end
    subgraph SFU_Model_LiveKit
        S1((User A)) --> SFU["LiveKit Server\n(SFU)"]
        S2((User B)) --> SFU
        S3((Agent)) --> SFU
        SFU --> S1
        SFU --> S2
        SFU --> S3
    end

LiveKit Server（SFU）がないと Room 自体が成立しない。

TURN について

WebRTC は ICE + STUN で NAT 越えを試みるが、企業ネットワーク等の厳格な NAT では失敗する。 TURN はそのフォールバックで、メディアをサーバー経由でリレーする。LiveKit Cloud は TURN も内包している。

Key Concepts

用語説明
SFU (Selective Forwarding Unit)メディアを混合せず「選択的に転送」するサーバー。LiveKit はこれ
MCU (Multipoint Control Unit)ストリームをサーバー側で混合して1本にするサーバー。LiveKit は使わない
TURNNAT 越えできないときにメディアをサーバー経由でリレーする仕組み
Agent serverdispatch 待機する常駐プロセス。job を起動・管理するオーケストレータ
Job実際に Room に join するエージェントの実体（participant として振る舞う）
Dispatch「この Room に agent を入れろ」という指示。LiveKit Cloud または自前バックエンドが発行
自前コントローラお前のバックエンドサーバー。Dispatch API を叩く役割
Multimodality音声・映像・テキスト複数のモダリティを扱う能力
Turn detectionユーザーの発話の終わりを検出してエージェントが応答するタイミングを決める機能

一言まとめ

LiveKit Agents は「SFU（LiveKit Server）でつながった Room に、agent server が管理する job（participant）を送り込み、STT→LLM→TTS パイプラインでリアルタイム音声対話を実現するフレームワーク」だ。

疑問・今後の深掘りポイント

  • WebRTC の ICE / STUN / TURN の詳細（必要になったタイミングで）
  • Agent server のライフサイクル詳細（Phase 3 で扱う）
  • Dispatch API の仕様（自前コントローラを実装する際に）
  • Langfuse / OpenTelemetry との Observability 連携（Phase 6 で扱う）

Graph View

Backlinks