NeboAI
NeboAI
Comenzar

Aplicaciones

Una app es un empleado con una página. Los propietarios la abren en su propia ventana para ver algo y trabajar con ello directamente: un tablero, un registro, un formulario. La página es HTML y JavaScript simples, y se comunica con Nebo y con su empleado a través de un solo script, el App SDK.

El paquete

Una app es un paquete de empleado con un manifest.json que lo marca como app y una carpeta ui/ con la página.

<data>/user/agents/deal-board/
├── manifest.json     # marks the employee as an app
├── AGENT.md          # the employee behind the page
├── agent.json        # optional: sidecar tools, workflows
└── ui/
    ├── index.html
    └── app.js
{
  "id": "<minted UUID>",
  "name": "deal-board",
  "version": "1.0.0",
  "type": "app",
  "window": { "title": "Deal Board", "width": 900, "height": 700, "resizable": true },
  "permissions": ["storage:readwrite"]
}
CampoSignificado
type"app". Convierte al empleado en una app. Nebo también lee el antiguo artifact_type.
idUn UUID que se genera al crear la app. La página se sirve en /apps/<id>/ui/.
name, versionEl nombre del empleado y la versión del paquete.
windowtitle, width, height, resizable, fullscreen, orientation. Valores predeterminados: 1024 × 768, redimensionable, sin pantalla completa, vertical, con el nombre del empleado como título.
permissionsLo que puede hacer la página. Valor predeterminado: ["storage:readwrite"].

Permisos

PermisoConcede
storage:readwriteEl almacén de clave-valor de la app.
subagent:<employee-id>Preguntarle a otro empleado desde la página. El empleado de la propia app no necesita permiso.
network:<host> o network:*Solicitudes a hosts externos a través del proxy de Nebo.
device:motionEl giroscopio y el acelerómetro, solo para esta página. En iPhone, la página también llama a DeviceMotionEvent.requestPermission() a partir de un toque.

Cada permiso tiene la forma prefix:scope. Pide lo mínimo que necesite la app.

Pantalla completa, orientación e inclinación

Los juegos y las películas pueden ocupar toda la pantalla. Define fullscreen y, para la app móvil, una orientation: portrait (la predeterminada), landscape o any. Cualquier otra orientación se rechaza al escribir el manifiesto.

{
  "type": "app",
  "permissions": ["storage:readwrite", "device:motion"],
  "window": { "title": "Kart", "fullscreen": true, "orientation": "landscape" }
}
  • En el escritorio, la app se abre en una ventana de pantalla completa.
  • En la app móvil no hay barra de la app, las barras del sistema se ocultan, la pantalla se mantiene encendida y el gesto de deslizar para actualizar está desactivado. Una pequeña pastilla de Cerrar aparece en la esquina superior izquierda y se desvanece después de unos segundos; tocar cerca de la parte superior la hace volver. El gesto de deslizar desde el borde de iOS está desactivado, y el botón Atrás de Android recorre el historial de la página antes de cerrarla.
  • Agrega márgenes a la página con env(safe-area-inset-*) y viewport-fit=cover, y deja libre de controles la esquina superior izquierda.

El control de voz

Cada app que se abre en la app de escritorio de Nebo o en la app móvil muestra un pequeño control de voz en la esquina inferior derecha, para que el propietario pueda hablar con el empleado de la app mientras este trabaja en la página. El control está fuera de tu página, así que recargar la página nunca corta la llamada.

  • En el escritorio es una barra de unos 300 por 48 píxeles, a 16 píxeles de la esquina inferior derecha de la ventana.
  • En la app móvil es un botón redondo de 48 puntos dentro del área segura, que el propietario puede arrastrar a cualquiera de los dos lados. En una app de pantalla completa, se vuelve a contraer a ese botón unos segundos después de iniciar una llamada.
  • Deja libre de controles importantes la esquina inferior derecha.
  • Durante una tarea larga en una llamada, el empleado da actualizaciones breves como "Editando ahora." y nunca lee en voz alta nombres de archivos ni comandos.

Crea una app

Un empleado puede crear una app de dos formas, y elige según lo que diga el propietario. "Créame una app para mis pedidos" crea un nuevo empleado de app. "Tú eres la app" o "créate un juego" convierte en la app al empleado con el que habla el propietario: conserva su chat, su memoria y su personalidad, y su página se recarga mientras el propietario le habla. Esto también funciona con un empleado contratado durante la conversación. Cuando no queda claro a cuál se refiere el propietario, el empleado pregunta una vez.

update_employee(
  name: "<the employee's own name>",
  app: { window: { title: "Solitaire", fullscreen: true, orientation: "landscape" } },
  ui: { "index.html": "<!doctype html>..." }
)

Las herramientas del día a día (un registro, un formulario, un pequeño panel) se crean con la skill de apps integrada en Nebo. Una página que debe verse diseñada y no generada, como una página de inicio cinematográfica, una película que avanza con el scroll, arte generado o un juego, se crea con la skill App Studio de la tienda.

Para una app nueva, lo más sencillo es pedírsela a un empleado. Nebo incluye una skill integrada para crear apps, y el empleado usa create_employee, que escribe la carpeta, el manifiesto, la personalidad y la página en una sola llamada. La app aparece en la plantilla del propietario en cuestión de segundos.

create_employee(
  name: "deal-board",
  description: "A board of open deals, sorted by close date.",
  app: {
    window: { title: "Deal Board", width: 900, height: 700, resizable: true },
    permissions: ["storage:readwrite"]
  },
  ui: { "index.html": "<!doctype html>..." }
)

update_employee recibe los mismos argumentos ui, app y agent_md. Una ruta en ui reemplaza solo ese archivo. La página se lee del disco en cada solicitud, así que al recargar la ventana se ve el cambio.

Una página mínima

Esta página carga el SDK, pregunta quién es su empleado e imprime la respuesta. Si muestra el id y el nombre del empleado, la conexión está bien.

<!doctype html>
<html>
<head>
  <meta charset="utf-8">
  <title>Deal Board</title>
</head>
<body>
  <h1>Deal Board</h1>
  <pre id="who">loading...</pre>
  <script src="/sdk/nebo.global.js"></script>
  <script>
    NeboAppSDK.nebo.identity.get()
      .then(me => { document.getElementById('who').textContent = JSON.stringify(me, null, 2); })
      .catch(err => { document.getElementById('who').textContent = String(err); });
  </script>
</body>
</html>

El SDK obtiene el id de la app a partir de la dirección de la página. Una página servida desde cualquier otro lugar necesita <meta name="nebo-app-id" content="<id>">. Guarda el estado en el almacenamiento de la app, no en la página: la ventana se cierra, pero el almacenamiento se conserva.

Cómo se sirve la página

  • Nebo sirve ui/ en /apps/<id>/ui/ y la abre en su propia ventana.
  • Una ruta sin archivo correspondiente recurre a index.html, así que el enrutamiento del lado del cliente funciona.
  • Las páginas HTML reciben las etiquetas meta nebo-app-id y nebo-base-url.
  • Cada archivo se envía con su tipo de contenido real, incluidos video, sonido, fuentes, wasm y modelos 3D (glb, gltf). Un archivo con una extensión desconocida se envía como application/octet-stream y el navegador no lo usará.
  • Los archivos responden a solicitudes de rango (206, o 416 para un rango más allá del final), así que el video y el audio se pueden adelantar o retroceder. En la app móvil, el video se reproduce en su lugar sin necesidad de tocarlo: <video muted playsinline autoplay loop poster="assets/hero.jpg" src="assets/hero.mp4"></video>
  • Un archivo cuyo nombre lleva un hash del contenido, como main-0a8ksftt.js, se guarda en caché durante un año. Todo lo demás, incluido index.html, se comprueba cada vez que se abre y responde 304 si no cambió. Compila con nombres con hash en lugar de renombrar archivos a mano.
  • Cada archivo de la página puede pesar como máximo 10 MB.
  • Borrar la carpeta desactiva al empleado; delete_employee lo quita por completo.

Agrega un sidecar

Cuando la página necesita lógica del servidor, sus propios datos o herramientas que el empleado pueda llamar, agrega un sidecar: un binario que Nebo ejecuta junto a la app. La página llega a él con neboFetch y una ruta relativa. Consulta Sidecar de apps.

Publica desde Nebo

Una app que creó el propietario puede publicarse sola. El propietario dice "publícate", o toca Publicar en el chat de la app, en la pantalla de la app en la app móvil (en la barra superior, o como una pastilla junto a Cerrar en una app de pantalla completa), o elige Publicar esta app… en el menú de escritorio (el menú Archivo en macOS mientras una ventana de app está al frente; el menú App de la ventana de la app en Windows y Linux). El empleado redacta la ficha a partir de la app, toma de 3 a 5 capturas de pantalla y muestra la ficha en el chat para ajustarla conversando. No se envía nada hasta que el propietario responde Enviar a revisión en la tarjeta, con un toque o por voz.

Una app que creó el propietario siempre tiene sus herramientas de desarrollo para sí misma: recargar, estado, consola, capturas de pantalla y publicación. El modo Desarrollador de apps (Configuración del bot, Desarrollador) permite que otros empleados trabajen en cualquiera de las apps del propietario, agrega una consola flotante a la página y desactiva la caché. Las apps instaladas desde la tienda nunca reciben herramientas de desarrollo ni un botón Publicar.

Publica una app tú mismo

Una app que solo tiene página se publica como un único paquete con la herramienta agent. El frontmatter de AGENT.md debe decir artifact_type: app; de lo contrario, la tienda crea un empleado normal sin página. Pon entre comillas cualquier valor que contenga dos puntos seguidos de un espacio; sin comillas, el frontmatter no se puede leer y la app se convierte, sin avisar, en un empleado normal.

---
name: deal-board
description: "A board of open deals: sorted by close date, with a chat that knows each deal."
artifact_type: app
metadata:
  version: "1.0.0"
---
# Deal Board

You work beside the Deal Board app. ...
agent(action: "create", name: "deal-board", version: "1.0.0",
      description: "A board of open deals, sorted by close date.",
      manifestContent: "<contents of AGENT.md>")
agent(action: "bundle-token", id: "<app id>")

zip -r deal-board.zip deal-board -x '*/.git/*' '*/node_modules/*' '*/src/*'
curl -X POST "https://neboai.com/api/v1/skills/<app id>/bundle" \
  -H "Authorization: Bearer <token>" \
  -F file=@deal-board.zip

agent(action: "submit", id: "<app id>", version: "1.0.0")
En el zipQué pasa
AGENT.mdLa personalidad y el manifiesto de la ficha.
agent.jsonLa configuración del empleado. {} es suficiente.
manifest.jsonSe conserva como manifiesto de la app: la ventana y los permisos llegan a la app instalada. Debe ser JSON válido.
ui/La página. Se permiten: html, css, js, mjs, ts, jsx, tsx, json, map, txt, md, imágenes (png, jpg, gif, svg, webp, avif, ico, bmp), fuentes (woff, woff2, ttf, otf), sonido (mp3, wav, ogg, m4a, aac, flac, opus), video (mp4, webm, mov, m4v), wasm, glb, gltf, pdf. Los archivos que empiezan con punto y node_modules/ se descartan.
skills/<name>/Las skills propias del empleado, revisadas igual que una skill subida por separado: se conserva SKILL.md, scripts/ y bin/ admiten cualquier tipo, y todo lo demás debe estar en la lista permitida de skills.
  • Límites: 10 MB por archivo y 50 MB por paquete. Un archivo de más de 10 MB se omite (revisa filesSkipped y uiFilesStored en el resultado); un paquete de más de 50 MB se rechaza.
  • El token de subida dura 5 minutos. Si el zip tiene una sola carpeta superior, se elimina.
  • En una app privada o solo para canales, cada subida reconstruye al instante el paquete instalable, y Nebo les avisa a los bots que instalaron la app. Un bot en línea coloca el paquete reconstruido de inmediato; uno sin conexión lo hace la próxima vez que se conecte. No necesitas subir la versión para esto, y se conservan la configuración, las programaciones y los datos del propietario para la app. Las apps públicas, no listadas y solo por invitación conservan su paquete aprobado hasta que una nueva versión pase la revisión.
  • Una nueva versión sigue la configuración de actualizaciones automáticas que cada propietario tenga para la app. Está desactivada a menos que el propietario la active, así que de forma predeterminada el bot muestra "Actualización disponible" y el propietario la aplica desde Configuración, luego Actualizaciones, o desde la Bandeja de entrada. Una actualización nunca concede permisos nuevos; un permiso que agrega la nueva versión se solicita la primera vez que la app lo necesita.
  • Si NeboAI retira una app de la tienda, cada bot que la instaló la desactiva y se lo avisa al propietario. No se borra nada: se conserva todo lo que guardó la app.
  • Una app con sidecar, en cambio, sube el binario de cada plataforma con binary-token, y la página como un archivo ui. Consulta Sidecar de apps y Publicación.