NeboAI
NeboAI
Começar

Apps

Um app é um funcionário com uma página. Os proprietários o abrem em uma janela própria para ver algo e trabalhar com isso diretamente: um quadro, um acompanhamento, um formulário. A página é HTML e JavaScript simples e conversa com o Nebo e com o seu funcionário por um único script, o App SDK.

O pacote

Um app é um pacote de funcionário com um manifest.json que o marca como app e uma pasta ui/ com a 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". Transforma o funcionário em um app. O Nebo também lê o antigo artifact_type.
idUm UUID gerado quando o app é criado. A página é servida em /apps/<id>/ui/.
name, versionO nome do funcionário e a versão do pacote.
windowtitle, width, height, resizable, fullscreen, orientation. Padrões: 1024 × 768, redimensionável, sem tela cheia, retrato, com o título igual ao nome do funcionário.
permissionsO que a página pode fazer. Padrão ["storage:readwrite"].

Permissões

PermissãoConcede
storage:readwriteO armazenamento de chave-valor do app.
subagent:<employee-id>Perguntar a outro funcionário a partir da página. O próprio funcionário do app não precisa de permissão.
network:<host> ou network:*Requisições a hosts externos pelo proxy do Nebo.
device:motionO giroscópio e o acelerômetro, somente para esta página. No iPhone, a página também chama DeviceMotionEvent.requestPermission() a partir de um toque.

Toda permissão tem o formato prefix:scope. Peça o mínimo de que o app precisa.

Tela cheia, orientação e inclinação

Jogos e filmes podem ocupar a tela inteira. Defina fullscreen e, para o app de celular, uma orientation: portrait (o padrão), landscape ou any. Qualquer outra orientação é recusada quando o manifesto é gravado.

{
  "type": "app",
  "permissions": ["storage:readwrite", "device:motion"],
  "window": { "title": "Kart", "fullscreen": true, "orientation": "landscape" }
}
  • No desktop, o app abre em uma janela de tela cheia.
  • No app de celular não há barra do app, as barras do sistema ficam ocultas, a tela não apaga e o puxar para atualizar fica desativado. Uma pequena pílula Fechar fica no canto superior esquerdo e some depois de alguns segundos; um toque perto do topo a traz de volta. O gesto de deslizar pela borda do iOS fica desativado, e o botão Voltar do Android percorre o histórico da página antes de fechar.
  • Adicione margens à página com env(safe-area-inset-*) e viewport-fit=cover, e mantenha os controles longe do canto superior esquerdo.

O controle de voz

Todo app aberto no app de desktop do Nebo ou no app de celular mostra um pequeno controle de voz no canto inferior direito, para que o proprietário possa falar com o funcionário do app enquanto ele trabalha na página. O controle fica fora da sua página, então recarregar a página nunca derruba a chamada.

  • No desktop, é uma barra de cerca de 300 por 48 pixels, a 16 pixels do canto inferior direito da janela.
  • No app de celular, é um botão redondo de 48 pontos dentro da área segura, que o proprietário pode arrastar para qualquer lado. Em um app de tela cheia, ele volta a ser esse botão alguns segundos depois do início da chamada.
  • Mantenha os controles importantes longe do canto inferior direito.
  • Durante uma tarefa longa em uma chamada, o funcionário dá atualizações curtas, como “Editando agora.”, e nunca lê em voz alta nomes de arquivos ou comandos.

Criar um app

Um funcionário pode criar um app de duas formas e escolhe de acordo com o que o proprietário diz. “Crie um app para os meus pedidos” cria um novo funcionário de app. “Você é o app” ou “crie um jogo para você mesmo” transforma o funcionário com quem o proprietário está falando no app: ele mantém o chat, a memória e a persona, e a página dele recarrega enquanto o proprietário conversa com ele. Isso também funciona para um funcionário contratado em uma conversa. Quando não está claro o que o proprietário quer, o funcionário pergunta uma vez.

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

Ferramentas do dia a dia (um acompanhamento, um formulário, um pequeno painel) são criadas com a skill de apps integrada do Nebo. Uma página que deve parecer projetada, e não gerada, como uma landing page cinematográfica, um filme guiado pela rolagem, arte generativa ou um jogo, é criada com a skill App Studio, da loja.

Para um app novo, o jeito mais simples é pedir a um funcionário. O Nebo inclui uma skill integrada para criar apps, e o funcionário usa create_employee, que escreve a pasta, o manifesto, a persona e a página em uma única chamada. O app aparece na equipe de funcionários do proprietário em 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 recebe os mesmos argumentos ui, app e agent_md. Um caminho em ui substitui aquele arquivo específico. A página é lida do disco a cada requisição, então recarregar a janela mostra a alteração.

Uma página mínima

Esta página carrega o SDK, pergunta quem é o seu funcionário e exibe a resposta. Se ela mostrar o id e o nome do funcionário, a ligação está certa.

<!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>

O SDK descobre o id do app pelo endereço da página. Uma página servida de qualquer outro lugar precisa de <meta name="nebo-app-id" content="<id>">. Guarde o estado no armazenamento do app, não na página: a janela fecha, e o armazenamento continua.

Como a página é servida

  • O Nebo serve ui/ em /apps/<id>/ui/ e a abre em uma janela própria.
  • Um caminho sem arquivo correspondente cai para index.html, então o roteamento no cliente funciona.
  • As páginas HTML recebem as meta tags nebo-app-id e nebo-base-url.
  • Todo arquivo é enviado com o tipo de conteúdo real, incluindo vídeo, som, fontes, wasm e modelos 3D (glb, gltf). Um arquivo com extensão desconhecida é enviado como application/octet-stream e o navegador não vai usá-lo.
  • Os arquivos atendem a solicitações de intervalo (206, ou 416 para um intervalo além do fim), então vídeo e áudio podem avançar e voltar. No app móvel, o vídeo é reproduzido no próprio lugar, sem precisar tocar: <video muted playsinline autoplay loop poster="assets/hero.jpg" src="assets/hero.mp4"></video>
  • Um arquivo cujo nome tem um hash do conteúdo, como main-0a8ksftt.js, fica em cache por um ano. Todo o resto, inclusive o index.html, é verificado a cada abertura e responde 304 quando não mudou. Gere os arquivos com nomes com hash em vez de renomeá-los à mão.
  • Cada arquivo da página pode ter no máximo 10 MB.
  • Excluir a pasta desativa o funcionário; delete_employee o remove por completo.

Adicionar um sidecar

Quando a página precisar de lógica de servidor, de dados próprios ou de ferramentas que o funcionário possa chamar, adicione um sidecar: um binário que o Nebo roda ao lado do app. A página o acessa com neboFetch e um caminho relativo. Veja Sidecar do app.

Publicar pelo Nebo

Um app criado pelo proprietário pode publicar a si mesmo. O proprietário diz “publique-se”, ou toca em Publicar no chat do app, na tela do app no app de celular (na barra superior, ou como uma pílula ao lado de Fechar em um app de tela cheia), ou escolhe Publicar este app… no menu do desktop (no menu Arquivo do macOS, com uma janela de app em primeiro plano; no menu App da janela do app no Windows e no Linux). O funcionário redige o anúncio a partir do app, tira de 3 a 5 capturas de tela e mostra o anúncio no chat para ser ajustado na conversa. Nada é enviado até o proprietário responder Enviar para revisão no cartão, tocando ou por voz.

Um app criado pelo proprietário sempre tem as ferramentas de desenvolvedor para si mesmo: recarregar, status, console, capturas de tela e publicação. O modo Desenvolvedor de apps (Configurações do bot, Desenvolvedor) permite que outros funcionários trabalhem em qualquer app do proprietário, adiciona um console flutuante à página e desativa o cache. Apps instalados pela loja nunca recebem ferramentas de desenvolvedor nem um botão Publicar.

Publique um app você mesmo

Um app só de página é publicado como um único pacote com a ferramenta agent. O frontmatter do AGENT.md precisa dizer artifact_type: app; caso contrário, a loja cria um funcionário comum, sem página. Coloque entre aspas qualquer valor que contenha dois-pontos seguidos de espaço; sem aspas, o frontmatter não pode ser lido e o app vira, sem aviso, um funcionário comum.

---
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")
No zipO que acontece
AGENT.mdA persona e o manifesto do anúncio.
agent.jsonA configuração do funcionário. {} serve.
manifest.jsonMantido como o manifesto do app: a janela e as permissões chegam ao app instalado. Precisa ser um JSON válido.
ui/A página. Permitidos: html, css, js, mjs, ts, jsx, tsx, json, map, txt, md, imagens (png, jpg, gif, svg, webp, avif, ico, bmp), fontes (woff, woff2, ttf, otf), som (mp3, wav, ogg, m4a, aac, flac, opus), vídeo (mp4, webm, mov, m4v), wasm, glb, gltf, pdf. Arquivos que começam com ponto e node_modules/ são descartados.
skills/<name>/As skills próprias do funcionário, verificadas como uma skill enviada separadamente: SKILL.md mantido, scripts/ e bin/ de qualquer tipo, todo o resto conforme a lista de permitidos de skills.
  • Limites: 10 MB por arquivo e 50 MB por pacote. Um arquivo acima de 10 MB é ignorado (confira filesSkipped e uiFilesStored no resultado); um pacote acima de 50 MB é recusado.
  • O token de envio dura 5 minutos. Se o zip tiver uma única pasta no topo, ela é removida.
  • Para um app privado ou só de canais, cada envio recria o pacote instalável na hora e o Nebo avisa os bots que instalaram o app. Um bot online coloca o pacote recriado no lugar imediatamente; um bot offline faz isso na próxima vez que se conectar. Você não precisa aumentar a versão para isso, e as configurações, os agendamentos e os dados do proprietário para o app são mantidos. Apps públicos, não listados e somente por convite mantêm o pacote aprovado até uma nova versão passar pela revisão.
  • Uma nova versão segue a configuração de atualizações automáticas de cada proprietário para o app. Ela fica desativada a menos que o proprietário a ative, então, por padrão, o bot mostra "Atualização disponível" e o proprietário a aplica em Configurações, depois Atualizações, ou pela Caixa de entrada. Uma atualização nunca concede novas permissões; uma permissão que a nova versão adiciona é pedida quando o app precisa dela pela primeira vez.
  • Se a NeboAI retirar um app da loja, todos os bots que o instalaram o desativam e avisam o proprietário. Nada é excluído: tudo o que o app salvou é mantido.
  • Um app com sidecar envia o binário de cada plataforma com binary-token, e a página como um arquivo ui. Veja Sidecar do app e Publicação.