打造 AI Agent 系統，從可靠但無聊的基礎建設開始

在建構 AI Agent 系統時，我們常陷入一個迷思：必須設計一套複雜的跨程序通訊（IPC）機制。然而，許多專案的第一個錯誤，並非做得太少，而是一開始就把溝通層想得太重。本文將從一個 macOS AI 工作區的實例出發，論證一個反直覺的觀點：真正可落地、可維護的 Agent 基礎設施，往往源於檔案、PTY、事件監聽這些枯燥但極度可靠的 primitives。先把可驗證性與可維護性做好，遠比追求華麗的即時通訊協定更重要。

為什麼我們該重新思考 Agent 的溝通方式？

當我們談論讓應用程式與 AI 代理（Agent）互動時，直覺反應通常是建立一個專屬的通訊協定。工程師的腦中可能會浮現 gRPC、WebSocket，或是自訂的 socket 連線，用以處理即時、雙向的資訊交換。這些技術當然很強大，但它們也帶來了對應的複雜性：版本控制、錯誤處理、連線管理，以及最重要的——大幅增加的除錯與測試成本。

然而，一個由日本開發者 ruri 所設計的 macOS AI 工作區 Aidea，為我們提供了一個截然不同的思路。這個專案的目標是讓 AI Agent（此例中為 Claude）能像一個「夥伴」一樣在本地端運作，並與主應用程式無縫溝通。面對這個需求，設計者沒有選擇任何現代化的 IPC 框架，反而回歸到作業系統最古老、最穩定的兩種機制：檔案系統與虛擬終端機（Pseudoterminal, PTY）。

Aidea 如何用「檔案」與「終端機」實現雙向溝通？

Aidea 的設計精妙之處在於，它將應用程式與 AI Agent 之間的雙向溝通，拆解成兩個獨立、單向且極其簡單的流程。這套方法幾乎不需要撰寫任何專屬的通訊層程式碼，而是完全依賴作業系統提供的現成工具。

其核心思想是將雙向溝通拆分為兩個獨立的單向流程。首先，在應用程式向 Agent 傳遞指令時，主應用程式會透過一個虛擬終端機（Pseudoterminal, PTY）向 AI Agent 發送指令。PTY 是類 UNIX 系統中一個歷史悠久的機制，它能模擬一個物理終端機，讓一個程式（主應用程式）能像使用者在命令列中輸入文字一樣，與另一個程式（AI Agent）互動。這意味著從 Agent 的角度來看，它只是在標準輸入（stdin）讀取指令，這是一種最自然、最容易測試的互動模式。

其次，當Agent 需要回傳結果給應用程式時，這部分是設計的巧思所在。AI Agent 完成任務後，它並非透過 PTY 將結果「印」回給主程式，而是將結果寫入一個位於指定目錄下的檔案。主應用程式則利用 macOS 內建的 FSEvents API 來監聽該目錄的變化。一旦 FSEvents 偵測到新檔案寫入，便會觸發事件，通知主應用程式前來讀取。這個 API 從 Mac OS X 10.5 開始就已存在，非常成熟穩定。

這個設計的本質是：Agent 只需要學會如何寫檔案，應用程式只需要學會如何監聽檔案系統事件。兩者之間沒有直接的耦合，溝通的「狀態」被物化成一個個可供檢視的檔案。

這套「原始」設計的實務優勢在哪？

選擇如此「低科技」的方案，並非技術上的倒退，而是一種務實的權衡。它帶來了幾個在複雜系統中至關重要的好處，讓開發者能更專注於 Agent 本身的核心邏輯，而非底層通訊的繁瑣細節。

極高的可驗證性與可除錯性

這是最顯著的優點。當 Agent 的行為不如預期時，我們可以直接檢查那個「信箱」目錄。Agent 產生的每個檔案都是一次完整的溝通紀錄。我們可以手動 `cat` 檔案內容，確認格式是否正確；甚至可以手動建立一個檔案，來測試主應用程式的反應。相較於需要透過 network sniffer 或複雜日誌系統才能追蹤的 IPC 封包，這種基於檔案的溝通方式，讓除錯變得像在檔案總管裡點擊一樣簡單，大幅降低了開發與維護的門檻。

優異的解耦與可維護性

Agent 與應用程式之間是完全解耦的。Agent 的核心任務被簡化為「接收指令，寫出檔案」，它不需要知道誰在監聽、也不用處理任何連線狀態。未來若要替換 Agent 的實作（例如從 Claude 換成另一個模型），只要新的 Agent 同樣遵守寫檔案的約定即可，無需修改通訊層。同樣地，應用程式端也可以輕易地擴充或修改，而不用擔心破壞與 Agent 之間的通訊協定，這為系統的長期演進提供了極大的彈性。

內建的持久化與可靠性

所有溝通都被自動記錄下來。如果應用程式在處理 Agent 回傳的結果時當機，那個檔案依然靜靜地躺在硬碟上。重啟後，程式可以輕易地重新處理這些未竟之事。這種由檔案系統提供的持久化能力，是許多記憶體內 IPC 機制需要額外開發才能實現的。雖然檔案 I/O 的延遲（通常在數毫秒等級）高於記憶體通訊，但在許多 Agent 工作流中，這點延遲相對於模型本身的推論時間幾乎可以忽略不計，使得系統在面對意外情況時更具韌性。

誠然，這套架構不適用於需要微秒級延遲的高頻率交易等場景。但對於絕大多數 AI Agent 的應用——例如程式碼生成、文件整理、任務規劃——來說，其可靠性與簡單性所帶來的好處，遠遠超過了它在效能上的微小犧牲。正如許多成熟的系統設計原則所強調的，我們應該先追求系統的正確性與可維護性，再依實際瓶頸進行優化。在 AI Agent 的世界裡，這意味著先建立一個你可以信任、可以輕易驗證的溝通基礎，而不是一開始就跳進一個華麗但難以捉摸的黑盒子裡。

延伸閱讀

• Aidea の設計シリーズ、第2章：ファイルと PTY を API チャンネルにする
• Apple Developer Documentation: File System Events
• Martin Fowler: The Architectures of AI Systems

我是江中喬，專注於 AI Agent Architecture、Memory Governance 與 Cognitive Diversity，持續研究如何打造能夠長期協作、可信任且可治理的 AI 系統。