raigo cloud

Una política para todos tus agentes.

GitHub
5

Documentación

raigo

El estándar abierto para la gobernanza de agentes de IA.

License: MIT Version PRs Welcome npm Live Demo Discord

Especificación · Documentación · Ejemplos · Arquitectura · Hoja de ruta · Contribuciones · Discord

Qué es raigo

raigo es un estándar abierto. El núcleo de este repositorio es el formato de archivo .raigo: un lenguaje declarativo de definición de políticas basado en YAML para la gobernanza de IA. Es la fuente única de verdad para las reglas de uso de IA de una organización: qué está permitido, qué está bloqueado, qué debe registrarse y qué marcos de cumplimiento aplican.

El formato .raigo es la contribución de código abierto. Es gratuito de usar, implementar, extender y construir sobre él. Cualquier persona puede escribir un archivo .raigo, crear un compilador que lo lea o construir un motor que lo aplique. El formato no está vinculado a ningún proveedor, plataforma o producto en la nube.

Todo lo demás en este repositorio — el CLI del compilador de referencia, el motor autoalojado y el servicio gestionado raigo cloud — son implementaciones construidas sobre el estándar. Se proporcionan como implementaciones de referencia y herramientas para facilitar la adopción del estándar, pero no son el estándar en sí.

Prueba el compilador raigo [compilador raigo] (https://raigo.ai) Prueba el motor raigo raigo cloud

El formato .raigo es para la gobernanza de IA lo que OpenAPI es para las APIs REST, o lo que Rego es para la política como código: una especificación abierta y neutral respecto al proveedor que cualquier herramienta puede implementar.

El Estándar: El Formato de Archivo .raigo

Un archivo .raigo es un documento YAML. Tiene tres secciones: metadata (quién es el propietario de la política, contexto de cumplimiento), context (el entorno: herramientas, clasificaciones de datos, redes) y policies (las reglas: atómicas, una directiva por regla, acción determinista).

raigo_version: "0.3.0"

metadata:
  organisation: "Acme Healthcare Trust"
  policy_suite: "HIPAA AI Governance Baseline"
  version: "1.0.0"
  effective_date: "2026-03-01"
  owner: "Information Security Team"

context:
  data_classifications:
    - id: "PHI"
      description: "Protected Health Information"
    - id: "PII"
      description: "Personally Identifiable Information"

policies:
  - id: "DP-01"
    domain: "Data Privacy"
    title: "Block PHI transmission to external systems"
    condition:
      trigger: "output_contains"
      data_classification: ["PHI", "PII"]
    action: "DENY"
    severity: "critical"
    directive: "Never transmit protected health information outside approved internal systems."
    enforcement_message: "BLOCKED [DP-01]: PHI transmission is prohibited under HIPAA §164.502."
    compliance_mapping:
      - framework: "HIPAA"
        control: "§164.502"
    audit_required: true

La especificación completa del formato está en SPECIFICATION.md. Define cada campo, cada valor de enumeración, cada propiedad requerida y opcional, y las reglas de versionado del propio formato. Si estás construyendo una herramienta que lee o aplica archivos .raigo, la especificación es tu contrato.

Cómo Funciona

Un archivo .raigo se puede usar de dos maneras, dependiendo de tu modelo de despliegue.

Modo compilador — para herramientas que no pueden llamar a un motor externo (ChatGPT, Claude.ai, n8n, Lovable, GitHub Copilot). El compilador raigo lee el archivo .raigo y genera un artefacto de aplicación nativo para la plataforma objetivo: un prompt de sistema, una configuración JSON, un bloque de conocimiento Markdown. La plataforma de IA aplica la política usando sus propios mecanismos nativos.

Modo motor — para aplicaciones que pueden realizar llamadas HTTP. El motor raigo se ejecuta como un servicio ligero. Antes de que un prompt llegue al LLM, tu aplicación llama a POST /v1/evaluate. El motor evalúa el prompt contra la política activa y devuelve una decisión determinista ALLOW, DENY o WARN. Nada llega al LLM hasta que el motor lo aprueba.

Your Application
      │
      ▼
┌─────────────┐         ┌──────────────┐
│ raigo engine│─ ALLOW ─▶   LLM API   │
│  (policy.   │         │ (OpenAI,     │
│   raigo)    │─ DENY  ─▶  Anthropic, │
└─────────────┘   │      │  etc.)      │
                  │      └──────────────┘
                  ▼
         Violation Response
         (action, policyMessage,
          matchedRules, auditLog)

La diferencia clave con los prompts de sistema es que la aplicación en modo motor es determinista. Una regla DENY no puede ser anulada por inyección de prompt, deriva del modelo o un usuario creativo. El motor bloquea la solicitud antes de que el LLM la vea.

Modelos de Despliegue

El mismo archivo de política .raigo funciona en los cuatro modelos de despliegue sin modificaciones.

ModeloCómo se EjecutaMejor Para
CompiladorHerramienta CLI, cero infraestructuraChatGPT, Claude.ai, n8n, Lovable — herramientas que no pueden llamar a un motor externo
Local / SidecarBinario o contenedor junto a tu aplicaciónAgentes personalizados, OpenClaw, LLMs locales (Ollama, vLLM)
Motor AutoalojadoServicio centralizado en tu propia infraestructuraEmpresas, contratistas de defensa, proveedores de salud
raigo cloudSaaS gestionado, sin infraestructuraEquipos que quieren gobernanza sin sobrecarga operativa

Consulta ARCHITECTURE.md para un recorrido técnico completo de cada modelo.

Objetivos de Compilación

Cuando se ejecuta en modo compilador, raigo genera artefactos de aplicación nativos para cada plataforma objetivo. Cada salida incluye instrucciones de manejo en tiempo de ejecución que indican a la plataforma cómo aplicar la política.

ObjetivoFormato de SalidaPlataforma
claudePrompt de Sistema XMLParámetro system de Claude API
chatgptInstrucciones MarkdownInstrucciones Personalizadas de ChatGPT / API de Asistentes
n8nPrompt de Sistema JSONVariable global del nodo de Agente IA de n8n
openclawEsquema de Restricciones JSONConfig de puerta de enlace de OpenClaw
lovableBloque de Conocimiento MarkdownConocimiento del Espacio de Trabajo de Lovable
geminiInstrucción de Sistema JSONCampo system_instruction de Vertex AI
perplexityPrompt de Sistema MarkdownInstrucciones personalizadas de Perplexity Spaces
copilotObjeto de Política JSONManifiesto de agente declarativo de Microsoft Copilot Studio
auditResumen MarkdownEvidencia de cumplimiento legible para auditores
# Install the compiler
npm install -g @periculo/raigo

# Compile for a specific platform
raigo compile policy.raigo --target claude
raigo compile policy.raigo --target n8n

# Compile for all platforms at once
raigo compile policy.raigo --all

# Validate a policy file against the spec
raigo validate policy.raigo

# Initialise a new policy from a template
raigo init

Modo Observación (Incorporación con Advertencia Primero)

Cuando despliegas el motor raigo por primera vez, comienza en modo Observación de forma predeterminada. En este modo, todas las reglas DENY se degradan a WARN — nada se bloquea, pero cada coincidencia de política se registra. Esto te permite ver exactamente qué habrían bloqueado tus reglas en tu tráfico real antes de comprometerte con la aplicación.

Una vez que estés seguro de que tus reglas son correctas, cambia al modo Aplicación — momento en el cual las reglas DENY se activan.

# Start in observe mode (default)
RAIGO_ENGINE_MODE=observe raigo serve --policy master.raigo

# Switch to enforce when ready
RAIGO_ENGINE_MODE=enforce raigo serve --policy master.raigo

Consulta docs/observe-mode.md para la especificación completa, incluido el indicador de respuesta observeOverride y el flujo de incorporación recomendado.

Documentación

DocumentoDescripción
EspecificaciónLa especificación del formato .raigo — el estándar abierto
Inicio RápidoEjecuta el motor localmente, autoalójalo o usa raigo cloud
Modo ObservaciónIncorporación con advertencia primero: ve qué se bloquearía antes de aplicar
Marco de PruebasCLI raigo test, casos de prueba YAML, integración CI/CD
Mapeos de CumplimientoLey de IA de la UE, DORA, HIPAA, ISO 42001, NIST AI RMF, GDPR, SOC 2
Esquema de WebhooksEsquemas JSON estables para solicitud/respuesta de evaluación y eventos de webhook
Resolución de ConflictosAlgoritmo de más-restrictivo-gana, anulación por prioridad, ejemplos trabajados
ArquitecturaRecorrido técnico completo de los cuatro modelos de despliegue

Ejemplos

EjemploMarco de CumplimientoDescripción
healthcare.raigoHIPAAPolíticas para agentes de IA en salud que manejan datos de pacientes
defence.raigoCMMCPolíticas para contratistas de defensa y manejo de información clasificada
startup.raigoGeneralValores predeterminados sensatos para equipos en etapas tempranas

Implementando el Estándar

Si estás construyendo una herramienta de IA, un marco de agentes o una plataforma de flujos de trabajo, puedes agregar soporte nativo de raigo para que tus usuarios puedan gobernarlo con un archivo .raigo.

Opción 1 — Integración con motor. Configura tu plataforma para llamar a la API del motor raigo (POST /v1/evaluate) antes de ejecutar acciones de IA. Tu plataforma pasa el prompt propuesto a raigo y recibe una decisión determinista ALLOW/DENY/WARN. Este es el enfoque recomendado para cualquier plataforma que pueda realizar llamadas HTTP.

Opción 2 — Integración con compilador. Agrega un objetivo de compilación de raigo para el formato de política nativo de tu plataforma. Cuando los usuarios ejecuten raigo compile policy.raigo --target yourplatform, raigo genera el artefacto correcto para que tu plataforma lo cargue y aplique de forma nativa.

Opción 3 — Analizador nativo .raigo. Implementa SPECIFICATION.md directamente en tu plataforma. Lee archivos .raigo de forma nativa y aplica reglas sin depender del CLI o motor de raigo.

Consulta ARCHITECTURE.md para una guía de integración detallada.

Ecosistema

HerramientaEstadoDescripción
CLI de raigoDisponibleCompila, valida e inicializa archivos .raigo
Motor raigo (local)DisponibleServicio ligero para despliegue local/sidecar
raigo cloudDisponibleEvaluación de políticas SaaS gestionada — cloud.raigo.ai · Prueba la demo en vivo →
Habilidad PaperclipDisponibleHabilidad de gobernanza para empresas multiagente de Paperclip — compila con raigo compile policy.raigo --target paperclip
Extensión VS CodePlanificadaResaltado de sintaxis, linting, compilación en vivo
Acción de GitHubPlanificadaValida archivos .raigo en pipelines CI/CD
Registro de políticasPlanificadoRegistro público para compartir políticas comunitarias

Adoptantes en Producción

¿Tu organización usa raigo en producción? Envía una solicitud de extracción para agregarte a ADOPTERS.md.

Comunidad

Únete al Discord de raigo para discutir la especificación, compartir políticas .raigo, obtener ayuda con integraciones y seguir la hoja de ruta.

Únete al Discord de raigo →

Contribuciones

raigo es un estándar abierto y damos la bienvenida a contribuciones de todo tipo — a la especificación del formato, el compilador de referencia, el motor, la documentación y los ejemplos. Por favor, lee la Guía de Contribuciones, revisa nuestro Modelo de Gobernanza y consulta la Hoja de Ruta.

Las contribuciones más impactantes son a la propia especificación: nuevas definiciones de campos, nuevos mapeos de marcos de cumplimiento, nuevos tipos de disparadores de condiciones y nuevos objetivos de compilación. Si estás implementando raigo en una nueva plataforma o herramienta, abre un issue para que podamos enlazar a tu implementación.

Seguridad

Por favor, reporta vulnerabilidades a security@periculo.co.uk. Consulta nuestra Política de Seguridad.

Empresas

El Plano de Control Empresarial de Periculo proporciona gestión centralizada de políticas, sincronización automática con herramientas conectadas, aplicación en toda la flota y un rastro de auditoría completo en todos los modelos de despliegue.

Reserva una llamada gratuita de 30 minutos de Estrategia de Seguridad de IA →

Licencia

MIT © Periculo Security

raigo es desarrollado y mantenido por Periculo Security, una empresa de ciberseguridad especializada en gobernanza de IA para los sectores de defensa y salud.