# AI Agent 計画ガイド：踏んだ失敗から再現可能なフレームワークへ > AI Agent を導入する前に、役割と境界を明確にしなければ、すぐに制御不能なブラックボックスと化す。OneUp の自動投稿から討論エンジン、自社 AI プラットフォームの監視まで、私が踏んできたすべての失敗は同じことを指していた。モジュール化、追跡可能性、小さく始めること。これは実戦から帰納した五つの原則だ。 - Author: Paul Kuo（郭曜郎） - Date: 2025-10-05 - Pillar: 創造と構築 / Creation & Enterprise - Tags: AI Agent, 自動化, プロセス設計, リスク管理, モジュール化, Multi-Agent - Canonical: https://paulkuo.tw/ja/articles/ai-agent-planning-guide/ - Language: Japanese (日本語) - Translation: AI-translated from the zh-Hant (Traditional Chinese) original - Original (zh-Hant): https://paulkuo.tw/articles/ai-agent-planning-guide.md - Site index for LLMs: https://paulkuo.tw/llms.txt --- 昨年末、私の OneUp 自動投稿パイプラインが深夜二時に同じ投稿を八回送信した。八プラットフォーム、それぞれ八件の重複コンテンツ。朝起きてスマートフォンの通知を見た私は、四十分かけて手動で削除して回った。
▶ 聴く・要約
AI 合成音声・著者本人の声をクローン
その日に学んだ教訓はシンプルだ。Agent を作ることは難しくない。難しいのは、制御を失わせないことだ。 過去一年で三つの Agent システムを構築した。討論エンジンでは GPT-4o、Gemini、Grok が互いに議論し、Perplexity がファクトチェックする。OneUp パイプラインは Google スプレッドシートからスケジュールを読み込み、DALL-E で画像を生成して八つのプラットフォームへ自動投稿する。自社 AI プラットフォームの生産ライン監視は深夜三時にパラメータを自動調整する。どのシステムも、それぞれ異なることを教えてくれた。 これは理論ではない。失敗を踏みながら帰納した五つの原則だ。 ## 動く前に三つの問いに答える コードを一行書く前に、私は今、自分に三つの問いを強制する。この Agent は何の問題を解くのか。権限の範囲はどこまでか。正しく動いていると、どうやって判断するのか。 基本的に聞こえるかもしれないが、討論エンジンの初版はまさに二番目の問いを考えていなかった。モデルが自由に討論のラウンド数を決められるようにした結果、あるとき二十七ラウンド走り、API の枠を使い果たした。その後、ハードな上限を設けた。最大五ラウンド、超えたら強制収束させる。 役割が曖昧な Agent は制御不能なブラックボックスに過ぎない。まず境界を引く。それからコードを書く。 ## API を優先し、ブラウザは最終手段にする Agent の価値はツールを呼び出して複数ステップのタスクを完了することにある。しかしツール統合の複雑さは指数的に増大する。 OneUp パイプラインで痛烈に学んだことがある。最初、投稿スケジューリングにブラウザ自動化を試みた。UI が変わるたびに全部壊れた。API に切り替えると、安定性は 60% から 99% に跳ね上がった。今の原則はシンプルだ。API の安定性を常に優先し、ブラウザ自動化は API が存在しない場合にのみ検討する。 データ処理も同じだ。入力データが汚ければ、Agent はゴミの上で判断を下す。[「AI の嵐の中で活路を見出す」](/ja/articles/personal-strategy-in-ai-storm/)で触れたように、構造設計が新たな競争力の核心だ。Agent の構造設計は、データクリーニングの段階からすでに始まっている。 ## モジュールに分割する。エラーを特定できるように 大型の Agent はメンテナンスが難しい。私は今、すべてのシステムを四つのモジュールに分割している。Input 処理 → 意思決定ロジック → ツール呼び出し → 結果の後処理。各モジュールは独立して検証でき、ロールバックできる。 討論エンジンはそう設計した。Input モジュールがトピックとモード（dialogue/duo/adversarial）を解析する。意思決定モジュールがラウンド制御と収束判断を担う。ツール呼び出しモジュールが四モデルへの API 呼び出しを処理する。後処理モジュールが結果を Markdown として保存する。どのモジュールに問題が起きても、他の部分を巻き込まない。 これは私がメモに記している協働の原則でもある。複雑なエンジニアリングはまず Phase に分解し、各 Phase を独立して検証可能にする。一括処理の結果は、たいてい途中で詰まり、それまで正しく動いていた部分まで壊すことになる。 ## すべてのステップにログを残す Agent の動作プロセスは透明でなければならない。そうでなければ、何かが壊れたとき、どこで壊れたかわからない。 OneUp パイプラインの八重投稿事件は、まさにログがなかったせいだ。API がタイムアウトを返し、スクリプトが八回リトライし、毎回新しい投稿のスケジュールに成功した。API 呼び出しのレスポンスステータスを記録していれば、二回目のリトライ時点で一回目がすでに成功していたことに気づけた。 今、私のすべての Agent には三層の監視がある。操作ログ（各ステップで何をしたか）、意思決定パス（なぜそれを選んだか）、コスト追跡（API の枠をどれだけ使ったか）。透明性は贅沢品ではない。生存条件だ。 ## 最小のシナリオから始める 最後の原則が最もシンプルで、最も見過ごされやすい。小さく始めることだ。 自社 AI プラットフォームの監視システムは、最初から全ラインを対象にしたわけではない。まず一つの生産ラインの一つのパラメータだけを監視させ、二週間動かしてロジックが正しいことを確認してから、段階的に拡張した。[「負けているのは認知ではない」](/ja/articles/overcome-fear-start-ugly/)で「まず粗いものを出せ」と言ったとおり、Agent も同じだ。粗削りな PoC を動かし、運用しながら最適化する。三ヶ月かけて完璧なシステムを設計し、本番で即爆発させるより、百倍まともだ。 Agent の価値は人を代替することではない。人の能力の境界を拡張することにある。ただし、拡張の前提は馴らすことだ。役割を明確に、モジュール化し、追跡可能にし、小さく始める。どの原則も、失敗の代償として得たものだ。