Pular para o conteúdo principal
Roberty Studio
CODECode

Preparar o projeto

O contrato de um projeto de código: o manifesto roberty.json, as variáveis roberty-*, argumentos e resultado, exit codes, o entry point de exceção e o SDK oficial.

Preparar o projeto

Para rodar na Roberty, o repositório (ou o .zip) precisa seguir um contrato simples: um manifesto roberty.json na raiz diz como iniciar o robô, e a plataforma conversa com o processo por variáveis de ambiente, arquivos JSON e o exit code. A cada deploy, a Roberty valida essa estrutura, instala as dependências e só então entrega o código aos dispositivos.

Estrutura mínima​

Node.js

meu-robo/
├── roberty.json
├── package.json
└── src/
└── index.js

Python

meu-robo/
├── roberty.json
├── main.py
└── requirements.txt

O manifesto roberty.json​

Todo projeto — Node.js ou Python — declara seus pontos de entrada em um arquivo roberty.json na raiz do repositório ou do .zip. Ele é a única fonte de verdade sobre como iniciar o robô: a Roberty nunca tenta adivinhar linguagem, runtime ou arquivo inicial. O manifesto é validado a cada deploy.

ChaveObrigatóriaDescrição
entrypointSimComo a Roberty inicia o robô. Node.js: comando shell. Python: caminho relativo de um arquivo .py.
exceptionHandlerNãoExecutado quando o entrypoint termina com erro, no mesmo formato do entrypoint. Veja Entry point de exceção.
blockParallelNãotrue faz o projeto rodar sozinho no dispositivo. Padrão: false. Veja Execução exclusiva.
webhookNãoContrato do gatilho webhook: as chaves que o robô lê e escreve. Veja Seção webhook.
$schemaNãoURL do JSON Schema público, para autocomplete e validação na IDE. Ignorada no deploy.

Exemplo completo:

json
{
"$schema": "https://api.roberty.app/v4/public/schemas/code/roberty.json",
"entrypoint": "node src/index.js",
"exceptionHandler": "node src/exception.js",
"webhook": {
"inputs": [
{ "name": "cpf", "type": "string", "required": true, "description": "CPF do cliente, sem máscara" }
],
"outputs": [
{ "name": "status", "type": "string", "description": "ok | nao_encontrado" }
]
}
}

Regras de validação​

  • O arquivo deve ser um objeto JSON válido, e entrypoint é obrigatório e não pode ser vazio.
  • Python: os caminhos são relativos à raiz do projeto, devem terminar em .py e apontar para arquivos que existem no deploy. Caminhos absolutos ou que escapam da raiz com .. são rejeitados.
  • Node.js: o comando é shell livre — Node puro, tsx, ts-node, um build prévio etc. —, mas comandos que aparentam invocar Python (ex.: python main.py) são rejeitados.
  • blockParallel precisa ser booleano; outro valor falha o deploy.
  • Chaves desconhecidas são ignoradas.

Autocomplete na IDE ($schema)​

O formato do roberty.json é publicado como JSON Schema em https://api.roberty.app/v4/public/schemas/code/roberty.json. Com a chave $schema apontando para ele, editores como o VS Code passam a autocompletar as chaves, mostrar a descrição de cada uma e marcar erros (como um entrypoint ausente), sem nenhuma extensão.

A mesma referência aparece nas configurações do projeto, na aba Manifesto, com um template pronto para a linguagem do projeto. Veja Configurações.

Seção webhook​

Declara, para quem vai integrar com o robô, quais chaves ele lê do arquivo de argumentos (inputs) e quais ele escreve no arquivo de resultado (outputs). A plataforma expõe essa declaração na API e a usa para montar o exemplo de requisição. Veja API e webhook.

Cada item de inputs e outputs:

CampoObrigatórioDescrição
nameSimNome da chave. Não pode ser vazio e deve ser único dentro da lista.
typeNãoTexto livre para orientar o integrador (string, number, object…). Padrão: any. Não é validado no disparo.
requiredNãoEm inputs, true faz o disparo por webhook falhar com 400 se a chave não vier nos argumentos. Em outputs, é só documentação. Padrão: false.
descriptionNãoTexto livre exibido ao integrador.

No disparo, só a presença dos inputs marcados como required é verificada: tipos e chaves extras chegam ao robô exatamente como foram enviados. Uma seção webhook malformada — que não é objeto, inputs que não é lista, item sem name ou name repetido — falha o deploy com uma mensagem apontando o campo. Sem a seção, o gatilho webhook continua funcionando; só não há contrato publicado.

Execução exclusiva (blockParallel)​

Com "blockParallel": true, o projeto não roda em paralelo: só inicia quando o dispositivo está ocioso, nada mais inicia no dispositivo enquanto ele roda — robôs RPA e outros projetos de código aguardam ele terminar — e as execuções que chegam depois aguardam na fila. Deploys com essa opção aparecem com o selo Não roda em paralelo. Veja Deploys.

Projeto Node.js​

  • roberty.json na raiz, com entrypoint como comando shell. O comando roda na raiz do projeto, com a versão de Node configurada na plataforma e o gerenciador de pacotes do projeto no PATH (ex.: node src/index.js, npm run start, npx tsx src/index.ts).
  • package.json na raiz, usado para instalar as dependências com npm ou yarn. Nenhum script específico é exigido nele.
json
{
"$schema": "https://api.roberty.app/v4/public/schemas/code/roberty.json",
"entrypoint": "node src/index.js"
}

Projeto Python​

  • roberty.json na raiz, com entrypoint apontando para o arquivo .py inicial. O nome e a localização são livres; o arquivo precisa existir e é verificado sintaticamente (py_compile) no deploy.
  • requirements.txt na raiz é opcional. Se existir, as dependências são instaladas em um ambiente virtual isolado, com a versão de Python configurada na plataforma; se não existir, a instalação é pulada.
json
{
"$schema": "https://api.roberty.app/v4/public/schemas/code/roberty.json",
"entrypoint": "main.py"
}

Variáveis de ambiente​

Em toda execução, a Roberty injeta estas variáveis no processo:

VariávelPresente emDescrição
roberty-environmentTodas as execuçõesproduction ou preview.
roberty-triggerTodas as execuçõesmanual, schedule, webhook ou evaluation.
roberty-output-file-pathTodas as execuçõesCaminho de um arquivo onde o robô pode escrever seu resultado (JSON).
roberty-args-file-pathSó webhook e evaluationCaminho de um arquivo JSON com os argumentos da execução. Em manual e schedule a variável não existe.

Os nomes contêm hífens, então leia-os por chave: process.env["roberty-trigger"] no Node.js, os.environ.get("roberty-trigger") no Python.

Argumentos e resultado​

  • Argumentos. Em execuções por webhook e avaliação, os argumentos chegam como JSON no arquivo de roberty-args-file-path. Em execuções manuais e agendadas não há argumentos: o robô é responsável por obter o próprio input.
  • Resultado. O que o robô escrever no arquivo de roberty-output-file-path é lido de volta pela plataforma: em avaliações, é comparado com a saída esperada; em webhooks, é devolvido ao integrador em response quando o processo termina com sucesso. Escreva JSON válido — texto que não é JSON volta como string crua. Na resposta do webhook, o resultado é limitado a 256 KB; acima disso, ele é cortado.

Exit code e logs​

  • Exit code 0 indica sucesso. Qualquer outro valor marca a execução como falha. Encerre com código diferente de zero em erros — exceções não tratadas já fazem isso.
  • stdout e stderr viram os logs da execução, visíveis na plataforma. Use-os para registrar o progresso do robô.

Entry point de exceção​

O exceptionHandler é um comando (Node.js) ou arquivo .py (Python) opcional que a Roberty executa automaticamente quando o entrypoint termina com erro.

  • Roda só quando o entrypoint falha. Não roda em execuções de avaliação nem quando o usuário interrompe a execução.
  • Recebe as mesmas variáveis de ambiente da execução principal, e o arquivo de roberty-args-file-path traz os detalhes do erro:
json
{
"message": "mensagem do erro",
"stack": "stack trace (pode ser null)",
"exitCode": 1
}
  • O exit code e a saída do entry point de exceção não alteram o resultado da execução principal. Seus logs são anexados aos logs da execução.
  • Use-o para alertas, notificações e limpeza — não para "corrigir" o resultado.
json
{
"entrypoint": "main.py",
"exceptionHandler": "on_error.py"
}

SDK oficial​

A Roberty publica um pacote por linguagem que encapsula esse contrato, para você não lidar com nomes de variáveis nem com os arquivos de argumentos e resultado:

LinguagemPacoteInstalaçãoImport
Node.js ≥ 18@roberty/codenpm install @roberty/codeimport roberty from "@roberty/code" ou const roberty = require("@roberty/code")
Python ≥ 3.9roberty-codepip install roberty-codeimport roberty_code as roberty

A API é a mesma nas duas linguagens e pode ser chamada em qualquer ponto do código:

MembroO que faz
roberty.trigger"manual", "schedule", "webhook" ou "evaluation" (null/None fora da Roberty).
roberty.environment"production" ou "preview".
roberty.isRoberty / roberty.is_robertytrue quando o processo roda na Roberty.
roberty.inputs()Todos os argumentos (webhook e avaliação); null/None quando não há.
roberty.input("chave", padrão)Um argumento específico, com valor padrão opcional.
roberty.output(valor)Grava o resultado (JSON) que a plataforma lê de volta.
roberty.exception(){ message, stack, exitCode } dentro do entry point de exceção.
roberty.run(handler)Opcional: executa handler(roberty), grava o retorno como resultado e encerra com exit code 0 ou 1.

Fora da Roberty o mesmo código roda: inputs() devolve vazio e output() apenas avisa que não há arquivo de resultado.

Node.js

js
const roberty = require("@roberty/code");

async function main() {
console.log(`Iniciando (${roberty.environment}, gatilho: ${roberty.trigger})`);
const cpf = roberty.input("cpf");
const result = { status: "ok", cpf };
roberty.output(result);
}

main()
.then(() => process.exit(0))
.catch((error) => {
console.error("Execução falhou:", error);
process.exit(1);
});

Python

python
import sys

import roberty_code as roberty


def main() -> None:
print(f"Iniciando ({roberty.environment}, gatilho: {roberty.trigger})")
cpf = roberty.input("cpf")
roberty.output({"status": "ok", "cpf": cpf})


if __name__ == "__main__":
try:
main()
except Exception as error:
print(f"Execução falhou: {error}", file=sys.stderr)
sys.exit(1)

Entry point de exceção com o SDK

js
const roberty = require("@roberty/code");

const { message, exitCode } = roberty.exception();
console.error(`Robô falhou (exit code ${exitCode}): ${message}`);

Sem o SDK​

Se preferir não adicionar a dependência:

  1. Leia roberty-trigger para saber o contexto da execução.
  2. Se roberty-args-file-path existir, leia o arquivo e faça o parse do JSON para obter os argumentos.
  3. Ao final, escreva o resultado (JSON) no caminho de roberty-output-file-path.
  4. Encerre com exit code 0 em sucesso.
python
import json
import os

args = None
args_file_path = os.environ.get("roberty-args-file-path")
if args_file_path:
with open(args_file_path, encoding="utf-8") as file:
args = json.load(file)

result = {"status": "ok"}

output_file_path = os.environ.get("roberty-output-file-path")
if output_file_path:
with open(output_file_path, "w", encoding="utf-8") as file:
json.dump(result, file)

Formatos descontinuados​

Os scripts roberty:start e roberty:exception no package.json (Node.js) e os arquivos fixos main.py e exception.roberty.py na raiz (Python) foram descontinuados. Mova essas declarações para o roberty.json — por exemplo, "entrypoint": "node src/index.js" no Node.js ou "entrypoint": "main.py" no Python.

Boas práticas​

  • Logs claros: escreva no console o início, os marcos importantes e o fim da execução.
  • Falhe alto: em erro irrecuperável, lance a exceção ou encerre com exit code diferente de 0. Não retorne sucesso escondendo um erro.
  • Sem segredos no código: não deixe senhas ou chaves fixas no repositório.
  • Idempotência: sempre que possível, faça o robô poder ser reexecutado com segurança — agendamentos e reexecuções manuais acontecem.
  • Suporte a todos os gatilhos: trate os argumentos como opcionais e escreva sempre o resultado, para o robô já responder a webhooks e avaliações sem mudanças.
  • Rodar localmente: mantenha uma forma de rodar o projeto na sua máquina (ex.: script start ou python main.py). Para simular um gatilho, defina as variáveis roberty-* à mão.

Checklist antes do deploy​

  • roberty.json na raiz com entrypoint (Node.js: comando shell; Python: caminho relativo do .py).
  • Node.js: package.json na raiz. Python: o arquivo do entrypoint existe e há requirements.txt se houver dependências.
  • (Opcional) exceptionHandler declarado.
  • (Recomendado) $schema apontando para o schema público.
  • (Recomendado) SDK instalado: @roberty/code ou roberty-code.
  • Nenhum segredo no código.
  • O processo encerra com exit code 0 em sucesso e diferente de 0 em falha.
  • O robô lê os argumentos quando existem e escreve o resultado em JSON.
  • (Opcional) Seção webhook declarando inputs e outputs, se o robô for disparado pela API.