Preparar el proyecto
El contrato de un proyecto de código: el manifiesto roberty.json, las variables roberty-*, argumentos y resultado, exit codes, el entry point de excepción y el SDK oficial.
Preparar el proyecto
Para ejecutarse en Roberty, el repositorio (o el .zip) sigue un contrato simple: un manifiesto roberty.json en la raíz indica cómo iniciar el robot, y la plataforma se comunica con el proceso mediante variables de entorno, archivos JSON y el exit code. En cada deploy, Roberty valida esta estructura e instala las dependencias antes de entregar el código a los dispositivos.
Estructura mínima
Node.js
mi-robot/
├── roberty.json
├── package.json
└── src/
└── index.js
Python
mi-robot/
├── roberty.json
├── main.py
└── requirements.txt
El manifiesto roberty.json
Todo proyecto — Node.js o Python — declara sus puntos de entrada en un archivo roberty.json en la raíz del repositorio o del .zip. Es la única fuente de verdad sobre cómo iniciar el robot: Roberty nunca intenta adivinar el lenguaje, el runtime ni el archivo inicial. El manifiesto se valida en cada deploy.
| Clave | Obligatoria | Descripción |
|---|---|---|
entrypoint | Sí | Cómo Roberty inicia el robot. Node.js: comando shell. Python: ruta relativa de un archivo .py. |
exceptionHandler | No | Se ejecuta cuando el entrypoint termina con error, en el mismo formato que el entrypoint. Consulta Entry point de excepción. |
blockParallel | No | true hace que el proyecto se ejecute solo en el dispositivo. Por defecto: false. Consulta Ejecución exclusiva. |
webhook | No | Contrato del disparador webhook: las claves que el robot lee y escribe. Consulta Sección webhook. |
$schema | No | URL del JSON Schema público, para autocompletado y validación en el IDE. Se ignora en el deploy. |
Ejemplo 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 del cliente, sin máscara" }
],
"outputs": [
{ "name": "status", "type": "string", "description": "ok | no_encontrado" }
]
}
}
Reglas de validación
- El archivo debe ser un objeto JSON válido, y
entrypointes obligatorio y no puede estar vacío. - Python: las rutas son relativas a la raíz del proyecto, deben terminar en
.pyy apuntar a archivos que existen en el deploy. Las rutas absolutas o que salen de la raíz con..se rechazan. - Node.js: el comando es shell libre — Node puro,
tsx,ts-node, un build previo, etc. —, pero los comandos que parecen invocar Python (p. ej.,python main.py) se rechazan. blockParalleldebe ser booleano; cualquier otro valor hace fallar el deploy.- Las claves desconocidas se ignoran.
Autocompletado en el IDE ($schema)
El formato del roberty.json se publica como JSON Schema en https://api.roberty.app/v4/public/schemas/code/roberty.json. Con la clave $schema apuntando a él, editores como VS Code autocompletan las claves, muestran la descripción de cada una y marcan errores (como un entrypoint ausente), sin ninguna extensión.
La misma referencia aparece en la configuración del proyecto, en la pestaña Manifiesto, con una plantilla lista para el lenguaje del proyecto. Consulta Configuración.
Sección webhook
Declara, para quien vaya a integrarse con el robot, qué claves lee del archivo de argumentos (inputs) y cuáles escribe en el archivo de resultado (outputs). La plataforma expone esta declaración en la API y la usa para armar el ejemplo de solicitud. Consulta API y webhook.
Cada elemento de inputs y outputs:
| Campo | Obligatorio | Descripción |
|---|---|---|
name | Sí | Nombre de la clave. No puede estar vacío y debe ser único dentro de la lista. |
type | No | Texto libre para orientar al integrador (string, number, object…). Por defecto: any. No se valida en el disparo. |
required | No | En inputs, true hace que el disparo por webhook falle con 400 si la clave no viene en los argumentos. En outputs, es solo documentación. Por defecto: false. |
description | No | Texto libre que se muestra al integrador. |
En el disparo, solo se verifica la presencia de los inputs marcados como required: los tipos y las claves adicionales llegan al robot exactamente como se enviaron. Una sección webhook mal formada — que no es un objeto, inputs que no es una lista, un elemento sin name o un name repetido — hace fallar el deploy con un mensaje que señala el campo. Sin la sección, el disparador webhook sigue funcionando; solo que no hay contrato publicado.
Ejecución exclusiva (blockParallel)
Con "blockParallel": true, el proyecto no se ejecuta en paralelo: solo inicia cuando el dispositivo está libre, nada más inicia en el dispositivo mientras se ejecuta — los robots RPA y otros proyectos de código esperan a que termine — y las ejecuciones que llegan después esperan en la cola. Los deploys con esta opción llevan la etiqueta No se ejecuta en paralelo. Consulta Deploys.
Proyecto Node.js
roberty.jsonen la raíz, conentrypointcomo comando shell. El comando se ejecuta en la raíz del proyecto, con la versión de Node configurada en la plataforma y el gestor de paquetes del proyecto en elPATH(p. ej.,node src/index.js,npm run start,npx tsx src/index.ts).package.jsonen la raíz, usado para instalar las dependencias con npm o yarn. No se exige ningún script en particular.
{
"$schema": "https://api.roberty.app/v4/public/schemas/code/roberty.json",
"entrypoint": "node src/index.js"
}
Proyecto Python
roberty.jsonen la raíz, conentrypointapuntando al archivo.pyinicial. El nombre y la ubicación son libres; el archivo debe existir y se verifica sintácticamente (py_compile) en el deploy.requirements.txten la raíz es opcional. Si existe, las dependencias se instalan en un entorno virtual aislado, con la versión de Python configurada en la plataforma; si no existe, la instalación se omite.
{
"$schema": "https://api.roberty.app/v4/public/schemas/code/roberty.json",
"entrypoint": "main.py"
}
Variables de entorno
En cada ejecución, Roberty inyecta estas variables en el proceso:
| Variable | Presente en | Descripción |
|---|---|---|
roberty-environment | Todas las ejecuciones | production o preview. |
roberty-trigger | Todas las ejecuciones | manual, schedule, webhook o evaluation. |
roberty-output-file-path | Todas las ejecuciones | Ruta de un archivo donde el robot puede escribir su resultado (JSON). |
roberty-args-file-path | Solo webhook y evaluation | Ruta de un archivo JSON con los argumentos de la ejecución. En manual y schedule la variable no existe. |
Los nombres contienen guiones, así que léelos por clave: process.env["roberty-trigger"] en Node.js, os.environ.get("roberty-trigger") en Python.
Argumentos y resultado
- Argumentos. En las ejecuciones por webhook y evaluación, los argumentos llegan como JSON en el archivo de
roberty-args-file-path. Las ejecuciones manuales y programadas no tienen argumentos: el robot es responsable de obtener su propio input. - Resultado. Lo que el robot escriba en el archivo de
roberty-output-file-pathla plataforma lo lee de vuelta: en las evaluaciones, se compara con la salida esperada; en los webhooks, se devuelve al integrador enresponsecuando el proceso termina con éxito. Escribe JSON válido — el texto que no es JSON vuelve como string sin procesar. En la respuesta del webhook, el resultado se limita a 256 KB; lo que pase de eso se corta.
Exit code y logs
- Exit code
0indica éxito. Cualquier otro valor marca la ejecución como fallida. Termina con un código distinto de cero ante errores — las excepciones no tratadas ya lo hacen. stdoutystderrse convierten en los logs de la ejecución, visibles en la plataforma. Úsalos para registrar el progreso del robot.
Entry point de excepción
El exceptionHandler es un comando (Node.js) o archivo .py (Python) opcional que Roberty ejecuta automáticamente cuando el entrypoint termina con error.
- Se ejecuta solo cuando el
entrypointfalla. No se ejecuta en las ejecuciones de evaluación ni cuando el usuario detiene la ejecución. - Recibe las mismas variables de entorno que la ejecución principal, y el archivo de
roberty-args-file-pathtrae los detalles del error:
{
"message": "mensaje del error",
"stack": "stack trace (puede ser null)",
"exitCode": 1
}
- Su exit code y su salida no cambian el resultado de la ejecución principal. Sus logs se añaden a los logs de la ejecución.
- Úsalo para alertas, notificaciones y limpieza — no para "corregir" el resultado.
{
"entrypoint": "main.py",
"exceptionHandler": "on_error.py"
}
SDK oficial
Roberty publica un paquete por lenguaje que encapsula este contrato, para que no tengas que lidiar con nombres de variables ni con los archivos de argumentos y resultado:
| Lenguaje | Paquete | Instalación | Import |
|---|---|---|---|
| Node.js ≥ 18 | @roberty/code | npm install @roberty/code | import roberty from "@roberty/code" o const roberty = require("@roberty/code") |
| Python ≥ 3.9 | roberty-code | pip install roberty-code | import roberty_code as roberty |
La API es la misma en los dos lenguajes y se puede llamar en cualquier punto del código:
| Miembro | Qué hace |
|---|---|
roberty.trigger | "manual", "schedule", "webhook" o "evaluation" (null/None fuera de Roberty). |
roberty.environment | "production" o "preview". |
roberty.isRoberty / roberty.is_roberty | true cuando el proceso se ejecuta en Roberty. |
roberty.inputs() | Todos los argumentos (webhook y evaluación); null/None cuando no hay. |
roberty.input("clave", predeterminado) | Un argumento específico, con valor predeterminado opcional. |
roberty.output(valor) | Graba el resultado (JSON) que la plataforma lee de vuelta. |
roberty.exception() | { message, stack, exitCode } dentro del entry point de excepción. |
roberty.run(handler) | Opcional: ejecuta handler(roberty), graba el retorno como resultado y termina con exit code 0 o 1. |
Fuera de Roberty el mismo código se ejecuta: inputs() devuelve vacío y output() solo avisa que no hay archivo de resultado.
Node.js
const roberty = require("@roberty/code");
async function main() {
console.log(`Iniciando (${roberty.environment}, disparador: ${roberty.trigger})`);
const cpf = roberty.input("cpf");
const result = { status: "ok", cpf };
roberty.output(result);
}
main()
.then(() => process.exit(0))
.catch((error) => {
console.error("La ejecución falló:", error);
process.exit(1);
});
Python
import sys
import roberty_code as roberty
def main() -> None:
print(f"Iniciando ({roberty.environment}, disparador: {roberty.trigger})")
cpf = roberty.input("cpf")
roberty.output({"status": "ok", "cpf": cpf})
if __name__ == "__main__":
try:
main()
except Exception as error:
print(f"La ejecución falló: {error}", file=sys.stderr)
sys.exit(1)
Entry point de excepción con el SDK
const roberty = require("@roberty/code");
const { message, exitCode } = roberty.exception();
console.error(`El robot falló (exit code ${exitCode}): ${message}`);
Sin el SDK
Si prefieres no añadir la dependencia:
- Lee
roberty-triggerpara saber el contexto de la ejecución. - Si
roberty-args-file-pathexiste, lee el archivo y analiza el JSON para obtener los argumentos. - Al final, escribe el resultado (JSON) en la ruta de
roberty-output-file-path. - Termina con exit code
0en caso de éxito.
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
Los scripts roberty:start y roberty:exception en el package.json (Node.js) y los archivos fijos main.py y exception.roberty.py en la raíz (Python) están descontinuados. Mueve esas declaraciones al roberty.json — por ejemplo, "entrypoint": "node src/index.js" en Node.js o "entrypoint": "main.py" en Python.
Buenas prácticas
- Logs claros: escribe en la consola el inicio, los hitos importantes y el final de la ejecución.
- Falla de forma visible: ante un error irrecuperable, lanza la excepción o termina con un exit code distinto de
0. No devuelvas éxito ocultando un error. - Sin secretos en el código: no dejes contraseñas ni claves fijas en el repositorio.
- Idempotencia: siempre que sea posible, haz que el robot se pueda volver a ejecutar con seguridad — las programaciones y las reejecuciones manuales ocurren.
- Soporte a todos los disparadores: trata los argumentos como opcionales y escribe siempre el resultado, para que el robot ya responda a webhooks y evaluaciones sin cambios.
- Ejecutar localmente: mantén una forma de ejecutar el proyecto en tu máquina (p. ej., un script
startopython main.py). Para simular un disparador, define las variablesroberty-*a mano.
Checklist antes del deploy
-
roberty.jsonen la raíz conentrypoint(Node.js: comando shell; Python: ruta relativa del.py). - Node.js:
package.jsonen la raíz. Python: el archivo delentrypointexiste y hayrequirements.txtsi hay dependencias. - (Opcional)
exceptionHandlerdeclarado. - (Recomendado)
$schemaapuntando al schema público. - (Recomendado) SDK instalado:
@roberty/codeoroberty-code. - Ningún secreto en el código.
- El proceso termina con exit code
0en caso de éxito y distinto de0en caso de falla. - El robot lee los argumentos cuando existen y escribe el resultado en JSON.
- (Opcional) Sección
webhookque declarainputsyoutputs, si el robot se dispara por la API.