Saltar al contenido principal
Roberty Studio
CODECode

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.

ClaveObligatoriaDescripción
entrypointSíCómo Roberty inicia el robot. Node.js: comando shell. Python: ruta relativa de un archivo .py.
exceptionHandlerNoSe ejecuta cuando el entrypoint termina con error, en el mismo formato que el entrypoint. Consulta Entry point de excepción.
blockParallelNotrue hace que el proyecto se ejecute solo en el dispositivo. Por defecto: false. Consulta Ejecución exclusiva.
webhookNoContrato del disparador webhook: las claves que el robot lee y escribe. Consulta Sección webhook.
$schemaNoURL del JSON Schema público, para autocompletado y validación en el IDE. Se ignora en el deploy.

Ejemplo 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 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 entrypoint es obligatorio y no puede estar vacío.
  • Python: las rutas son relativas a la raíz del proyecto, deben terminar en .py y 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.
  • blockParallel debe 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:

CampoObligatorioDescripción
nameSíNombre de la clave. No puede estar vacío y debe ser único dentro de la lista.
typeNoTexto libre para orientar al integrador (string, number, object…). Por defecto: any. No se valida en el disparo.
requiredNoEn 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.
descriptionNoTexto 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.json en la raíz, con entrypoint como 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 el PATH (p. ej., node src/index.js, npm run start, npx tsx src/index.ts).
  • package.json en la raíz, usado para instalar las dependencias con npm o yarn. No se exige ningún script en particular.
json
{
"$schema": "https://api.roberty.app/v4/public/schemas/code/roberty.json",
"entrypoint": "node src/index.js"
}

Proyecto Python​

  • roberty.json en la raíz, con entrypoint apuntando al archivo .py inicial. El nombre y la ubicación son libres; el archivo debe existir y se verifica sintácticamente (py_compile) en el deploy.
  • requirements.txt en 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.
json
{
"$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:

VariablePresente enDescripción
roberty-environmentTodas las ejecucionesproduction o preview.
roberty-triggerTodas las ejecucionesmanual, schedule, webhook o evaluation.
roberty-output-file-pathTodas las ejecucionesRuta de un archivo donde el robot puede escribir su resultado (JSON).
roberty-args-file-pathSolo webhook y evaluationRuta 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-path la plataforma lo lee de vuelta: en las evaluaciones, se compara con la salida esperada; en los webhooks, se devuelve al integrador en response cuando 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 0 indica é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.
  • stdout y stderr se 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 entrypoint falla. 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-path trae los detalles del error:
json
{
"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.
json
{
"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:

LenguajePaqueteInstalaciónImport
Node.js ≥ 18@roberty/codenpm install @roberty/codeimport roberty from "@roberty/code" o const roberty = require("@roberty/code")
Python ≥ 3.9roberty-codepip install roberty-codeimport roberty_code as roberty

La API es la misma en los dos lenguajes y se puede llamar en cualquier punto del código:

MiembroQué hace
roberty.trigger"manual", "schedule", "webhook" o "evaluation" (null/None fuera de Roberty).
roberty.environment"production" o "preview".
roberty.isRoberty / roberty.is_robertytrue 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

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

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

js
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:

  1. Lee roberty-trigger para saber el contexto de la ejecución.
  2. Si roberty-args-file-path existe, lee el archivo y analiza el JSON para obtener los argumentos.
  3. Al final, escribe el resultado (JSON) en la ruta de roberty-output-file-path.
  4. Termina con exit code 0 en caso de éxito.
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​

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 start o python main.py). Para simular un disparador, define las variables roberty-* a mano.

Checklist antes del deploy​

  • roberty.json en la raíz con entrypoint (Node.js: comando shell; Python: ruta relativa del .py).
  • Node.js: package.json en la raíz. Python: el archivo del entrypoint existe y hay requirements.txt si hay dependencias.
  • (Opcional) exceptionHandler declarado.
  • (Recomendado) $schema apuntando al schema público.
  • (Recomendado) SDK instalado: @roberty/code o roberty-code.
  • Ningún secreto en el código.
  • El proceso termina con exit code 0 en caso de éxito y distinto de 0 en caso de falla.
  • El robot lee los argumentos cuando existen y escribe el resultado en JSON.
  • (Opcional) Sección webhook que declara inputs y outputs, si el robot se dispara por la API.