全部任せたら、全部見えなくなった

PoC は、思ったより簡単に動きます。Agent Framework に任せれば、LLM 呼び出しも tool 接続も structured output も trace も、それっぽく揃います。

でも、少し複雑なタスクに近づけると、別の問題が出てきました。出力がおかしいとき、どこを直せばいいのか分からない。

prompt なのか。context なのか。workflow なのか。schema なのか。reflection なのか。tool calling なのか。

全部を一つの Agent Loop に投げ込んだとき、動くときは気持ちいい。でも、ズレたときに、どの責務でズレたのかが見えない。

自由度が高いということは、責務の境界が溶けている、ということでもありました。

coding Agent でさえ迷っていた

最初は MAF、Microsoft Agent Framework を使っていました。抽象を使えば、呼び出しも structured output も整理できるだろう、と。

ところが、Codex に MAF を使った実装を頼むと、workflow と Agent loop の中間のようなコードが出てきた。完全な workflow でもない。完全な autonomous loop でもない。

うおw、coding Agent でさえ迷ってるじゃん。

Codex が悪いわけではありません。逆です。抽象の自由度が広いから、どこに何を置いても成立してしまう。人間も AI も、置き場所が決まっていないと迷う。

欲しかったのはその自由度ではなく、workflow は workflow、model call は model call、context provider は context provider として分かれていることでした。

orchestration と execution は、同じ責務じゃなかった

見えてきたのは、orchestration（workflow を進める）と execution（node の中で model call を実行する）を、同じ framework の同じ責務にする必要はない、ということでした。

二つを同じ framework に寄せると、一見まとまって見える。でも、実際には責務が混ざる。混ざると、部品を差し替えにくくなる。

うおw、密結合じゃん。

分けておけば、workflow は LangGraph のまま、node 内部の model runtime だけを MAF から Pydantic AI に差し替えられる。全部を一つに入れると、最初は気持ちいい。でも、あとからどこを外せばいいか分からなくなる。

Agent Framework を選ぶ話だと思っていたのに、実際に詰まったのは「どの責務をどこに置くか」でした。

見えるようにしたら、普通のソフトウェア設計になった

責務を分けていったら、残ったのはかなり地味な姿でした。

workflow は LangGraph。output schema は Pydantic。prompt surface は Jinja。context は MCP を application が deterministic に呼ぶ。Skill は判断軸。Reflection は別 node。trace は Langfuse。UI は system state を出す。

うおw、普通にソフトウェア設計じゃん。

状態を外に出す。入出力契約を持つ。prompt surface を分ける。context provider を制御する。trace を残す。新しいことをしているようで、かなり古典的です。古典に戻ったというより、問題構造が古典を呼び戻した。

ズレたときに、修正可能な signal になるか

一番大きかったのは、責務を分けると、失敗が「修正可能な signal」になることでした。

失敗したときに、prompt が悪いのか。context が足りないのか。MCP の candidate が弱いのか。output schema が粗いのか。reflection が弱いのか。routing が間違っているのか。

うおw、CI じゃん。

Agent Loop に全部溶けていると、失敗はただの失敗になります。「なんか微妙」で終わる。でも責務が分かれていれば、失敗は次の PR を切れる signal になる。

見える責務だけが、直せる責務です。

Agent Loopおじさん、見えない責務に敗北しました

Agent Framework への丸投げ。一つの loop で回る気持ちよさ。「とりあえず動いた」の安心感。

対戦ありがとうございました。

Agent Loopおじさん、見えない責務に敗北しました。

負けた相手は、外部サービスでも、もっと賢いモデルでも、もっと強い framework でもなかった。自分で見えなくした責務の置き場所でした。

丸投げ（Agent Loop に全部任せる）で勝とうとしていたものが、引き算（責務を分けて見えるようにする）で勝てた。自由度を上げるほど勝てるのではなく、責務を見える位置に置くほど、直せるようになった、という話です。

この「丸投げをやめて、見える位置に責務を置く」を、Agent 設計の話としてちゃんと書いたのが、この本です。orchestration と execution の分離、MCP を Context Boundary として切ること、Skill を判断軸として持つことまで、責務の置き場所を一通り扱っています。

『PoCで終わらせないAI Agent設計』

Agent Loop を信じる前に、責務が見える位置にあったか、という話です。