agent-draw

エージェントファーストのテクニカルキャンバス。人間はtldrawキャンバスを配置・検査し、エージェントはレンダラーに依存しないバージョン管理されたグラフドキュメントを読み取り・パッチします。

Alpha: ドキュメント境界は意図的なものです。プラグインSDKと互換性の保証はまだ進化中です。

最初の垂直スライスには以下が含まれます：

• API、サービス、データベース、テーブル、ファイル、外部システムのブロックを備えたtldrawベースのテクニカルキャンバス；

• データベース所有権、サービス読み取り、外部キー参照のための検査可能なテーブル列とセマンティックエッジ；

• 名前付き入出力ハンドルと型付きスナップ接続を備えたカスタムReactノードシェイプ；

• 安定したID、セマンティックエッジ、名前付きビュー、ケイパビリティ、前方互換性のある拡張機能を備えた標準agent-draw/0.1 JSON；

• 楽観的リビジョンチェック付きのagent-draw-patch/0.1オペレーション；

• 名前空間化されたノードタイプと宣言されたケイパビリティを備えたビルド時プラグイン登録；

• ガード付きローカルケイパビリティランタイムを通じてHTTPリクエストを編集・実行するAPIインスペクター；

• JSONインポート/エクスポートとブラウザローカル永続化；

• エージェント作成の読み取り、インポート、接続提案、楽観的パッチのためのTypeScript CLIおよびstdio MCPサーバー。

実行方法

要件：Node 20+ と pnpm。

pnpm install
pnpm dev

http://127.0.0.1:4173 を開きます。キャンバスランタイムは127.0.0.1:4174のみで待ち受け、Viteが/apiをそこにプロキシします。

ヘッダーのサンプルピッカーを使用するか、サンプルを直接開きます：

• /?sample=system-map

• /?sample=agent-loop

• /?sample=plugin-system

• /?sample=openapi-projects

pnpm test
pnpm typecheck
pnpm build

Related MCP server: tldraw MCP Server

エージェントワークフロー

1. UIから.agent-draw.jsonドキュメントをエクスポートするか、プロジェクトから読み取ります。

2. IDと未知のextensionsフィールドを保持します。

3. ドキュメント全体を書き換えるよりも、小さなagent-draw-patch/0.1提案を優先します。

4. baseRevisionをソースドキュメントのリビジョンに設定します。

5. セマンティックフィールドはレイアウト（setLayout）とは別に変更します。

6. 適用前に検証します。古いパッチは最新のリビジョンに対して再生成する必要があります。

サンプルパッチとフォーマットリファレンスを参照してください。

CLIはキャンバスで使用されるのと同じモデルオペレーションを公開します：

pnpm agent-draw validate path/to/map.agent-draw.json
pnpm agent-draw import-openapi openapi.yaml -o map.agent-draw.json
pnpm agent-draw connect map.agent-draw.json \
  --source service-api/calls \
  --target database-projects/query \
  -o connection.agent-draw-patch.json
pnpm agent-draw apply map.agent-draw.json connection.agent-draw-patch.json --write

MCPサーバー

pnpm mcpはTypeScript stdioサーバーを実行します。MCPクライアントをプロジェクトに向け、AGENT_DRAW_ROOTでファイルアクセスを制限します：

{
  "mcpServers": {
    "agent-draw": {
      "command": "pnpm",
      "args": ["--dir", "/absolute/path/to/agent-draw", "mcp"],
      "env": { "AGENT_DRAW_ROOT": "/absolute/path/to/your/project" }
    }
  }
}

最初のツールセットは意図的にグラフレベルです：read_document、list_plugins、propose_connection、apply_patch、import_openapi。Agentツールを参照してください。

セキュリティモデル

ダイアグラムファイルにはケイパビリティ参照が含まれ、資格情報は含まれません。ホストがケイパビリティの付与を所有します。MVP HTTPランタイム：

• 明示的なHTTPメソッドのみをサポート；

• localhost、プライベート、リンクローカル、.local、埋め込み資格情報、リダイレクト、非HTTPスキームをブロック；

• 入力/ボディサイズ、レスポンスサイズ、期間を制限；

• 人間がリクエストを実行を押した後にのみ実行。

これは有用なベースラインであり、本番グレードのネットワークサンドボックスではありません。デプロイ版では、実行の分離、接続時のDNS再解決、スペースごとの許可リストの追加、監査可能な付与の保存も行うべきです。

アーキテクチャ

src/modelがソース・オブ・トゥルースです。src/canvasAdapter.tsはtldrawアダプターです。src/pluginsにはマニフェストとセマンティックヘルパーが含まれます。src/runtimeはブラウザクライアントで、serverは信頼されたローカルケイパビリティランタイムです。

キャンバスはReact Flowの有用なインタラクションセマンティクス（可視ハンドル、互換性のあるエンドポイント、型付き接続）を借用していますが、2つ目のシーングラフは採用していません。tldrawが選択、カメラ、空間変換、レンダリングを所有します。標準のAgent DrawドキュメントがノードID、ポート、エッジ、リビジョンを所有します。UIジェスチャーは、CLIとMCPサーバーが使用するのと同じagent-draw-patch/0.1提案に変換されます。

プラグイン境界は、宣言的マニフェスト、フロントエンドサーフェス、制限付きホストケイパビリティの間のBBの有用な分離を借用しています。tldrawストアをプラグインコントラクトとして公開しないことを意図的に選択しています。

設定可能性の方向性

現在のブロックはインプロセスのTypeScriptプラグインです。次のステップとして、標準モデルを弱めることなくほとんどのブロックを宣言的にすることを意図しています：

1. ブロックスキーマ： マニフェストがフィールド、ポート、デフォルト、外観、互換性のある関係を宣言します。

2. 生成インスペクター： ホストがそのスキーマから通常のフィールドエディターをレンダリングします。プラグインは、真に特殊化されたインタラクションのためだけにカスタムReactパネルを提供します。

3. インポーターとアダプター： SQL/ORM/OpenAPI/リポジトリースキャナーが外部システムを、来歴付きの安定したノードとパッチに変換します。

4. ホストケイパビリティ： ブロックはコネクターまたはシークレットIDを参照し、信頼されたホストが資格情報を所有し、ランタイムアクションを承認します。

5. Agentツール： MCPはUIと同じスキーマカタログとパッチオペレーションを公開するため、エージェント作成のダイアグラムは検査・レビュー可能なままです。

これにより、一般的なブロックにはローコードの道が提供され、API実行、ライブデータベース検査、その他のリッチなユーティリティのための型付きエスケープハッチが維持されます。