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.
| Chave | Obrigatória | Descrição |
|---|---|---|
entrypoint | Sim | Como a Roberty inicia o robô. Node.js: comando shell. Python: caminho relativo de um arquivo .py. |
exceptionHandler | Não | Executado quando o entrypoint termina com erro, no mesmo formato do entrypoint. Veja Entry point de exceção. |
blockParallel | Não | true faz o projeto rodar sozinho no dispositivo. Padrão: false. Veja Execução exclusiva. |
webhook | Não | Contrato do gatilho webhook: as chaves que o robô lê e escreve. Veja Seção webhook. |
$schema | Não | URL do JSON Schema público, para autocomplete e validação na IDE. Ignorada no deploy. |
Exemplo completo:
{
"$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
.pye 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. blockParallelprecisa 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:
| Campo | Obrigatório | Descrição |
|---|---|---|
name | Sim | Nome da chave. Não pode ser vazio e deve ser único dentro da lista. |
type | Não | Texto livre para orientar o integrador (string, number, object…). Padrão: any. Não é validado no disparo. |
required | Não | Em 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. |
description | Não | Texto 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.jsonna raiz, comentrypointcomo 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 noPATH(ex.:node src/index.js,npm run start,npx tsx src/index.ts).package.jsonna raiz, usado para instalar as dependências com npm ou yarn. Nenhum script específico é exigido nele.
{
"$schema": "https://api.roberty.app/v4/public/schemas/code/roberty.json",
"entrypoint": "node src/index.js"
}
Projeto Python
roberty.jsonna raiz, comentrypointapontando para o arquivo.pyinicial. O nome e a localização são livres; o arquivo precisa existir e é verificado sintaticamente (py_compile) no deploy.requirements.txtna 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.
{
"$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ável | Presente em | Descrição |
|---|---|---|
roberty-environment | Todas as execuções | production ou preview. |
roberty-trigger | Todas as execuções | manual, schedule, webhook ou evaluation. |
roberty-output-file-path | Todas as execuções | Caminho de um arquivo onde o robô pode escrever seu resultado (JSON). |
roberty-args-file-path | Só webhook e evaluation | Caminho 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 emresponsequando 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
0indica 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. stdoutestderrviram 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
entrypointfalha. 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-pathtraz os detalhes do erro:
{
"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.
{
"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:
| Linguagem | Pacote | Instalação | Import |
|---|---|---|---|
| Node.js ≥ 18 | @roberty/code | npm install @roberty/code | import roberty from "@roberty/code" ou const roberty = require("@roberty/code") |
| Python ≥ 3.9 | roberty-code | pip install roberty-code | import roberty_code as roberty |
A API é a mesma nas duas linguagens e pode ser chamada em qualquer ponto do código:
| Membro | O que faz |
|---|---|
roberty.trigger | "manual", "schedule", "webhook" ou "evaluation" (null/None fora da Roberty). |
roberty.environment | "production" ou "preview". |
roberty.isRoberty / roberty.is_roberty | true 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
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
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
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:
- Leia
roberty-triggerpara saber o contexto da execução. - Se
roberty-args-file-pathexistir, leia o arquivo e faça o parse do JSON para obter os argumentos. - Ao final, escreva o resultado (JSON) no caminho de
roberty-output-file-path. - Encerre com exit code
0em sucesso.
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
startoupython main.py). Para simular um gatilho, defina as variáveisroberty-*à mão.
Checklist antes do deploy
-
roberty.jsonna raiz comentrypoint(Node.js: comando shell; Python: caminho relativo do.py). - Node.js:
package.jsonna raiz. Python: o arquivo doentrypointexiste e hárequirements.txtse houver dependências. - (Opcional)
exceptionHandlerdeclarado. - (Recomendado)
$schemaapontando para o schema público. - (Recomendado) SDK instalado:
@roberty/codeouroberty-code. - Nenhum segredo no código.
- O processo encerra com exit code
0em sucesso e diferente de0em falha. - O robô lê os argumentos quando existem e escreve o resultado em JSON.
- (Opcional) Seção
webhookdeclarandoinputseoutputs, se o robô for disparado pela API.