Lámina de comandos

Toda la capacidad de NORA de un vistazo: el SDK del robot, el CLI, las variables que el agente inyecta, los enums y los endpoints públicos. Para la explicación a fondo de cada cosa, sigue el enlace de cada bloque.

¿Eres (o usas) una IA?

Para darle a un asistente todo el contexto de NORA de golpe, pásale /llms-full.txt (volcado completo de la doc) y mira Operar NORA con IA.

SDK del robot — from nora_agent import sdk

La forma oficial de que un robot hable con NORA. Las funciones marcadas con 🔒 requieren un job gestionado (NORA_JOB_ID presente); fuera de él lanzan RuntimeError. El resto (colas, assets, logging, progreso) funciona también bajo nora dev run con NORA_EXEC_TOKEN.

Logging y progreso

Función	Firma	Qué hace
log	log(level: str, message: str, data: dict | None = None) -> None	Envía una línea de log estructurada al dashboard (en dev local imprime por stdout).
update_progress	update_progress(percent: int, message: str | None = None) -> None	Mueve la barra de progreso del job (0–100).

Info del job y señales de control

Función	Firma	Qué hace
get_job_id	get_job_id() -> str | None	ID del job actual; None en dev local.
get_job_signal	get_job_signal() -> str 🔒	Señal del job: "none", "stop" o "kill".
should_stop	should_stop() -> bool 🔒	True si el operador pidió Stop/Kill. Chéquealo dentro de bucles largos.

Argumentos de entrada/salida

Función	Firma	Qué hace
get_input	get_input(name: str | None = None, default=None)	Valor de un argumento (o el dict completo si name es None).
get_inputs	get_inputs() -> dict	Todos los argumentos de entrada del job.
set_output	set_output(key_or_dict, value=None) -> None	Reporta/mergea resultados en output_data (visibles en el job).

Se declaran en nora.json (inputs/outputs); ver argumentos.

Assets (credenciales/config cifradas)

Función	Firma	Qué hace
get_asset	get_asset(name: str, environment: str = "production") -> dict	Asset descifrado por nombre → {name, type, environment, value, username?} (value tipado según el tipo).

Colas (queues)

Función	Firma	Qué hace
get_queue_item	get_queue_item(queue_name: str) -> dict | None	Reclama el siguiente item (o None si está vacía).
queue_pending	queue_pending(queue_name: str) -> int	Cuántos items quedan claimables (status new).
queue_stats	queue_stats(queue_name: str) -> dict[str, int]	Conteo por estado, sin consumir nada.
complete_queue_item	complete_queue_item(queue_name: str, item_id: str, result: dict) -> None	Marca el item completado con su resultado.
fail_queue_item	fail_queue_item(queue_name: str, item_id: str, error_message: str, exception_type="system") -> None	Marca el item fallido. system = reintenta hasta max_retries; business = terminal (no reintenta).
add_queue_item	add_queue_item(queue_name: str, data: dict, priority: int = 3, reference=None, deadline=None, postpone=None) -> dict	Encola un único item (con reference/deadline/postpone opcionales).
add_queue_items	add_queue_items(queue_name: str, items: list[dict], priority: int = 3) -> int	Encola varios con la misma priority; devuelve cuántos.
send_queue_item_for_review	send_queue_item_for_review(queue_name: str, item_id: str) -> dict	Manda el item a revisión humana (pending_review).
wait_for_queue_review	wait_for_queue_review(queue_name: str, item_id: str, poll_interval=5.0, timeout=3600.0) -> str	Bloquea hasta "approved" o "rejected".

Las funciones de cola y de assets no necesitan job gestionado: corren bajo nora dev run (solo requieren NORA_EXEC_TOKEN).

Input atendido (human-in-the-loop) 🔒

Función	Firma	Qué hace
ask_user	ask_user(prompt: str, options: list[str] | None = None, poll_interval=5.0, timeout=3600.0) -> Any	Atajo: pide un dato al operador y bloquea hasta la respuesta.
request_user_input	request_user_input(prompt: str, options: list[str] | None = None) -> dict	Lanza la solicitud (no bloquea).
wait_for_user_input	wait_for_user_input(poll_interval=5.0, timeout=3600.0) -> Any	Bloquea hasta que el operador responda.

ask_user(...) = request_user_input(...) + wait_for_user_input(...).

Mantenimiento del agente

Función	Firma	Qué hace
check_for_update	check_for_update(current_version: str) -> dict	¿Hay versión más nueva del agente? Devuelve {update_available, latest_version, is_mandatory, changelog, download_url_macos, download_url_windows}.

Detalle de uso y buenas prácticas en SDK de robots y logging.

CLI nora — pip install nora-sdk

Comando	Flags clave (default)	Qué hace
nora login	--api-url (default https://nora-api.valisoftconsulting.com/api/v1, override con env NORA_API_URL), --password, --email	Inicia sesión (por navegador; --password para headless).
nora logout	—	Olvida la sesión guardada.
nora dev run <entry.py>	--environment dev, --assets, --ttl 1800, --input '{...}'	Ejecuta el robot local con datos en vivo (token de dev corto). --input pasa argumentos (NORA_INPUT).
nora dev env	--format dotenv, --write <path>, --ttl 28800, --environment dev	Escribe NORA_API_URL + NORA_EXEC_TOKEN para depurar en el IDE.
nora package [path]	--entry main.py, --bump patch, --version, --name, --exclude, --gitignore, --allow-secrets, --list	Empaqueta el robot en .zip (excluye venv/cachés/secretos; auto-incrementa versión).
nora release push [path]	--package, --version, --entry, --file, --no-create	Sube el .zip como release (crea el paquete si no existe).
nora release list [path]	--package	Lista las versiones subidas.
nora release delete <version>	--package	Elimina una versión (admin).
nora release download <version>	--package, -o	Descarga el .zip de una versión.

Flujo de despliegue completo en primeros pasos y procesos y paquetes.

Variables de entorno (las inyecta el agente)

El robot las lee con os.environ.get(...). Nunca se le pasan los secretos del agente (p. ej. NORA_MACHINE_KEY).

Variable	Contiene
NORA_JOB_ID	ID del job que lanzó el robot (ausente en dev local).
NORA_API_URL	URL base de la API (https://nora-api.valisoftconsulting.com/api/v1).
NORA_EXEC_TOKEN	Token de ejecución de corta vida, acotado a este job y sus assets/colas.
NORA_ASSETS	JSON con los assets precargados del proceso (get_asset los sirve sin red).
NORA_INPUT	JSON con los argumentos de entrada del job (get_input/get_inputs los leen).
NORA_DISPLAY_WIDTH / NORA_DISPLAY_HEIGHT	Resolución configurada en la máquina (úsala antes que la del SO).
NORA_DISPLAY_DEPTH / NORA_DISPLAY_SCALE	Profundidad de color (bits) y escala DPI (%).
NORA_SESSION_MODE	"rdp" (sesión RDP loopback) o "console" (consola física).
NORA_UNATTENDED	"1" si la máquina corre desatendida (auto-login), "0" si atendida.

Enums y constantes

Estados de un item de cola

Estado	Significado
new	Listo para ser reclamado.
in_progress	Un robot lo está procesando.
pending_review	Pausado, esperando aprobación humana.
completed	Procesado con éxito (lleva result).
failed	Falló o fue rechazado (reintenta si quedan reintentos).
dead_letter	Superó max_retries; ya no se reintenta solo.

stateDiagram-v2
    [*] --> new
    new --> in_progress
    in_progress --> completed
    in_progress --> pending_review
    in_progress --> failed
    pending_review --> new : aprobado
    pending_review --> failed : rechazado
    failed --> dead_letter : sin reintentos
    failed --> new : reintento

Prioridad de items: 1 = baja · 3 = normal (por defecto) · 5 = urgente.

Niveles de log: info · warning · error (recomendados; el SDK los normaliza a mayúsculas).

Tipos de asset: text · credential (usuario+valor) · secret · vault (bóveda externa) · integer · number · bool (el SDK devuelve el value ya tipado).

Tipos de trigger: webhook · queue (item nuevo → arranca job) · file_watcher · email_watcher.

Excepción de cola: system (transitoria, reintenta) · business (dato inválido, terminal).

Estados de job: pending · assigned · running · completed · failed · cancelled.

API pública (X-API-Key) — operaciones más usadas

Base: https://nora-api.valisoftconsulting.com/api/v1. Respuestas envueltas en {"success": true, "data": ...}. Cada key declara scopes (recurso:acción).

Acción	Endpoint	Scope	curl
Disparar un job	POST /jobs/trigger	jobs:write	curl -X POST .../jobs/trigger -H "X-API-Key: nora_ak_…" -d '{"process_id":"…"}'
Consultar un job	GET /jobs/{id}	jobs:read	curl .../jobs/<id> -H "X-API-Key: nora_ak_…"
Detener un job	POST /jobs/{id}/stop	jobs:stop	curl -X POST .../jobs/<id>/stop -H "X-API-Key: nora_ak_…"
Listar procesos (descubrir process_id)	GET /processes/list	processes:read	curl .../processes/list -H "X-API-Key: nora_ak_…"
Listar máquinas	GET /machines/list	machines:read	curl .../machines/list -H "X-API-Key: nora_ak_…"
Cargar items en lote	POST /queues/by-name/{name}/items/bulk	queues:write	curl -X POST .../queues/by-name/<cola>/items/bulk -H "X-API-Key: nora_ak_…" -d @items.json
Encolar un item	POST /queues/by-name/{name}/items	queues:write	curl -X POST .../queues/by-name/<cola>/items -H "X-API-Key: nora_ak_…" -d '{"data":{…}}'
Listar items de una cola	GET /queues/by-name/{name}/items	queues:read	curl .../queues/by-name/<cola>/items -H "X-API-Key: nora_ak_…"
Leer un asset	GET /assets/by-name/{name}?environment=production	assets:read	curl ".../assets/by-name/<nombre>?environment=production" -H "X-API-Key: nora_ak_…"
Webhook por proceso	POST /webhooks/trigger/{process_id}	— (cualquier key válida; feature webhooks)	curl -X POST .../webhooks/trigger/<id> -H "X-API-Key: nora_ak_…" -d '{…}'

Programaciones (cron) y administración de triggers se gestionan con tu sesión del dashboard (no X-API-Key); solo el webhook entrante por token es público. Ver autenticación y scopes, disparar jobs, colas vía API y webhooks.

Enlaces

• SDK de robots y logging · Colas · Assets
• Programaciones y triggers · Flujos DAG · Anomalías
• Tutoriales · Operar NORA con IA