エージェントがファイルを書き換えて止まった。
チャット履歴を開くと「このファイルを修正します」という宣言と、書き換え後のコードが残っている。
「どのツールが呼ばれたのか」「ツールが何を返したのか」「なぜそこで止まったのか」——その情報はどこにもない。
Claude CodeやOpenAI Codexを実務で使ったことがあるエンジニアなら、この詰まり方に覚えがあると思います。
チャット履歴は エージェントの意図の記録 であって、実行の記録ではありません。
Apache Maka（Incubating）は、この区別を設計の出発点に置いているプロジェクトです。
モデルメッセージ・ツール呼び出し・ツール結果・権限決定・終了イベント——5種類のイベントを追記専用ログに書き残す設計が、エージェントの監査と運用をどう変えるか。
ローカルで実際に起動して RuntimeEvents を読むところまで、順を追って見ていきます。
エージェントが「何かした」後に、あなたは何を追えますか
分散システムの開発をしていると、「ログのない障害調査は不可能」が肌感覚として分かるようになります。
サービスが落ちたとき、まずトレースを引っ張り出して、どのコンポーネントがどのタイミングで何を受け取り何を返したかを時系列で確認する。
その手順が当たり前になった頃から、AIエージェントの「ログのなさ」がじわじわ気になり始めました。
チャット履歴はビューです。
LLMが「このファイルを修正しようとしていた」という意図の記録ではありますが、「実際にどのツールが呼ばれ、そのツールが何を返し、なぜそこで止まったか」という実行の記録ではありません。
Claude Codeは完成度の高いコーディングエージェントですが、ツール呼び出しの記録をセッション終了後に体系的に参照できる構造にはなっていません。
Codexも同様で、「どの権限決定がいつ行われたか」を後から確認しようとすると、記録がないか、再現できない形でしか残っていないことがほとんどです。
この問題が見えにくい理由の一つは、エージェントツールの進化が「何ができるか」に集中してきたからだと思っています。
ファイル操作・Web検索・コード実行——できることを増やす競争の中で、「実際に何をしたか後から追える設計」の優先度が下がった。
分散システムでいえば、機能を作り続けてオブザーバビリティを後回しにする、あのパターンに近いです。
「エージェントが勝手に何かした」と感じる体験のほとんどは、実は「何が起きたか確認できない」だけだったりします。
後追いの手段がないせいで、実際には正しい動作でも「勝手にやられた感」だけが残る。
Makaはこの問題を 設計の問題として 扱っています。
チャット履歴を補完するのではなく、実行の記録として別のレイヤーを最初から持つ——その判断が、以降のすべての設計の土台になっています。
Makaのログ設計：追記専用ログに「状態遷移のすべて」を書く
Makaが記録するイベントは5種類に整理されています。
- モデルメッセージ：LLMが生成した応答の内容。後からどんな推論が行われたかを確認できる
- ツール呼び出し：どのツールが・どんな引数で呼ばれたか。実行の意図と入力値が記録される
- ツール結果：ツールが返した値。成功・失敗・エラー内容がすべて残る
- 権限決定：どのツール呼び出しにどの権限が付与されたか。「なぜそれが許可されたか」が追える
- 終了イベント：そのターンが「完了」「中断」「失敗」のどれで終わったか、理由とともに記録される
この5つが、追記専用（append-only）のログとして書き続けられます。
既存のレコードは上書きしない。
これはイベントソーシングと同じ原則で、「状態を直接持つのではなく、状態遷移のイベント列を持つ」という発想です。
イベントを順に再生すれば任意の時点の状態を復元できるため、「あの瞬間にエージェントが何を見ていたか」を後から再構築できます。
運用ストアは runtime.sqlite の一本です。
RuntimeEvents テーブルにイベントが積まれていき、セッションメタデータや実行状態もすべてここに集約されます。
バックアップの検証には SHA-256 チェックサムが使われており、復元前に SQLite のメタデータと突き合わせる仕組みになっています。
「バックアップが本物かどうか」を機械的に確認できる——これは地味ですが、長期運用を考えると重要な設計の選択です。
「チャット履歴はビューであり、ログが実体である」——この一文がMakaの設計思想を端的に表しています。
チャット画面で見えているものはログから生成されたビューに過ぎず、実際の記録はイベントの連鎖として別に積まれている。
この構造があることで初めて、まともな障害調査と権限監査ができるようになります。
ローカル起動の前提と、ログの読み方
現時点では macOS Apple Silicon と Windows に対応しています。
Linux はまだ未対応なので、手元の環境を先に確認してください。
Maka は TypeScript / Electron ベースのデスクトップアプリです。
リポジトリの取得は次のコマンドでできます。
git clone https://github.com/apache/maka.git
cd maka
その後の依存パッケージのインストール・ビルド・起動の手順は、公式リポジトリの README を確認してください。
Incubating 段階のプロジェクトなので手順の変化が速く、ここで特定のコマンドを固定して示すより、README を都度参照する方が確実です。
Node.js 環境が前提になるので、事前にバージョンを確認しておくと詰まりにくいです。
起動してエージェントにタスクを与えると、ツール呼び出しが発生するたびにイベントが runtime.sqlite の RuntimeEvents テーブルに追記されていきます。
このファイルはローカルマシン上に置かれ、クラウドには送信されません。
ログの確認は sqlite3 CLI から直接できます。
まず PRAGMA でテーブルの構造を把握してから読み進めるのがスムーズです。
-- テーブルのカラム構造を確認する（実際のカラム名はここで把握する）
PRAGMA table_info(RuntimeEvents);
-- 全イベントを時系列で取り出す
SELECT * FROM RuntimeEvents ORDER BY rowid ASC;
カラム名や値の形式は実際のスキーマで確認するのが前提です。
PRAGMA table_info の結果を見てから絞り込みクエリを組む、という順番で進めてください。
イベントレコードを読む際は、まず 終了イベント から確認するのがおすすめです。
「そのターンが完了で終わったのか、失敗で終わったのか」が最初に分かると、その後のツール呼び出しとツール結果の流れを「どこに問題があったか」という目線で読み直せます。
各イベントの詳細はペイロード（JSON形式）として格納されている構造が多く、ツール名・引数・返り値・エラー内容・権限の種類などが入っています。
SQLite の json_extract 関数で必要なフィールドだけ取り出すと、大量の JSON をざっと眺めるより読みやすくなります。
ログがあると、運用のどこが変わるか
実務でいちばん差が出ると感じるのは 障害調査 の場面です。
エージェントが5ステップのうち3ステップで止まった——この状況をログなしで調べようとすると、チャット履歴と最終的なファイルの状態しか手がかりがありません。
「3番目あたりでおかしくなったのかな」という推測から始まり、ほぼ再現実験頼みになります。
再現できなければ原因を特定できず、原因が特定できなければ直せない——という詰まり方を経験したことがある方は少なくないはずです。
Maka の終了イベントには「ターンがどう終わったか・なぜ止まったか」が記録されています。
そこを起点にツール呼び出しとツール結果を時系列でたぐると、「どのツールがどのエラーを返したか」まで特定できる起点が生まれます。
再現実験に頼らずに仮説が立てやすくなる——デバッグの入り口そのものが変わります。
それと地味に重要なのが、 権限決定の記録 です。
チームでエージェントを使い始めると、「あれ、なんであのディレクトリに書けたんだっけ」という疑問が必ず出てきます。
ログがなければ「エージェントがそう判断したから」で終わるしかない。
権限決定イベントには、どのツール呼び出しにどの権限が付与されたかが残ります。
何か問題が起きたときに「この操作にこの権限が付与されていた」という事実に後から戻れる——これは機密プロジェクトの運用において想像以上に効きます。
Maka の ローカルファースト 設計は、この権限記録とセットで意味を持ちます。
runtime.sqlite はあなたのマシンにある。
クラウドに送信されないし、セッションデータが外部に出ません。
「エージェントが何をしたかのログが、どこかのクラウドに残っているかもしれない」という懸念を持たずに使えます。
社内のコードや機密データに触れるタスクを任せるときの判断材料として、これは無視できない要素です。
Maka はまだ Incubating の早期段階です。
本番ワークロードに投入する前提で評価するプロジェクトではないので、その点は率直に書いておきます。
ただ、実際に動かしてみると気づくことがあります。
イベントソーシングの原則——状態を直接持つのではなく、状態遷移のイベント列を持つ——をエージェントに適用するだけで、「あの瞬間に何が起きていたか」を後から再構築できるようになる。
エージェントにこの構造を最初から持たせているプロジェクトはまだ少なく、その設計を手元で動かしながら確かめておくことは、自分のプロジェクトにエージェントを組み込むときの判断に、じわじわと効いてくると思っています。
株式会社ホコサキは山口県宇部を拠点に、AI活用支援・業務システム開発・DX推進に取り組んでいます。
エージェントの導入から「後から追える状態での運用設計」まで、実務に即した形でご支援します。
気になることがあれば お問い合わせ からお気軽にどうぞ。