
初めてAgentのメイン経路を通したとき、最も難しい部分はもう終わったと思っていた。
モデルは呼び出せ、データはDBに保存でき、ベクトルは検索でき、ワークフローも最後まで問題なく進んだ。LangGraphで初めて完全なプロジェクトを作る身としては、それだけでしばらく興奮できるものだった。
しかし実際に連続して使い始めると、問題が次々と出てきた。checkpointを設定しているのに、次のラウンドでモデルは前のラウンドに何が起きたのか分からない。ワークフローは細かく分割されているのに、状態には保存する必要のない中間生成物が詰め込まれている。データベースにはかなりの情報が保存されているのに、モデルが受け取るコンテキストが役に立つとは限らない。
さらに辛かったのは、製品要件が変わるたびに、まず既存アーキテクチャがなぜこの要件をあまりサポートしていないかを説明し、それから何とか押し込む方法を考える必要があったことだ。
その後、書き直すことにした。
議論しやすいように、以下ではプロジェクトの具体的な業務を伏せ、継続的にコンテキストを蓄積し、複数ターンの対話をサポートする会話Agentとして扱う。この記事でも技術スタックを並べるつもりはなく、むしろ本当に自分が詰まったところと、それらの問題がAgent開発に対する自分の理解をどう変えたかを話したい。
一、ワークフロー状態をモデルの記憶と勘違いしていた
最初のアーキテクチャは比較的長いPipelineだった。業務オブジェクトを読み込み、基礎資料を整理し、検索queryを構築し、情報を検索し、コンテキストを組織し、最後にモデルを呼び出す。
ノード間でデータを渡しやすくするため、途中で生成されたもののほぼすべてをGraph Stateに入れた。検索結果、検索query、組み立て途中のコンテキスト、さらにはSQLAlchemyのORMインスタンスまで詰め込んだ。
当時の理解は単純だった。Stateとはノード間で共有されるデータだろう?入れておけば次のノードでそのまま取れる、なんて便利なんだ。
checkpointを接続するまで、問題は起きなかった。
まずシリアライズだ。ORMインスタンスは普通の辞書のように、当時のcheckpointシリアライズ経路にそのまま渡すことはできない。次に永続化の範囲。今回の実行だけで使う一時データの多くも、状態と一緒に保存されてしまった。
最初の修正方法は、最後のノードで中間フィールドをクリアすることだった。その後気づいた。checkpointは実行過程で状態を記録するので、最後に一度クリアしても、それ以前に書き込まれたスナップショットを消すことはできない。
しかしこれが最大の罠ではなかった。
連続した追加質問をサポートするため、2ラウンド目で1ラウンド目に保存したコンテキストをそのまま再利用し、時間のかかる構築プロセスを省きたいと考えた。同じthread_idを設定してからGraphを呼び出したが、結果としてモデルは前のラウンドを見たことがないかのようだった。
経路をよく見ると、原因は実に明白だった。状態は復元されたが、モデルを呼び出すときに新しいHumanMessageを1つ構築しただけだった。履歴情報はStateの中に横たわっていて、今回のリクエストに組織されていないので、モデルに見えるはずがない。
さらにひどいことに、2ラウンド目の入力で、コンテキストフィールドに空文字列を渡していた。本来は「今回は再計算しない」という意味にしたかったのだが、実際の効果は空値で既存の状態を上書きしてしまった……
この後で、ようやくいくつかのことを本当に分けて考えるようになった。
| データ | システム内での役割 |
|---|---|
| ノード内部の一時変数 | 現在のステップを完了するため、使い終わったら破棄してよい |
| Graph State | ノード間で受け渡し、必要に応じて復元する実行状態 |
| メッセージ履歴 | 複数ターンの対話で保持する必要がある会話内容 |
| 今回のモデル入力 | 現在のタスクが実際に消費する必要がある情報 |
checkpointは実行状態の復元を助けるが、どの内容がモデル入力に入るかは依然として自分で設計する必要がある。逆に、Stateが大きくても、毎回のリクエストが必ず多くのtokenを消費するわけではない。これらの内容をモデルに送って初めて、入力コストになる。
この区別は基本的に見えるが、自分は実際に一度失敗して初めて理解した。
ノードの分割も見直した。以前はほぼ1関数につき1 nodeに分割し、その後もう一方の極端に走って、チェーン全体を1つのnodeに詰め戻したこともあった。続けていくうちに、ノード境界は実行要件に従うべきだと気づいた。独立して観察する必要があるステップ、分岐ルーティング、並列スケジューリングが必要なステップは切り出す価値がある。局所的にしか使わない変換ロジックは、普通の関数で十分だ。

二、モデルの処理が遅いのは、自分が難しすぎる問題を出していることもある
初期の入力経路の一つは、スクリーンショットから構造化レコードを復元する必要があった。
モデルに各メッセージの発話者、内容、時間を識別させ、厳密なJSONに整理するよう要求した。精度を上げるため、ユーザーにも多くの制限を加えた。スクリーンショットを順番にアップロードすること、時間を含めること、枚数を制限することなどだ。
結果は理想的ではなかった。ある試行では、2枚のスクリーンショットの処理に約2分かかり、それでも時間の混乱、発話者のずれ、無効な内容が存在した。
最初の反応はもちろんpromptをさらに調整することだった。しかし最終的な用途をもう一度見て、突然気づいた。自分は元の記録を1件も漏らさず復元する必要はないのだ。
下流が本当に必要としているのは、この材料がどんなテーマを中心にしているか、保持する価値のある情報は何か、そしてそれらがどんな文脈で起きたかだ。
そこでデータの粒度を「1件ずつの元記録」から「1つのテーマを中心に組織された情報」に調整した。モデルは完全な記録復元のタスクを負わなくなり、後続の検索も大量の断片的なメッセージから意味を再構築する必要がなくなった。
もちろん、この方案には当時コストもあった。ユーザーが一度に提出する材料はできるだけ同じテーマに属するよう要求し、分段作業の一部をユーザーに返した形だ。処理負担は軽減したが、入力体験を完全に解決したとはまだ言えない。
この出来事から、モデルを最適化する前にまず2つの質問をする習慣がついた。最終機能は一体どんな情報を必要とするのか?今モデルに要求している出力の粒度は、実際の用途を超えていないか?
データベースが元の記録を収められるからといって、モデルがそれを1件ずつ再構築しなければならないわけではない。モデルが複雑な構造を出力できるからといって、製品がユーザーにその構造を埋め終わるまで待たせる必要があるわけではない。
三、コンテキストの難点は「保存する」から「今回どう使うか」へ
最初に記憶を作ったとき、私の注意は主に書き込み側にあった。資料をどう抽出するか、データをどうモデリングするか、テキストをどうベクトル化するか。
その後、Markdownでコンテキストを組織するいくつかの方案に触れ、情報の分類と表現に参考になる点が多くあると分かった。しかし私が試した方案の中には、一部のファイルは毎回必ず読むことを要求し、他のファイルは必要に応じて全量ロードするものもあった。
資料が少ないときは、これはとても直接的だ。資料が徐々に増えると、毎回ほんの一部の情報しか必要ないのに、まずファイル全体をロードしなければならないのではないかと心配になり始めた。
そこで再構築の際、基礎資料は残し、より細かい情報を独立した条目に分割し、後続で問題に応じた検索をサポートした。ここでは、データベースが条目帰属、分類、時間を管理し、テキスト内容がモデルに理解させる意味を表現する。
しかしベクトル検索があっても、問題が自動的に消えるわけではない。
初期の検索は主に意味距離に依存していた。その後、業務範囲フィルタ、重要度重み、一部情報の時間減衰を徐々に加えた。なぜなら「問題とよく似ている」と「現在の回答に適している」は同じことではないからだ。
特に時間。
かつてはシステムプロンプトに「現在時間」を置くだけだったが、その後、それでは履歴メッセージがそれぞれいつ起きたかを説明できないと気づいた。さらに上流を見ると、データベースに作成時間があっても、抽出後のテキストが元資料の年、時期、段階を失っていれば、モデルは異なる時間に起きた類似の事柄を混同しやすい。
後の調整は2つの部分に分かれた。会話メッセージには明示的にタイムスタンプを付ける。情報を抽出するとき、資料中で確認できる時間アンカーを本文に残し、確定できない時間は補完しない。
これは単に並び替え式を調整するより前の話だ。時間情報が抽出時に失われたら、検索段階でゼロから取り戻すのは難しい。
また、知識検索をToolとしてカプセル化し、モデルにいつ資料を補足する必要があるかを判断させ、毎回機械的に検索一式を走らせるのを避けることも試した。
しかしTool Callは別の境界も露呈した。モデルは現在の業務オブジェクトのIDを安定して生成できない。このIDはすでにシステム実行コンテキストにあるのに、モデルにもう一度推測させる必要があった。
最後に、ツール実行前に現在のコンテキストで確定済みのパラメータを注入した。モデルは検索が必要か、何を検索するかを決められる。現在のユーザーが誰か、どのオブジェクトを操作しているか、アクセス権があるかは、プログラムが確定し検証すべきだ。
これらの問題をこなして、コンテキストに対する理解は「できるだけ多く集める」から徐々に、現在のタスクのために必要な情報を保持し、それを適切な形でモデルに入れるへと変わった。
各変更がどれだけ効果を上げたかについては、十分に体系的な評価データがないので、ここでパーセンテージをでっち上げたくない。確認できるのは、どの経路に沿って調査すべきかが分かり始め、最終回答だけを見てプロンプトを調整することにこだわらなくなったことだ。
四、ディレクトリを分けたからといって、本当に分離したわけではない
以前Webプロジェクトを作るとき、まずバックエンドを書き、次にHTTPインターフェースを包み、最後にフロントエンドから呼び出すのが習慣だった。このAgentも最初は似た構造を踏襲し、業務能力とWebサービスを近くに置いていた。
その後、製品は主にIMで対話するようになり、さらにCLIを追加して設定、管理、診断操作を実行するようにした。ここまで来ると、業務層がWebフレームワークに依存し続けるのは非常にぎこちなく感じられた。
そこでServiceを切り出し、業務とデータアクセス能力を担わせ、異なる入口から呼び出すようにした。
聞くだけならもう分離しただろう?現実はまた一発食らった。
あるときCLIのヘルプコマンドを実行したら、出力されたのはWebフレームワークのヘルプだった。
原因は、コマンドモジュールがServiceをインポートし、ServiceがトップレベルでWebフレームワークのRequest型をインポートしていたことだ。本来は型注釈にすぎないのに、実行時にフレームワーク全体を引き込み、コマンドライン引数の解析に影響した。
修正は複雑ではない。純粋な型依存をTYPE_CHECKINGの下に移し、コマンド登録段階はできるだけ軽量に保ち、実際に実行するときに必要なモジュールをロードする。
しかしこの小さな出来事で気づいた。アーキテクチャ図上の依存矢印は、最終的にモジュールのインポートと初期化動作に落とし込まれる。きれいに見えるServiceでも、インポートするとフレームワークを引き込み、引数を読み、外部接続を起動するなら、別の入口から呼び出したときに同じ問題が起きる。
その後、ユーザー設定を簡素化するため、一部のデータ能力をリモートに置くことも試した。以前ORMオブジェクトを取得していた場所は、明確な戻り構造を消費するように変え、入口とGraphに散在するデータベース操作も引き続きServiceに集約する必要があった。
統一ディスパッチ層を追加した。ローカルモードはServiceを呼び、リモートモードは対応するHTTP APIを呼ぶ。シリアライズもこの境界で処理し、enum、時間オブジェクト、オプションパラメータの変換が各所に散らばるのを避けた。
例えば省略されたクエリパラメータは、Python関数でNoneを渡すのは自然だが、HTTP queryエンコードでは直接エラーになることがある。修正はリクエスト境界に収めるべきで、同時に0、Falseといった実際に意味のある値は保持する。JSONリクエストボディ内の明示的なnullもついでに削除してはいけない。
これらは複雑なアルゴリズムではないが、「ローカルで呼べる関数」が信頼できるリモートインターフェースになれるかどうかを決める。
五、ユーザーがデータベースを1つ設定しなくて済むと、システムは責任を1組多く負う
CLIとIM入口を作ったのは、最初は独立フロントエンドの開発量を減らし、ユーザーが慣れた場所で対話できるようにするためだった。
しかしインストールフローをつなげてみると、自分はフロントエンドを省いただけで、ユーザーは依然としてデータベース、モデル設定、ボット設定を準備しなければならないと気づいた。コードが動いても、ユーザーが使いたいと思うまでにはまだ長い道のりがある。
そこでサーバー側にデータベースアクセスを引き受けさせ、ユーザーが自分でDBを構築する負担を減らすことを試みた。
最初の制約は明確だった。便利さのために、共有データベースの接続資格情報をクライアントに送ってはいけない。通常のデータ操作は認証APIで引き受けられるが、ワークフローのcheckpointはデータベース接続に依存しており、HTTPルートを追加したからといって自動的にリモートストレージ能力を得るわけではない。
当時の処理は2つの動作を残すことだった。ローカルモードは引き続きPostgreSQLでcheckpointを永続化し、実験的な共有モードはプロセスメモリに切り替える。
コストも明確だ。プロセス再起動後、共有モードのこの部分の短期記憶は失われる。
この問題を完全に解決したわけではなく、クライアントにデータベース接続を露出しない実行方式と引き換えに、ある種の降格を受け入れただけだ。checkpointが永遠にリモート化できないという意味でもなく、当時のそのディスパッチ層ではカバーできず、さらに抽象化するコストがその回の目標を超えていただけだ。
さらに面倒な問題はその後にあった。
一部の「データ同期」に見えるServiceは、内部で実際にモデルを呼び出す。それをサーバー側に移すと、一体誰のモデル設定を使うのか?ユーザーの設定はどう渡すのか?呼び出しコストは誰が負担するのか?
以前は単一マシン内で、データベース、モデル設定、実行環境が同じ場所にあり、これらの問題は見落とされやすかった。ネットワークを越えると、每一项を改めて答えなければならない。
ログイン状態も同じだ。バックグラウンドタスクがtoken期限切れで中断されるのを減らすため、一度は有効期限を設定しない方式を採用した。しかしそれが残すローテーション、失効、無効化ガバナンスの問題は依然として存在し、メイン経路が動き続けるからといって認証設計が完全だとは言えない。
最終的に、共有モードの一部経路はすでに通したが、公開設定入口は隠した。モデル設定の帰属とサーバー側代理実行の境界がきれいに処理されていないなら、ユーザーにそれを準備済みの選択肢として扱わせるべきではない。
これも製品レベルでの転換だった。使用コストを下げるということは、誰かが元々ユーザーに渡していた複雑さを引き受けるということだ。データベースをユーザーが設定しなくてよくなれば、サーバー側が相応の権限、設定、実行責任を引き受ける必要がある。「Easy Mode」は、入力欄をいくつか表示しないだけでは済まない。

六、一度のプロンプトサービス障害で、実行依存を見直した
もう一つの教訓は、モデル能力とはほとんど関係がなかった。
調整を容易にするため、プロンプトを外部プラットフォームに置き、実行時にリアルタイムで取得していた。プロンプトを修正しても再リリース不要で、開発体験は確かによかった。
そしてプラットフォームサービスが故障した。
ローカルバックアップも残しておらず、読み取り失敗時のフォールバックも設計していなかったため、プロンプトに関わる経路が一気に全部落ちた。外部サービスは約2日後に復旧したが、この2日で十分に気づかされた。自分は開発便利ツールを、実行時のハード依存にしてしまっていたのだ。
この出来事から得た教訓は具体的だ。プロンプトはテキストの一部だが、システム内では実際の実行ロジックを担っている。そのバージョン、バックアップ、可用性は真剣に扱う必要がある。リモート管理に置いても、これらの責任が消えるわけではない。
その後の開発過程で、私は繰り返し現れる協業上の要件をSkillとして蓄積するようになった。変更後の品質チェック、変更履歴の記録、Graphドキュメントの同期、そして軌道修正をルールに書き戻すことだ。
これらの規程はテストの代わりにはならず、Agentが毎回正しく実行されることを保証するものでもない。しかし少なくとも、同じ種類の漏れが再び発生したとき、私はただもう一度注意を促すだけでなく、継続的に消費されるルールを修正する機会を得られる。
最後に
振り返ってみると、今回の書き直しは、ある日すべての問題を理解して新しいアーキテクチャ図を描き、一気に完成させたものではない。
私はまずcheckpointを誤解し、それから状態を再設計した。まず細粒度の入力を追求し、それから下流が実際に必要とするセマンティクスに戻った。まず業務層を分割し、不要なエントリを削除し、その後新しいデプロイ方式のためにHTTPサービスを再び追加した。新しい問題は絶えず現れ、以前に行った選択も見直される。
私はもはや「当初フレームワークの選択を誤ったのではないか」と特に悩むことはない。私を本当に遠回りさせたのは、いくつかのより基礎的な境界をはっきりさせていなかったことだ。何を永続化する必要があるのか、何をモデルに入れる必要があるのか、どのパラメータをプログラムが決定するのか、そしてある機能が実行位置を変えたとき、どのような責任を一緒に持っていくのか。
今、新しい機能を書き始めるとき、私は以前より少し多くの時間をかけてこれらの問いを突き詰める。それらは必ずしも一度で正しくできるようになるわけではないが、一見すでに完成したように見えながら、別のシナリオではまた書き直さなければならないコードを少なく書けるようにしてくれる。
今回の書き直しについて、私が最も残しておきたい成果は、おそらくこれらの、今後も私のコードの書き方に影響し続ける問いそのものだ。