これまでに、ただコンピュータに話しかけて、実際に何かをしてもらいたいと思ったことはありませんか？ ファイルを作ったり、コードを書いたり、質問に答えたり。私はまさにそのために、Mem0 AIインターン課題として「完全に動作する音声制御AIエージェント」を作りました。
この記事では、私が作ったもの、背後にあるアーキテクチャ、選んだツールの理由、直面した課題、そして道中で学んだことを順を追って説明します。
何を作ったか
次の機能を備えた、音声制御AIエージェントです：
マイクからの音声、またはアップロードした音声ファイルを受け付ける
Whisperで発話をテキストに書き起こす
意図を検出する — ファイルを作りたい？ コードを書きたい？ 何かを要約したい？ それともただ雑談したい？
ローカルマシン上でアクションを実行する
すべての結果を、きれいなWeb UIで表示する
全体の流れを素早く例示します：
あなたの発話：「リトライ用のPythonコードを書いて」
エージェントがそれを書き起こす → 意図をWrite Codeとして検出 → LLMでPythonコードを生成 → output/retry.pyに保存 → UIで結果を表示します。
これらはすべて5秒以内に行われます。
️ アーキテクチャ
このプロジェクトは、4つの明確なモジュールに分割されています：
ユーザーが話す
↓
音声ファイル（.wav / .mp3）
↓
[stt.py] → Groq Whisper Large V3 → 書き起こしたテキスト
↓
[intent.py] → LLaMA 3.3-70B → 意図の分類（JSON）
↓
[tools.py] → ツールルーター
├── create_file → output/に空のファイルを作成
├── write_code → output/にコードを生成して保存
├── summarize → 話題を要約し、output/summary.txtに保存
└── general_chat → LLMの会話応答
↓
[app.py] → Gradio UI → 書き起こし、意図、アクション、出力を表示
↓
セッションメモリ → セッション内のすべてのアクションを追跡
各モジュールには1つの役割があり、それをきちんとこなします。この分離によって、コードのデバッグが容易になり、拡張もしやすく、理解もしやすくなります。
️ テックスタックと選んだ理由
コンポーネントツール理由UIGradio最も早い方法PythonでプロフェッショナルなAI UIを作るため音声認識Whisper Large V3（Groq）無料・高速・GPU不要LLMGroq LLaMA 3.3-70B無料APIで超高速、品質も非常に良いファイル操作Python pathlib組み込みで追加依存なし環境python-dotenv安全なAPIキー管理
ローカルモデルの代わりにGroqを選んだ理由？
この課題では、OllamaまたはLM Studioを使ったローカルモデルの使用が挙げられていました。私はこの選択肢も検討しましたが、強い理由が3つあるためGroqのAPIを選びました：
- GPU不要。Whisper Large V3やLLaMA 70Bをローカルで動かすには、最低でも16GBのVRAMが必要です。ほとんどの学生のノートPCにはそれがありません。Groqは自社のハードウェアで動かします。
- 速度。Groqは独自のLPU（Language Processing Unit）チップを使っており、ほとんどのローカルGPU構成よりも本当に高速です。レスポンスは1〜2秒で返ってきます。
- 無料枠。Groqの無料枠は、このプロジェクト全体をお金を払わずに構築してデモするのに十分なだけ用意されています。これは、READMEにハードウェア回避策として記載されています（課題の条件として許容されます）。
対応する4つの意図
エージェントの中心は、意図分類器です。私は、モデルが毎回きれいなJSONを返すように強制する、構造化されたLLMプロンプトを使用しました：
pythonprompt = f"""
次のコマンドを1つに分類してください：
create_file, write_code, summarize, general_chat
Command: "{text}"
次を「JSONのみ」で返してください：
{{
"intent": "write_code",
"details": "Python retry function",
"filename": "retry.py"
}}
"""
これにより、エージェントは次の4つの明確な能力を持ちます：
ファイル作成 — 「ミーティングノートというテキストファイルを作って」
output/フォルダに空のファイルを即座に作成します。
コード作成 — 「TODOリスト用のJavaScriptコードを書いて」
完成したコメント付きの、生産品質のコードを生成し、ファイルに保存します。
要約 — 「ニューラルネットワークの利点を要約して」
箇条書きを含む構造化された要約を作成し、output/summary.txtに保存します。
一般チャット — 「AIとMLの違いは何？」
どんな質問にも会話形式で答えます。
ボーナス：セッションメモリ
私はMem0 AI（AIエージェント向けのメモリ層を構築する会社）のためにこれを作っていたので、メモリのボーナス機能も確実に実装しました。
エージェントが行うすべてのアクションは、セッション履歴リストに保存されます：
pythonsession_history.append({
"transcription": transcription,
"intent": intent_display,
"action": action_taken,
"output": final_output,
})
これはUI上で、セッション中に起きたことのログとして表示されます。シンプルな実装ですが、Mem0が基盤としているコアコンセプト、つまり「エージェントには本当に役立つためにメモリが必要だ」という考え方を示しています。
直面した課題
課題1：LLMモデルが廃止された
開発の途中で、このエラーが出ました：
Error code: 400 - The model 'llama3-70b-8192' has been decommissioned
Groqが、私が使っていたモデルを引退させていました。修正は簡単で、llama-3.3-70b-versatileに更新するだけでした。しかし、この出来事から重要な教訓を学びました。つまり、APIの非推奨（deprecation）通知は常に確認し、フォールバック計画なしにモデル名をハードコードしないことです。
課題2：LLMからきれいなJSONを取り出すこと
意図分類器は、毎回正しいJSONを返す必要があります。しかしLLMは、レスポンスをMarkdownのコードブロックで囲むことがあり、例えば次のようになります：
{"intent": "write_code"}
これではjson.loads()が壊れます。私の対策は、解析の前にMarkdownを取り除くことでした：
pythonraw_response = raw_response.replace("
json", "").replace("
", "").strip()
result = json.loads(raw_response)
そして、すべてをtry/exceptで包み、解析に失敗した場合はgeneral_chatにフォールバックするようにしました。その結果、アプリがクラッシュすることはありません。
課題3：ファイル操作を安全に保つこと
課題では、エージェントが誤ってシステムファイルを上書きしないよう、ファイル作成はすべてoutput/フォルダに制限することが求められていました。私はPythonのpathlibでこれを処理しました：
pythonOUTPUT_DIR = Path("output")
OUTPUT_DIR.mkdir(exist_ok=True)
filepath = OUTPUT_DIR / filename # 常にoutput/の内側
これにより、ユーザーが何を言っても、エージェントがそれ以外の場所に書き込めないようにしています。
✅ 学んだこと
- プロンプトエンジニアリングは、モデル選定よりも重要です。
明確な指示と定義済みの出力形式を備えた適切に構造化されたプロンプトは、曖昧なプロンプトを与えた大きなモデルよりも一貫して優れた結果を出します。 - APIベースのモデルは、ハッカソンや課題に現実的です。
課題ではローカルモデルが推奨されていましたが、素早いプロトタイピングとデモ品質の結果を得るためには、適切に選んだAPI（特にGroqのような無料のもの）が、しばしばより良い選択になります。 - モジュール化されたコードは、非常に多くの時間を節約します。
各モジュール（stt.py、intent.py、tools.py）が単一の責任を持っていたため、デバッグは速くできました。モデルが廃止されたときも、2つのファイルだけ更新すれば済みました。 - メモリは、本当に難しい問題です。
たとえ単純なセッション履歴機能を実装するだけでも、Mem0がプロダクトとして存在する理由に対する理解が深まりました。本当の意味での永続メモリ — セッションをまたいで、ユーザーをまたいで、文脈検索を伴って — は深いエンジニアリング課題です。
リンク
GitHubリポジトリ： https://github.com/Amratanshu-d/voice-ai-agent
動画デモ： https://youtu.be/fbXTjaXM-oI
課題提供： Mem0 AI — MLOps and AI Infra インターン
Mem0 AIインターン課題のために、❤️を込めて作りました。もしAIエージェントを作っていて、それに永続メモリを追加したいなら、mem0.aiをチェックしてください。
