メインコンテンツまでスキップ

エージェントによるワークフロー

Neatフレームワークの公開APIは、単に人間が作成するアプリケーションだけでなく、開発者の代わりにModalixを対象としたコードを作成するAIコーディングエージェントのために設計されています。このページでは、フレームワークの設計におけるいくつかの選択が、なぜ現在の形になっているのかを説明します。それは、人間だけでなく、APIを使用するエージェントにとって最適化されているためです。

エージェントがフレームワークから必要とするもの​

見慣れない API を使用してコードを生成する AI エージェントには、通常、以下のものが必要です。

  1. 小さな公共スペース — 種類が少ないほど、覚えることが少なくて済みます。
  2. 自己記述型 — 型シグネチャは、単にその内容を示唆するだけでなく、契約内容を明示的に記述する必要があります。
  3. 物事を達成するための方法の一つ — 複数の同等の選択肢がある場合、エージェントが誤った選択をしてしまうのは、まさにそのような状況です。
  4. 関連ドキュメント — エージェントは、8000行の設計ドキュメントではなく、@brief の短いドキュメントを読みます。重要なコンテキストは、そのシンボルのすぐ隣に配置する必要があります。
  5. 決定的な出力 — エージェントがテストスナップショットを書き込む際、バイト単位での決定性により、それらは安定したものになります。
  6. 根本原因を特定するエラー — 何らかの処理が失敗した場合、エラーメッセージには「グラフの構築に失敗しました」とだけ表示するのではなく、どのカーネル／コントラクト／オプションに問題があるのかを具体的に示す必要があります。
  7. 再現用アーティファクト — エージェントのコードがエラーになった場合、デバッガーにrepro_gst_launch文字列を貼り付けて、エージェントを再実行せずに反復処理を行うことができます。
  8. 隠れたグローバル変数は使用しない — すべての動作は、コンストラクターの引数または Node のオプションとして定義し、ランタイム時に読み込まれる環境変数として定義してはいけません。
  9. 安定した識別子 — 同じノードとオプションを使用すると、同じ要素名になり、同じ起動文字列が生成され、結果として安定したテスト環境が実現されます。
  10. モデルアーカイブをコードではなくデータとして扱う — モデルは、エージェントがコンパイルする必要があるヘッダーではなく、フレームワークが読み込む一連のデータである。
  11. 組み合わせ可能な構成要素 — ノード、モデル、および再利用可能なグラフフラグメントを相互に接続できます。どの組み合わせをフレームワークがサポートするかをエージェントが事前に把握する必要はありません。プランナーがビルド時に判定します。
  12. ビルド時の厳格な検証 — エラーが以下から発生します Graph::build()最初ではありません。 pull()エージェントの反復処理ループでは、エラーが発生した正しい行を特定する必要があります。
  13. 構造化されたGraphReport — ビルドの実行結果をプログラムで取得できるようにすることで、エージェントが自身の作業を検証できるようになります。
  14. 段階的な情報開示 — Model は最も簡単な方法であり、Graph::add() は次に適用するもので、カスタムノードはより高度な方法です。エージェントはまず、最も簡単な方法を試します。
  15. バージョン管理された MPK 契約 — モデルアーカイブには十分なメタデータが含まれているため、それに基づいてコードを生成するエージェントは、外部ドキュメントを参照する必要がありません。

これらは、フレームワーク全体にわたって具体的な設計上の決定事項として現れます。

  • エージェントがアプリケーションコードを学習するために必要なのは、小さな公開されたインターフェース（モデル、テンソル、サンプル、ノード、グラフ、および実行）だけです。
  • Graph::describe() は、構造化された計画の概要を返します。これにより、エージェントは自身のパイプラインを検証できます。
  • NeatError には、error_code() と GraphReport が含まれており、エージェントはコードを有効にすることができます。
  • Node::backend_fragment() は決定的な処理を行います。エージェントは、パイプラインに対して、期待される結果を示すテスト（ゴールデン文字列テスト）を作成できます。
  • MpkContract は、モデルに関する唯一の信頼できる説明であり、モデルに基づいて配線コードを生成するエージェントは、これ以外に何も必要としません。

アプリケーション開発者がどのようにメリットを得られるか​

たとえあなたがエージェントでなくても、エージェントにとって使いやすい API デザインの恩恵を受けることができます。自動化されたコード生成を信頼できるものにする要素は、手動によるコードレビューを容易にし、リファクタリングをより安全にし、AI を活用した開発（Claude Code、Copilot、Cursor など）を Modalix のコード上でより効率的にします。

さらに詳しく知りたい場合は​

  • 「Neatをご紹介します」— デザインの詳細な解説、第0.1節。
  • Graph::describe() — プログラムによる計画概要。
  • NeatError — 構造化されたエラータイプ。
  • Model — モデルアーカイブを読み込み、MPK契約を解析しました。