ツールではなくファイル:仮想ファイルシステムとbashでエージェントを構築した方法
Files over tools: how we built our agent with a virtual filesystem and bash (knock.app)
要約
Knockは、顧客メッセージングリソースを管理するAIエージェント「Knock Agent」を構築しました。このエージェントは、仮想ファイルシステムとbashを活用して、APIツールに依存する従来のアプローチよりもスケーラブルな設計を実現しています。ファイルシステムを通じてコンテキストを取得し、bashスクリプトで操作を行うことで、より柔軟で効率的なエージェント開発が可能になりました。このアプローチは、既存のCLIツールとの親和性も高く、Elixirエコシステム内で開発されました。
全文翻訳
ファイル対ツール:仮想ファイルシステムとbashでKnock Agentを構築した方法
2026年3月、私たちはKnock Agentをリリースしました。これは、Knockで全ての顧客メッセージングリソースを管理するためのAIエージェントです。ワークフロー、テンプレート、オーディエンスの作成・更新、ユーザーのセグメンテーション支援、顧客メッセージングのパフォーマンスに関する質問への回答が可能です。エージェントは、Knockダッシュボード、接続されたSlackワークスペース、API、またはMCPサーバーから呼び出すことができます。
この記事では、bash、仮想ファイルシステム、そして当社の管理APIを使用して、エージェントのアーキテクチャをどのように設計し、構築したのかを裏側から見ていきます。
エージェントのビジョンの定義
私たちのビジョンは、Knockダッシュボードからアクセスできる全てを管理できるエージェントを作成することでした。エージェントには、企業のデザインシステムを使用し、トーン・オブ・ボイスに合わせ、顧客メッセージングのデータモデリングを理解してほしいと考えていました。
このビジョンを実現するために、Knockアカウント内のデータ全体にアクセスし、メッセージ作成や質問応答の際にそのコンテキストを使用できる、リッチなエージェントハーネスを作成する必要がありました。
最初のプロトタイプは、ワークフローのみを対象に動作するように構築しました。これは、その仕組みに関する多くのニュアンスを持つ、深いドメインです。私たちは「ツール・パー・タイプ」パターンを使用しました。各ツールは、ワークフローに遅延ステップを追加したり、ビジュアルブロック言語を使用してメールテンプレートを構築したりするなど、当社の管理APIのプリミティブを公開しました。ツールの説明には、そのツールを扱う上での特殊性がエンコードされ、例が示されていました。ツールの入力は、フィールドタイプと必須項目を記述していました。
このアプローチは機能し、良好な結果をもたらしましたが、このアプローチはスケーリングしないことに気づきました。管理APIのリソースごとにツールを公開することになり、より洗練されたツールルーティングレイヤーを実装したり、エージェントが使用するスクリプト言語を導入したりしない限り、コンテキストウィンドウが肥大化してしまうからです。
より少ないツール、より多くのファイル
私たちはVercelチームによるブログ記事「How to build agents with filesystems and bash」を見つけました。この記事では、彼らの内部データツールであるd0のエージェント構築について説明しています。ファイルシステムがエージェントが必要なコンテキストを発見するための優れた方法であり、ドメインをファイルシステムにマッピングしてこのコンテキストレイヤーを強化できると説明しています。
Knockでは、以前からCLIを持っており、チームはメッセージングテンプレートやコンポーネントなどのKnockリソースをプルダウンし、ファイルシステム経由でローカルで操作できます。
ここでのアイデアはシンプルでした。管理APIをミラーリングするツールを公開する代わりに、エージェントにアカウントの内容を持つファイルシステムと、そのファイルシステム上でスクリプトを作成するためのbashを使用する機能を提供します。これにより、エージェントはファイルシステムを探索してコンテキストを収集し、必要に応じて効率的にスクリプトを作成するためにbashを使用できます。
エージェントがワークフローやテンプレートの編集を行いたい場合、ファイルシステム内のファイルをインプレースで変更し、Knockにコールバックしてその変更を永続化します。
このパターンは、他の製品内アシスタントよりもClaude Codeやその他のコーディングエージェントに近く、CLIやローカルファーストのアプローチで顧客メッセージングを維持するという、私たちが既に確立した哲学に合致しています。
エージェントのためのbash、Elixirで
2025年のホリデーシーズン中、VercelのMalteはjust-bashをリリースしました。アイデアはシンプルでした。Linuxイメージを起動することなく、エージェントにUnixファイルシステムとbash環境を持たせることです。実際には、エージェントが呼び出すことができる仮想ファイルシステムを備えた、TypeScriptでの仮想bash実装を作成することを意味しました。
Knockは、Elixirエコシステムに強く根ざした企業です。私たちは独自の仮想化されたbashインタプリタを求めていました。選択肢は、1) エージェントで行った作業を放棄し、TypeScriptで再構築するか、2) ライブラリのバージョンをElixirにポートするか、でした。
幸いなことに、just-bashのようなライブラリは、エージェントにとって再現可能なターゲットです。明確に定義されたサーフェスエリアと、サポートするコマンド(jq、ls、catなど)を網羅する徹底したテストスイートを備えています。これらは、私たちのElixirポートがそのまま再利用するフィクスチャです。
史上最高のナードスナイプの一つで、私たちはエージェントに傾倒したKnockの友人、Ivar Vongにこれを試してもらうことにしました。多くのトークンを費やした後、彼は包括的なテストスイートと堅牢なセキュリティモデルを備えた、Elixirでの完全なbashインタプリタと仮想ファイルシステムを開発しました。彼はこれをjust-bashと名付けました。
なぜサンドボックスではないのか?
明白な質問です。なぜエージェントに仮想ファイルシステムではなく、サンドボックス経由で完全なコンピュータを提供しないのか?結局のところ、それを強化するために選ぶことができるベンダーはいくつかあります。
現段階では、完全なサンドボックスは私たちのシンプルなニーズには過剰であると信じています。サンドボックスの起動は、仮想インメモリオプションと比較してパフォーマンスコストがかかり、アプリ外で行われたコンテンツや変更に関する同期の問題がより難しくなり、現時点ではそれらを先送りしたかったのです。
複雑さがスケールを傾けるようであれば、この決定を再検討します。エージェントが記述するためのbash以外の(Pythonのような)完全なスクリプト言語を追加することが、決定要因になるかもしれません。私たちは「手と脳を分離する」という原則に従っており、実際のサンドボックスへの移行は、仮想のものへの呼び出しを実際の呼び出しに置き換えるだけです。
連携
just-bashをElixirで利用可能にし、全てのビルディングブロックを揃えたところで、ファイルシステムベースのエージェントを組み立てました。
[画像: Knock Agentのアーキテクチャ図。エージェントループ、サンドボックスプロセス、仮想ファイルシステム、管理APIを示している]
私たちは、Anthropic API上で直接、タスクに応じて異なるモデルを使用して、典型的なエージェントループを実行しています。そのエージェントループは、優れたElixirライブラリであるObanを使用して、ステップを安全にリトライできる耐久性のあるワークフローによってバックアップされています。ObanはPostgresに状態を保存しています。
エージェントセッション内では、just-bashインスタンスと完全な仮想ファイルシステムを含むサンドボックスをアタッチします。サンドボックスは、私たちにとってはElixirクラスタ内で実行される別のプロセスにすぎません。サンドボックスは、リクエストが最初にファイルシステムを使用する必要があるときに遅延して開始されます。これにより、ファイルシステムを必要としないリクエストは、最小限のフットプリントで迅速な応答を返します。
既存のサンドボックスプロセスが実行されていない場合、ファイルシステムはアカウント内のオブジェクトのメタデータでブートストラップされます。これにより、エージェントは必要なリソースの完全なカタログを持つことができますが、エージェントがそれらを操作する必要がある前に、完全でより大きなリソースを遅延ロードできます。
ファイルシステムは以下のようになります。
|- account.json # アカウントコンテキスト
|- channels.json # 利用可能なチャネルのセット
|- workflows.json # アカウント上のワークフローの完全なリスト
|- ... # 他の多くのリソース
エージェントが特定のワークフローやテンプレートを探索したい場合、load_resourcesツールを呼び出すことで、それらをバルクでファイルシステムにロードするように要求できます。
workflows/
some-workflow/
workflow.json # ワークフローの設定(ステップ、設定など)
steps/
email_1/
template.html # メールステップのメッセージテンプレート
in_app_1/
template.md # インアプリステップのメッセージテンプレート
サンドボックスプロセスは長寿命であるため、後続のターンではこのコンテンツがロードされ、操作の準備ができています。これは、ワークフローやメッセージテンプレートの一連の更新を行うために、エージェントと繰り返しやり取りするマルチターン会話に最適です。
エージェントが操作するために、いくつかの追加ツールを公開しています。
bash– bashコマンドを実行します。read_file– ファイルシステムからファイルを読み取ります(catより推奨)。edit_file– ファイルに対してターゲットを絞った編集を行います(文字列xをyに置換)。write_file– ファイル全体をファイルシステムに書き込みます。upsert_resource– ファイルシステム上のリソースに加えられた変更をKnockに永続化します。
ファイル操作以外の注目すべきツールはupsert_resourceツールです。これは、仮想ファイルシステムに保存されたバンドルを読み取り、管理APIと同じ内部メソッドを呼び出すことで、ファイルシステム上の変更をKnockアカウントに永続化します。
エージェントループは、受信したプロンプト、実行したアクション、送信した応答の完全なイベントログを生成します。このイベントログはメモリにバッファリングされ、エージェントの実行中に非同期でPostgresストアに書き込まれます。イベントログは、コンテキストを保持するために後続のターン用に圧縮・フォーマットされます。NDJSONストリームを使用して、フォーマットされたログを接続されたクライアントにストリーミングします。
エージェントに新しいスキルを教える
エージェントが管理できる最初のドメインはワークフローとテンプレートでしたが、Knockの全てを扱えるようにしたいと考えていました。
当初、ワークフローとテンプレートに関する全ての製品情報をシステムプロンプトに入れていましたが、これはスケーリングしないことがわかっていました。代わりに、リソース固有の情報をエージェントが「学習」できるスキルに移動し、リソースを編集する前にそれらのスキルを読むようにエージェントを誘導しました。
各スキルには、エージェントがそのリソースを扱う上でのニュアンスを理解するために必要な情報と、避けるべき一般的な落とし穴が含まれています。スキルはファイルシステム上で利用可能であり、呼び出し時にシステムプロンプトに組み込まれるため、エージェントは利用可能なスキルの全範囲を把握できます。
skills/
workflows/
SKILL.md # トップレベルのスキル定義
references/
template-editing.md # テンプレート編集のための特定のスキル参照
broadcasts/
...
guides/
...
エージェントが新しいスキルを学習したい場合、skillツールを呼び出します。これにより、スキルの完全なメタデータが取得され、エージェントのコンテキストウィンドウに追加されます。また、エージェントがスキルに従っているかを評価・監視する便利な方法が提供されます。
同様の方法で顧客定義スキルも導入したため、スキルはシステム定義と顧客定義の混合が可能であり、それぞれが発見のためにシステムプロンプトにロードされ、アクセス用にファイルシステムにロードされます。
ツール対CLI
Knockアカウント内の全てのデータが静的ファイルとして表現するのに適しているわけではありません。例えば、Knockが生成するロギングデータです。これは、エージェントが実行時にクエリを実行してスコープ付きログのページを取得するのが最も適しています。
Knock内の全てのAPIをエージェントに公開するためにさらに多くのツールを導入する代わりに、カスタムコマンド(knock)としてCLIをエージェントに導入しました。これは、just-bashインスタンスに登録されています。
[画像: Knock Agent CLI。利用可能なコマンドのリストとその使用方法を示している]
これで、エージェントがAPIログ(またはデバッグ支援のためのワークフロー実行ログ)をクエリしたい場合、knock api_logs listまたはknock messages listを呼び出すことができます。デバッグスキルを通じてエージェントにCLIの操作方法を教えますが、CLIは各リソースに対して--helpコマンドを公開しているため、エージェントは最小限の指示で高い成功率で操作を学習することが容易です。
可観測性と評価
あらゆる本番システムと同様に、エージェントが何を行っているか、どのように動作しているかについての優れた可視性と、その動作を確認するためのテストスイートを求めていました。
可観測性については、標準的なOpenTelemetry形式でエージェントループからトレースを生成します。これらのトレースをHoneycombとBraintrustの両方に転送します。Braintrustはエージェントセッションのより深い分析に役立ち、Honeycombはサービストレースの定番です。
評価(evals)の面では、Anthropicによる優れた記事「Demystifying evals for AI agents」で共有された洞察に基づいて、自社開発の評価システムを構築しました。私たちの評価は、軌跡を測定し、結果が1つ以上の期待されるプロパティまたは形状を持っているかを確認し、LLMをジャッジとして使用して出力をスコアリングします。評価は毎晩実行し、一般的なタスクにおけるエージェントの精度を保証するためにpass^kで測定します。
将来の改善
このファイルシステムベースの基盤の上に、エージェントへの投資を継続していくことを楽しみにしています。検討中の将来の改善点には以下が含まれます。
- 長時間実行されるエージェントセッションのための、より良いコンパクションの導入。 現在、いくつかの単純なメカニズムがありますが、エージェントが長期的なタスクに取り組めるように、セッション要約ロジックを洗練させたいと考えています。
- 評価の範囲と深さの向上。 当初は最も一般的な操作に焦点を当てていましたが、特に複雑なワークフローの構築と編集に関して、評価にさらに多くのケースを追加することを検討しています。
- 集中した作業のためのサブエージェントの検討。 サブエージェントがコンテキスト収集、分析、およびメインエージェントループ外のその他の個別のタスクをどのように処理できるかを評価しています。
私たちのファイルシステムバックドエージェントは、エージェントの機能を拡張していく上での堅実な基盤を提供します。ファイルシステムを効率的なコンテキスト取得メカニズムとして使用することで、本番環境でお客様が要求している複雑なタスクを実行できるインテリジェントなエージェントをリリースすることができました。既にAPI、Slack、MCPサーバーから呼び出せるようにエージェントのサーフェスを拡張しており、将来的にはさらに多くの機能を追加していく予定です。