「とりあえず動く」から実運用へ。音声AI開発でElevenLabsとLangChainを組み合わせるハイブリッド設計

音声AIの「とりあえず動く」は10分で作れる

音声AIエージェントの開発ハードルが下がった。

フロントエンドの複雑な処理は、マネージドAPIのSDKを使えば数行で終わる。

しかし、それを実運用に乗せようとした瞬間に地獄を見る。

エージェントは外部APIのエラー一つでパニックを起こし、思考停止に陥る。

フルマネージドの快適さと、堅牢なバックエンド設計。

この2つを適材適所で組み合わせるハイブリッド設計が、これからのAI開発のスタンダードになる。

ElevenLabsのReact SDKがフロントエンドの複雑さを隠蔽する

音声AIプラットフォームの進化が止まらない。

開発者が泥臭いコードを書く必要はなくなった。

ElevenLabsが提供するReact SDKはその最たる例だ。

ブラウザ上でのマイクのパーミッション要求から、WebSocketを通じた音声ストリーミングまでを完全に隠蔽している。

開発者は提供されるフックを一つ呼び出すだけで、会話の状態管理やイベントハンドリングを実装できる。

ダッシュボードでエージェントを作成し、発行されたIDを環境変数にセットするだけでいい。

ダッシュボードにアクセスし、画面左側のメニューからエージェントを追加する。

パーソナルエージェントを選択し、名前と目的を入力する。

システムプロンプト、言語、そして音声のタイプを指定する。

対応言語と音声のタイプの多さが特徴だ。

設定が完了したらデプロイボタンを押してエージェントを稼働させる。

出力されるエージェントIDを控えておく。

プロトタイプなら、10分でブラウザ上で対話できるエージェントが完成する。

私はこのSDKを使って、社内向けの音声アシスタントの挙動を確認した。

マイクのミュート解除を忘れて無音のまま5分間話し続けてしまった。

useConversationフックは、会話の状態やイベントハンドラーを管理する。

マイクのミュート状態や音量の割合を引数として受け取る。

メッセージを受信した際の処理は、配列に新しいメッセージを追加するだけだ。

エラーが発生した場合は、エラーテキストを構築して状態を更新する。

ステータスやモードの変更も、ペイロードから文字列を抽出して画面に反映させる。

接続時や切断時のコールバックも用意されている。

マイクの要求は、ブラウザのメディアデバイスAPIを呼び出す。

音声の許可が得られれば、マイクの準備完了フラグを立てる。

セッションの開始には、環境変数から取得したエージェントIDを使用する。

接続タイプやユーザーIDを指定し、新しい会話IDを取得して保存する。

ユーザーからのテキスト入力を送信するメソッドも提供されている。

空白をトリムし、空文字でなければ送信処理を実行する。

セッションの終了も、専用のメソッドを呼び出すだけで完了する。

これらはすべて、数行の関数呼び出しで実現できる。

フロントエンドの実装にかかる時間は、従来の10分の1以下に短縮される。

開発者はUIの構築やユーザー体験の向上にリソースを集中できる。

しんたろー：
ElevenLabsのSDKのコードを見ていて、WebSocketの管理が完全に隠蔽されているのが気になった。
自前で書くと数千行になる処理が数行で終わるのは、開発体験としてかなり快適だと思った。

AWS CDKを用いたS3とCloudFrontによるインフラ構築

フロントエンドの実装が完了したら、次はインフラの構築だ。

AWS CDKを使用すれば、インフラをコードとして定義できる。

スタッククラスを定義し、コンストラクターでスコープとIDを受け取る。

親クラスを初期化し、リソースの定義を開始する。

静的アセットのホスティングには、Amazon S3を使用する。

バケットの作成時には、パブリックアクセスを完全にブロックするBLOCK_ALL設定を適用する。

暗号化はS3_MANAGEDキーを使用し、SSL通信を強制する。

リソース削除時にはバケットも破棄するDESTROYポリシーと、中のオブジェクトも自動的に削除する設定を組み合わせる。

コンテンツの配信には、Amazon CloudFrontを使用する。

オリジンアクセス制御を設定し、S3バケットへの直接アクセスを防ぐ。

ビューワーのプロトコルポリシーは、HTTPSへのリダイレクトに設定する。

キャッシュポリシーは最適化されたものを選択し、配信効率を高める。

シングルページアプリケーションのルーティングに対応するため、エラーレスポンスを設定する。

HTTPステータス403と404のエラーが発生した場合の処理を定義する。

レスポンスのステータスコードを200に書き換え、ルートのHTMLファイルを返す。

キャッシュの生存期間は5分に設定する。

これにより、クライアントサイドルーティングが正常に機能する。

私はこの構成をClaude Codeに指示して構築手順を確認した。

AWSの認証情報が期限切れでデプロイコマンドが弾かれた。

インフラのコード化により、環境の複製や破棄が容易になる。

検証環境と本番環境の差異をなくし、デプロイの再現性を担保する。

プロトタイプの罠。実運用に耐えるエージェントの裏側

フロントエンドとインフラの構築が簡単になったことは素晴らしい。

実務で使えるエージェントを作るには、泥臭い状態管理とエラーハンドリングが不可欠だ。

エージェントが使うツールを、単なる関数として渡してはいけない。

LLMは平気で引数の型を間違え、必須パラメータを省略し、存在しないプロパティにアクセスしようとする。

これを防ぐには、Pydanticを用いて入出力のスキーマを厳密に型定義する。

検索ツールの入力スキーマを定義するクラスを作成する。

基本モデルクラスを継承して実装する。

検索キーワードのフィールドを文字列型で定義する。

フィールドの説明として「検索キーワード」という文字列を付与する。

最大結果数のフィールドを整数型で定義する。

デフォルト値は5に設定する。

最小値は1、最大値は10という制約を設ける。

フィールドの説明として「最大結果数」という文字列を付与する。

これにより、エージェントは事前に自分が何を渡すべきかを正確に理解できる。

出力スキーマであるSearchOutputも同様に厳密に定義する。

検索結果のリストを辞書型の配列として定義する。

総件数のフィールドを整数型で定義する。

エラーメッセージのフィールドを文字列型で定義する。

このフィールドは空の値を許容する設定にする。

実際の検索関数は、入力スキーマを受け取り出力スキーマを返す。

内部で実際の検索API呼び出しを行う。

結果のリストにはタイトル、URL、スニペットを含める。

総件数を計算して返すロジックを実装する。

例外発生時に空のリストとエラーメッセージを返すフェイルセーフな設計にする。

ツールは機能ごとにToolCategoryとして分類する。

列挙型クラスを定義し、各カテゴリの値を設定する。

情報検索、データベース操作、計算、通信、ファイル操作などに分ける。

ツールのリストにカテゴリ情報を付与するデータ構造を作成する。

これにより、エージェントが適切なツールを選びやすくなる。

私はこの分類を細かく分けすぎて、エージェントがツール選びに迷ってフリーズする現象を観察した。

しんたろー：
Pydanticのスキーマ定義を見ていると、LLMに型を強制するアプローチの面白さを感じる。
プロンプトエンジニアリングよりも、データ構造の設計に時間を割く方が確実だと思った。

Pydanticによる型定義とChromaを用いた記憶管理

エージェントには、人間のような記憶が必要だ。

会話履歴をすべてプロンプトに詰め込めば、すぐにコンテキストウィンドウの上限に達する。

直近の会話だけを保持する短期記憶と、ベクトルデータベースを用いた長期記憶を明確に分離する。

ShortTermMemoryクラスは、最大メッセージ数を指定したキューで実装する。

古い要素は自動的に削除される仕組みを利用する。

役割と内容のペアを配列に追加していく。

直近5件のメッセージを取得するメソッドを用意し、プロンプトに組み込む。

記憶をリセットするクリアメソッドも実装する。

長期記憶の実装であるLongTermMemoryには、ChromaとOpenAIEmbeddingsを使用する。

コレクション名を指定してベクトルデータベースを初期化する。

データの論理的な分離を可能にする。

知識を保存する際は、テキストとメタデータをセットにして追加する。

メタデータにキーを含めることで後からフィルタリングしやすくする。

検索時には、クエリとの類似度を計算し、上位3件の結果を取得する。

検索結果のドキュメントオブジェクトからコンテンツとメタデータを抽出する。

メモリを持つエージェントは、これら2つの記憶を統合して動作する。

コンストラクターで短期記憶と長期記憶を初期化する。

短期記憶の最大メッセージ数を20件に設定する。

ユーザーの入力を受け取ると、まず短期記憶に追加する。

次に、長期記憶から関連情報を検索する。

検索結果のコンテンツを改行コードで結合する。

コンテキストとしてプロンプトに埋め込む。

直近の会話履歴も併せてLLMに送信する。

得られた応答は、再び短期記憶に追加される。

この仕組みにより、過去の文脈を踏まえた自然な対話が実現する。

私はこの記憶システムの挙動を見ていて、エージェントが過去の入力データを正確に引き出す精度に驚いた。

指数バックオフによるエラーハンドリングの実装

実務では、外部APIの失敗は日常茶飯事だ。

ネットワークは切れるし、レートリミットには引っかかる。

システム側でエラーを握りつぶしてはいけない。

エージェントはエラーを適切に処理し、リトライやフォールバックを実行する。

エラーに強いツールラッパーであるResilientToolを実装する。

実行する関数、最大リトライ回数、フォールバック関数を引数に取る。

リトライ回数はデフォルトで3回に設定する。

実行メソッドは可変長引数を受け取る。

最後のエラーを保持する変数を空で初期化する。

最大リトライ回数の分だけループを回す。

ループ内で対象の関数を実行し、成功すれば結果を返す。

例外が発生した場合は、エラーを変数に記録する。

試行回数に応じた待機時間を計算する。

待機時間は2のn乗秒となる。

計算した時間だけシステムの実行を一時停止する。

すべてのリトライが失敗した場合の処理に移る。

フォールバック関数が設定されていれば、それを実行する。

設定されていなければ、記録しておいた最後のエラーを返す。

例外をキャッチしたら、そのエラーメッセージを文字列としてエージェントに返却する。

「APIの呼び出し上限に達しました」という結果を受け取れば、エージェントは別のツールを使う。

これが、パニックを起こさない堅牢なエージェントの基本構造だ。

私はこのリトライ処理のループ条件を見誤り、APIの呼び出し回数が想定を超えて跳ね上がる現象を確認した。

ElevenLabsのフロントエンドSDKと、LangChainのバックエンド設計を統合する。

この統合知見こそが、初めて実用的なエージェントを完成させる鍵となる。

しんたろー：
指数バックオフの実装コードは、分散システムの基本だ。
AIエージェントも結局は外部APIに依存するシステムの一つに過ぎないという事実が興味深い。

音声AI開発に関するFAQ

Q1: フルマネージドAPIのReact SDKを使う最大のメリットは何ですか？

ブラウザ特有の複雑なメディア制御を完全に隠蔽できる点だ。

マイクのパーミッション要求、音声データのエンコード、WebSocketを通じた双方向ストリーミングのセッション管理を自動化する。

これらを自前で実装すると数千行のコードになるが、SDKのフックを使えば数行で完了し、即座にUI開発に移行できる。

Q2: エージェントのツール呼び出しでパニックを防ぐ具体的な方法は？

ツールを単なる関数として扱わず、入出力を厳密に型定義することだ。

Pydanticのモデルを使ってパラメータの制約を明記し、LLMに正しい形式を強制する。

API呼び出し失敗時の例外処理を必ず実装し、エラー内容を文字列としてLLMに返却することで、エージェントに次のリカバリー行動を推論させる。

Q3: エージェントの記憶管理はどのように実装しますか？

短期記憶と長期記憶を分離して実装する。

短期記憶は直近5件から20件の会話履歴を配列として保持し、コンテキストウィンドウの消費を抑える。

長期記憶はChromaなどのベクトルデータベースを使用し、過去の知識をエンベディングして保存し、類似度検索で必要な情報だけを抽出する。

まとめ

音声AIエージェントの開発は、フロントエンドの簡略化とバックエンドの複雑化が同時に進行している。

ElevenLabsのマネージドAPIでプロトタイプを作り、LangChainと堅牢な状態管理で実運用に耐えるシステムへと昇華させる。

このハイブリッドなアーキテクチャ設計が、次世代の開発者に求められる必須スキルとなる。

👉 ThreadPostでSNS運用を自動化する