Documentación

Crea un flujo que puedas ejecutar y revisar.

Para equipos con acceso a la aplicación. Sigue un evento hasta la tarea de un agente, revisa su ejecución y define el evento que confirma el resultado. Más adelante encontrarás las referencias de la API y las políticas.

1

Empieza en Flujos de trabajo.

Cuando tengas acceso, abre Flujos de trabajo. Si tu espacio aún no tiene flujos, ofrece un ejemplo inicial que puedes instalar y ejecutar desde la aplicación.

Esta guía usa la aplicación alojada.
Solicita acceso
2
Define el trabajo y el evento de finalización.

Nuevo flujo de trabajo conecta un evento con una tarea de agente. Especifica un nombre, el evento y la instrucción. El YAML completo contiene una lista rules. Este ejemplo parte de una etiqueta en un ticket, pide a un agente preparar un pull request y espera un evento de merge.
first-run.yamlDescargar
```
rules:
  - name: first-run
    on: plane.label_added
    if: { label: first-run }
    do:
      - agent: { type: first-run, context: "Fix {issue.title} and open a pull request." }
      - plane.comment: "Picked up. The pull request is linked in the run."
    verify:
      on: github.pr.merged
      within: 24h
    finally:
      - matrix.send: "[{_status}] first-run {issue.title}"
```
Validado con el parser de flujos de Recuriant el 2026-11-02. Versión 1 del lenguaje de flujos.

Recuriant valida el flujo antes de guardarlo. Con una política declarada, los pasos que modifican sistemas se verifican antes de ejecutarse: de forma predeterminada, L1 se ejecuta, L2 espera aprobación y L3 se rechaza.
Cómo se aplican los niveles
3
Revisa la ejecución.

Agrega una etiqueta a un ticket para iniciar el flujo. En Ejecuciones, consulta el resultado y la duración de cada paso. Las asignaciones a agentes enlazan a la ejecución del agente. Las acciones en espera aparecen en Aprobaciones.
1. 09:10 first-run on plane.label_added first-run iniciado
2. 09:10 first-run agent type=first-run asignado
3. 09:12 first-run plane.comment L1 · ejecutado
4. 09:12 first-run verify github.pr.merged within 24h en observación hasta mañana a las 09:12
Ejemplo ilustrativo con datos ficticios
Los resultados de ejecución y las decisiones de política disponibles también se pueden leer mediante la API. Las escrituras de auditoría para permitir o rechazar acciones no están garantizadas; el estado de una aprobación en espera debe guardarse.

Autentícate con una clave API.

Cada solicitud incluye una clave como token bearer. Las solicitudes se envían a la dirección API que recibes con tu espacio de trabajo; en los ejemplos se llama $RECURIANT_API.

Crea una clave en Claves API dentro de la aplicación. Asigna un nombre y un vencimiento de 30 días, 90 días, un año o sin vencimiento. La clave se muestra una sola vez; cópiala en ese momento.
Una clave que empieza con ck_ actúa en nombre de quien la creó. Una clave que empieza con cka_ pertenece a un agente administrado y solo incluye los permisos de su rol.
Una clave puede llamar acciones y leer ejecuciones. No puede aprobar un paso en espera: las aprobaciones requieren una sesión de usuario.
Revoca la clave desde la misma pantalla cuando dejes de necesitarla.

Verificar una clave

curl "$RECURIANT_API/me" -H "Authorization: Bearer $RECURIANT_API_KEY"

Referencia de la API.

Usa la dirección API que recibes con tu espacio de trabajo. Los cuerpos usan JSON y /openapi.json publica el esquema legible por máquinas. Los ejemplos muestran campos seleccionados de la respuesta.

GET /me tu identidad

Devuelve la persona o el agente de la clave y el espacio de trabajo al que pertenece.

Solicitud

curl "$RECURIANT_API/me" \
  -H "Authorization: Bearer $RECURIANT_API_KEY"

Respuesta abreviada

{
  "sub": "<id>",
  "email": "<email>",
  "username": "ana",
  "tenant": {
    "id": "<id>",
    "slug": "acme",
    "name": "acme"
  },
  "role": "",
  "principal_type": "user",
  "principal_id": "<id>"
}

GET /workflows tus flujos de trabajo

Lista cada flujo con su evento de activación, condiciones, pasos y si declara una verificación.

Solicitud

curl "$RECURIANT_API/workflows" \
  -H "Authorization: Bearer $RECURIANT_API_KEY"

Respuesta abreviada

{
  "workflows": [
    {
      "name": "first-run",
      "on": "plane.label_added",
      "conditions": {
        "label": "first-run"
      },
      "steps": 2,
      "do": [
        {
          "action": "agent"
        },
        {
          "action": "plane.comment"
        }
      ],
      "has_verify": true
    }
  ],
  "defaults": {}
}

GET /actions el catálogo de acciones

Lista las acciones que puede llamar tu clave, sus entradas, si modifican algo fuera de Recuriant, su reversibilidad, impacto y nivel.

Solicitud

curl "$RECURIANT_API/actions" \
  -H "Authorization: Bearer $RECURIANT_API_KEY"

Respuesta abreviada

{
  "tenant": "acme",
  "actions": [
    {
      "name": "matrix.send",
      "kind": "connector",
      "mutates_external_state": true,
      "reversibility": "reversible",
      "impact": "low",
      "tier": "L1"
    }
  ],
  "total": 1
}

POST /actions/{action} llamar una acción

Ejecuta una acción por nombre mediante las verificaciones configuradas. Coloca sus argumentos en args. Una llamada que continúa en segundo plano devuelve 202 con una URL de estado en data.

Solicitud

curl -X POST "$RECURIANT_API/actions/matrix.send" \
  -H "Authorization: Bearer $RECURIANT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"args": {"body": "Deploy complete"}}'

Respuesta abreviada

{
  "ok": true,
  "output": "<the action output>",
  "data": {}
}

POST /dry-run simular un evento

Explica qué flujos coinciden con un evento de ejemplo y por qué. No asigna trabajo ni registra decisiones de política. Con explain, la respuesta también incluye los flujos que no coincidieron.

Solicitud

curl -X POST "$RECURIANT_API/dry-run" \
  -H "Authorization: Bearer $RECURIANT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"event": "plane.label_added", "vars": {"label": "first-run"}, "explain": true}'

Respuesta abreviada

{
  "event": "plane.label_added",
  "vars": {
    "label": "first-run"
  },
  "matched_workflows": 1,
  "total_evaluated": 1,
  "matches": [
    {
      "workflow": "first-run",
      "matched": true
    }
  ],
  "results": [
    {
      "workflow": "first-run",
      "matched": true
    }
  ]
}

GET /executions listar ejecuciones

Lista las ejecuciones. Filtra por flujo, tipo, estado o issue. La lista omite el detalle de los pasos; consulta una ejecución para obtener su registro completo.

Solicitud

curl "$RECURIANT_API/executions?workflow=first-run" \
  -H "Authorization: Bearer $RECURIANT_API_KEY"

Respuesta abreviada

[
  {
    "id": "<id>",
    "type": "workflow",
    "status": "completed",
    "workflow_name": "first-run",
    "event_type": "plane.label_added",
    "started_at": "2026-11-02 09:10:04+00:00",
    "finished_at": "2026-11-02 09:12:41+00:00",
    "details_included": false,
    "step_log": null
  }
]

GET /executions/{id} consultar una ejecución

Devuelve una ejecución con el registro de sus pasos, la ejecución que la inició, el paso actual y su nivel de anidación.

Solicitud

curl "$RECURIANT_API/executions/<id>" \
  -H "Authorization: Bearer $RECURIANT_API_KEY"

Respuesta abreviada

{
  "id": "<id>",
  "type": "workflow",
  "status": "completed",
  "workflow_name": "first-run",
  "parent_execution_id": null,
  "current_step": 2,
  "total_steps": 2,
  "depth": 0,
  "details_included": true
}

Encuentra las acciones que expone tu espacio de trabajo.

Tu catálogo muestra las acciones que permiten tus credenciales. Las acciones de un conector aparecen cuando su integración se configura para tu espacio de trabajo y desaparecen al desactivarla.

La clave de un agente administrado muestra las acciones de lectura, los flujos y las acciones de su rol. Cada acción declara su reversibilidad e impacto, que determinan su nivel.

plane.comment: reversible, bajo impacto: L1, se ejecuta
plane.issue: reversible, bajo impacto: L1, se ejecuta
matrix.send: reversible, bajo impacto: L1, se ejecuta
http: difícil de revertir, bajo impacto: L2, espera a una persona
llm: solo lectura: sin control de políticas
grafana.query_metrics: solo lectura: sin control de políticas

Conecta un cliente MCP.

El servidor MCP de Recuriant expone flujos, ejecuciones, registros de aprobación y acciones de conectores a clientes compatibles como Claude Code o Cursor. Las acciones usan las mismas verificaciones configuradas que los pasos de un flujo. El servidor aún no se publica como paquete instalable; contáctanos para hablar del acceso.

Se autentica con la misma clave ck_ o cka_ que la API.

Hablemos del acceso a MCP

Configura las políticas de acción.

Con una política declarada, los pasos que modifican sistemas se verifican después de resolver sus entradas y antes de ejecutarse. Tu política asigna permitir, solicitar aprobación o rechazar a los niveles predeterminados siguientes.

L1: Reversible y de bajo impacto. El paso se ejecuta. La escritura de la decisión que lo permite no está garantizada, salvo que la operación requiera persistencia.
L2: Otras acciones que modifican sistemas, incluidas las que no tienen clasificación. El paso espera a una persona designada durante 24 horas de forma predeterminada. Al vencer, se rechaza, salvo que la política indique aprobarlo o escalarlo. El estado de aprobación debe guardarse antes de continuar.
L3: Irreversible de impacto medio o alto, o difícil de revertir y de alto impacto. El paso se rechaza; el registro de decisión, cuando está disponible, identifica la regla.
Sin política declarada: Sin una política declarada, los pasos del flujo se ejecutan sin estos controles y ninguna acción espera aprobación por política. Los permisos de identidad aplicables se siguen verificando.
policy_unavailable: Si una política declarada no se puede cargar, se bloquea toda acción que modificaría un sistema externo.

Consulta el modelo completo de control

Comprueba que llegue el evento esperado.

Un flujo puede definir un evento que represente la finalización y un plazo. Después de ejecutar sus pasos, espera ese evento. Si el plazo vence primero, registra que no llegó y ejecuta los pasos de seguimiento configurados para ese caso.

incident-resolution.yamlDescargar

rules:
  - name: incident-resolution
    on: alertmanager.firing
    if: { severity: critical }
    do:
      - agent: { type: incident, context: "Diagnose {alert.name} and propose one change." }
        as: diagnosis
      - plane.issue: { title: "[INCIDENT] {alert.name}", description: "{diagnosis}" }
      - http: { url: "https://deploy.example.com/rollback", method: POST, body: { service: "{alert.namespace}" } }
    verify:
      on: alertmanager.resolved
      within: 30m
      else:
        - alert: { severity: critical, summary: "{alert.name} is still firing after 30 minutes" }
    finally:
      - matrix.send: "[{_status}] incident-resolution {alert.name}"

Validado con el parser de flujos de Recuriant el 2026-11-02. Versión 1 del lenguaje de flujos.

verify.on indica el evento esperado. within fija su plazo con una duración como 30m o 24h. Elige un evento que represente el resultado que necesitas observar.
else define los pasos que se ejecutan si vence el plazo sin recibir el evento esperado.
finally programa tareas de limpieza o reporte después del cuerpo del flujo, incluso si falla un paso.
Una acción en espera tiene un plazo de aprobación independiente: 24 horas de forma predeterminada, configurable en la política. Al vencer, la acción se rechaza, salvo que la política indique otro resultado.

Entiende los errores y cómo recuperarte.

La API devuelve un código de estado y un detalle JSON. Los registros de ejecución muestran los resultados de los pasos; las decisiones de política disponibles explican por qué una acción se permitió, quedó en espera o se rechazó.

401: La clave falta, no es válida o venció. Revisa el encabezado Authorization o crea una clave.
404: Acción desconocida. Consulta GET /actions para ver los nombres disponibles en tu espacio de trabajo.
422 invalid_action_arguments: Los argumentos no coinciden con las entradas de la acción. El detalle indica el campo; compáralo con las entradas que lista GET /actions.
202: Aceptado. El trabajo continúa en segundo plano; consulta la URL de estado incluida en data.
502, 503: La validación de claves no está disponible por un momento. Esto no significa que tu clave sea inválida. Reintenta con pausas progresivas.
refused · scope_missing: La acción no está incluida en el token de la ejecución. Una aprobación no puede reabrirla: agrega la acción al rol del agente o mueve el paso a un flujo que tenga ese permiso.
refused · policy_unavailable: No se pudo cargar tu política declarada. Restáurala: hasta que se cargue, se rechaza cada paso que modificaría algo.

Regístrate para usar Recuriant.

Recuriant prepara la apertura del acceso de pago. Comparte tus datos de trabajo y el plan que te interesa; te contactaremos cuando esté disponible.

Solicita acceso

Crea un flujo que puedas ejecutar y revisar.

Empieza en Flujos de trabajo.

Define el trabajo y el evento de finalización.

Revisa la ejecución.

Autentícate con una clave API.

Referencia de la API.

Encuentra las acciones que expone tu espacio de trabajo.

Conecta un cliente MCP.

Configura las políticas de acción.

Comprueba que llegue el evento esperado.

Entiende los errores y cómo recuperarte.

Regístrate para usar Recuriant.