agent-draw

Un lienzo técnico orientado a agentes. Los humanos organizan e inspeccionan un lienzo de tldraw; los agentes leen y aplican parches a un documento de grafo versionado e independiente del renderizador.

Alpha: el límite del documento es deliberado; el SDK de plugins y las garantías de compatibilidad aún están evolucionando.

El primer corte vertical incluye:

• un lienzo técnico basado en tldraw con bloques de API, servicio, base de datos, tabla, archivo y sistema externo;

• columnas de tabla inspeccionables y aristas semánticas para la propiedad de la base de datos, las lecturas de servicio y las referencias de clave foránea;

• formas de nodo React personalizadas con conectores de entrada/salida con nombre y conexiones tipadas y magnéticas;

• JSON canónico agent-draw/0.1 con IDs estables, aristas semánticas, vistas con nombre, capacidades y extensiones compatibles con versiones futuras;

• operaciones agent-draw-patch/0.1 con comprobaciones optimistas de revisión;

• registro de plugins en tiempo de compilación con tipos de nodo con espacio de nombres y capacidades declaradas;

• un inspector de API que edita y ejecuta peticiones HTTP a través de un runtime de capacidades local protegido;

• importación/exportación JSON y persistencia local en el navegador;

• una CLI de TypeScript y un servidor MCP stdio para lecturas, importaciones, propuestas de conexión y parches optimistas creados por agentes.

Ejecución

Requisitos: Node 20+ y pnpm.

pnpm install
pnpm dev

Abre http://127.0.0.1:4173. El runtime del lienzo escucha solo en 127.0.0.1:4174 y Vite redirige /api hacia él mediante proxy.

Usa el selector de ejemplos de la cabecera, o abre un ejemplo directamente:

• /?sample=system-map

• /?sample=agent-loop

• /?sample=plugin-system

• /?sample=openapi-projects

pnpm test
pnpm typecheck
pnpm build

Related MCP server: tldraw MCP Server

Flujo de trabajo del agente

1. Exporta un documento .agent-draw.json desde la interfaz o léelo del proyecto.

2. Conserva los IDs y los campos extensions desconocidos.

3. Prefiere una propuesta pequeña agent-draw-patch/0.1 a reescribir el documento completo.

4. Asigna a baseRevision la revisión del documento de origen.

5. Cambia los campos semánticos por separado del diseño (setLayout).

6. Valida antes de aplicar. Un parche desactualizado debe regenerarse con la última revisión.

Consulta el parche de ejemplo y la referencia de formato.

La CLI expone las mismas operaciones de modelo que usa el lienzo:

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

Servidor MCP

pnpm mcp ejecuta el servidor stdio de TypeScript. Apunta un cliente MCP al proyecto y restringe su acceso a archivos con 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" }
    }
  }
}

El primer conjunto de herramientas es deliberadamente a nivel de grafo: read_document, list_plugins, propose_connection, apply_patch e import_openapi. Consulta Herramientas de agente.

Modelo de seguridad

Los archivos de diagrama contienen referencias a capacidades, nunca credenciales. El host posee las concesiones de capacidades. El runtime HTTP del MVP:

• solo admite métodos HTTP explícitos;

• bloquea localhost, direcciones privadas, link-local, .local, credenciales incrustadas, redirecciones y esquemas no HTTP;

• limita los tamaños de entrada/cuerpo, el tamaño de la respuesta y la duración;

• solo se ejecuta después de que la persona pulse Ejecutar petición.

Es una base útil, no un sandbox de red de nivel de producción. Una versión desplegada también debería aislar la ejecución, volver a resolver el DNS en el momento de la conexión, añadir listas de permitidos por espacio y almacenar concesiones auditables.

Arquitectura

src/model es la fuente de verdad. src/canvasAdapter.ts es el adaptador de tldraw. src/plugins contiene los manifiestos y los ayudantes semánticos. src/runtime es el cliente del navegador; server es el runtime de capacidades local de confianza.

El lienzo toma prestadas las útiles semánticas de interacción de React Flow —conectores visibles, extremos compatibles y conexiones tipadas— sin adoptar un segundo grafo de escena. tldraw es el responsable de la selección, la cámara, las transformaciones espaciales y el renderizado. El documento canónico de Agent Draw es el responsable de los IDs de nodo, los puertos, las aristas y las revisiones. Un gesto de la interfaz se traduce en la misma propuesta agent-draw-patch/0.1 que utilizan la CLI y el servidor MCP.

El límite de plugins toma prestada de BB su útil separación entre un manifiesto declarativo, superficies de frontend y capacidades acotadas del host. Intencionadamente no expone el almacén de tldraw como contrato de plugin.

Dirección de configurabilidad

Los bloques actuales son plugins TypeScript ejecutados en el mismo proceso. El siguiente paso previsto es hacer que la mayoría de los bloques sean declarativos sin debilitar el modelo canónico:

1. Esquema de bloque: los manifiestos declaran campos, puertos, valores predeterminados, apariencia y relaciones compatibles.

2. Inspector generado: el host renderiza editores de campos normales a partir de ese esquema; los plugins solo proporcionan paneles React personalizados para interacciones realmente especializadas.

3. Importadores y adaptadores: los escáneres de SQL/ORM/OpenAPI/repositorios traducen los sistemas externos a nodos y parches estables con procedencia.

4. Capacidades del host: los bloques hacen referencia a IDs de conectores o secretos, mientras que el host de confianza posee las credenciales y aprueba las acciones en tiempo de ejecución.

5. Herramientas de agente: MCP expone el mismo catálogo de esquemas y las mismas operaciones de parche que la interfaz, de modo que los diagramas creados por agentes sigan siendo inspeccionables y revisables.

Esto proporciona a los bloques comunes una vía de low-code y, al mismo tiempo, conserva vías de escape tipadas para la ejecución de APIs, la inspección de bases de datos en vivo y otras utilidades más completas.