AI エージェント開発で四層構造の仕組みで整理できたメモ 2025年12月版
AI エージェント開発で四層構造の仕組みで整理できたメモ 2025年12月版です。
前提
あくまで、2025 年 12 月時点での私の AI エージェント開発についての雑感です。開発の背景や技術背景はこの時点でのものとしてまとめます。
背景
最近、AI エージェントの仕様策定から入りながら実際に動くものの開発も行うことが増えてきました。
2025 年 7 月時点の Claude で Artifacts で自分が便利に使っている出力方法のメモ - 1ft-seabass.jp.MEMO
その中で Claude Desktop の Artifact がとても好きで、あのデータをまとめる上でとても使いやすいなと感じていました。
自然言語で指示するだけでリッチな UI やグラフが生成されるってのはとても良かったんですよね。たとえばセンサーデータなどがあってそれを可視化するといったところが、私がフロントエンドでやるんだたらこう書くなあこう見せるなあというのが良い感じに出てくる。フロントエンドのデータ可視化という観点からしても、AI がここまでやってくれるのかという感動がありました。
自分の開発においてもクライアントワークでも使いたいなあと思いました。
ただですね、毎回生成されるんですけども、制御の大変さはありました。
同じ入力でも異なる出力が出てくるという AI ではありがちな部分がありますし、そうなってくると品質の担保とか大変になり、デバッグというか AI なのでデバッグをやりようがないんですよね。
憧れているけれども自由すぎて再現しにくい。自分の開発ならまだしもクライアントワークでの実用には課題が多かったです。
Mastra で AI エージェント開発をはじめる
そこで、ちゃんと AI エージェントを作りたいよねというところで、Mastra という TypeScript で書けるフレームワークを勉強・調査して採用することにしました。
The Typescript AI framework - Mastra
自然言語入力があって、Mastra の AI エージェントが自然言語のインタラクション、チャット機能、ツール選択、テンプレート出力みたいなところも結構できるので、前述の Claude の Artifact で実現できそうだなと確信が得られたといったところでスタートしてみた次第です。
Mastra は AI エージェントのバックエンドとして機能します。フロントエンドの表示部分には Vue や Vite といった別のフレームワークを使う構成です。
最初は非常に楽しかったんですよね。
やってみてわかった課題
ただやっていく中で結構つらいなーと感じるという部分はありました。
やはり開発を進めていく上で、AI エージェントにかなり自由に出力させる範囲を与えてしまうと結構整理が難しいんですよね。
- AI へ同じ入力内容でも異なる出力がでてくる（揺れる）
- 予期しないフォーマットで表示が壊れる
- エラーハンドリングの一貫性がない
- AI に任せるとプログラムと違って判断基準が不透明
- プロンプトで上手く出たり出なかったりする原因が自然言語ベースで特定しにくい
- AI の振る舞いが噛んでしまうとログ追跡が困難
AI が自由にやってしまうのでテストケースとか作るのは困難ですし、前のバージョンとの比較検証もしにくい。なので本番環境での問題再現も同じ言葉で話しかけても結果が異なるためデバッグ迷子になる。
AI エージェントをつくれるようにはできたが、かなり自由にやられてしまって制御ができない、みたいなところになりました。
現状の解決策：四層構造アーキテクチャ
そういう流れになってくると、やっぱり AI の設計を適切な大きさにする必要があるなと「めっちゃ」考えて、四層構造アーキテクチャを考案して、現在の仕組みに採用しました。
従来のビジネスロジック・API・UI といった部分を確実に動く部分としてやって、AI エージェントを加えたといったところになります。
ビジネスロジック層
アプリケーションのコアロジックを担当します。AI との会話から独立していて、テスト可能で再利用しやすい。
API 層（薄い API）
UI と AI エージェントからの統一の窓口です。HTTP でアクセスできる部分で、認証認可やバリデーションといった窓口業務を確実に行う。ほとんどビジネスロジックそのものを呼び出す形にして、非常に薄い層として設計しました。
UI 層
ロジックと対になる粒度の人間向けの操作画面です。Vuetify による Material Design で直感的に操作できるものを作って、API やビジネスロジックがちゃんと動くかの検証ができます。
AI エージェント層
自然言語の揺れをうまく吸収して API に案内する役割だけです。自然言語を構造化したデータに変換して、なるべく速やかに API に直接呼び出す。かなり区分けが、役割分けがしやすくなりました。
いろいろ良くなった
従来は AI エージェントが自然言語処理もツール選択もツール処理の計算も外部の連携も全部やってるようなことになっていたんですよね。Claude の Artifact に憧れたのなら AI に自由に任せるのは、それを投影した実装方針としては合っていたのですが、ただ、自分の開発しかりクライアントしかり AI エージェントであろうと「実装したものが確実に動作する」というのは大切なわけです。
こうやって要素に分けることによって、エージェントがやるところは自然言語の処理とツール選択という部分になりますし、それ以降は速やかにシステムの方、API とビジネスロジックの方に行くことになります。
AI が人間の言葉をシステムに案内するパートと、AI での揺れがなく確実に動くパート（ビジネスロジック・API・UI）がうまく分離できているところがポイントです。
この構造によっていろいろ良いところがあります。
- 開発が安定しやすい
- 各層が独立して開発テストができるようになりました。責務が明確になって保守がしやすくなる。
- AI の自己チェックがしやすい
- API 仕様が明確になったので、AI が正しい API を選択しているかの検証もしやすいですし、自動テストなどを回せばより良くなるでしょうね～。
- 人間も UI でチェックできる
- 今まで AI から叩かないと結果がもらえないような状況になっていましたが、UI から同じ機能が実行できます。これが地味に良いです。UI を操作することで人間がかなり視覚的に結果を確認できてデバッグしやすくなりましたね。というかこれで、かなりの完成度まで動作的にはにじり寄れる。安心。これはかなりポイントが高いですね。
- 今までの仕組みを活かせる
- UI・API・ビジネスロジックの段階でかなり動くといった状況になるので、あとは速やかに AI エージェントがツールを選択して API に繋げる部分に注力しやすくなるため、見通しもだいぶ良くなりました。
- AI による自由な挙動があると従来の仕組みって入れづらかったんですよ。読み込みだけならまだしも書き込みとか削除とか、結合したときに自由にやられたらめっちゃ怖いじゃないですか。既存の API とか UI を再利用できますし、後付けで追加するような関係性にもできるようになってきたのもうれしい気づきです。
たとえば
たとえば、カメラ画像を取得してくる AI エージェント例です。
カメラ画像の場合は、最新画像の画像取得と過去の画像取得を想定します。UI での表示の段階で、画像表示や過去の画像取得をどうするべきかの詰めを行います。
AI エージェントはこのように薄めに載せる。基本的に UI 層と同じ見せ方ですが、画像表示が AI エージェントの会話上で、通常の会話以外に必要になるので、その部分は追加開発をします。
ということで
2025 年 12 月時点での現在地としてAI エージェント開発で四層構造の仕組みで整理できたメモをまとめました。最近は、これでなんとか開発がうまく回り始めています。
そういえば AI との壁打ちの時点で Mastra だけでなくこういった AI エージェント作成ツールでも起きうる問題と聞きましたが、私は AI 併走とはいえコード書いて自分で挙動が追える Mastra とともに、こういった世界観を見れてよかったです。
ともあれ、まだまだブラッシュアップ中なので、また困難を越えて変わっていくこともありますし、AI エージェント周りの技術が進化して、より良いパターンが出てきて変わっていく部分もあると思います。
現時点のスナップショットとして残しておきます。