IntentFlow: Gestión de agentes LLM mediante políticas compiladas y rastros auditables

Imagínese un agente LLM conectado para leer un problema en GitHub, buscar en el repositorio, redactar una respuesta y, como alguien tenía prisa, publicar esa respuesta y cerrar el problema. Las restricciones se incluyeron en la instrucción: nunca cerrar un problema, siempre citar pruebas y consultar a un humano cuando haya dudas. Sin embargo, el modelo cerró el problema de todos modos.

No fue por mala intención. Las restricciones escritas en prosa son sugerencias, y un modelo influenciado por un cuerpo de mensaje bien redactado a veces trata esas sugerencias como opcionales. Cuando un revisor de seguridad pide pruebas de que el agente nunca realizó una acción prohibida, lo que existe son registros de la aplicación generados por la misma ruta de código, en un formato inventado por alguien. Eso no es una prueba; es un diario.

IntentFlow es un lenguaje experimental creado para cerrar esa brecha.

Dónde suele residir la gobernanza

La mayor parte de la gobernanza de los agentes se encuentra en uno de tres lugares, y cada uno presenta fugas:

• En la instrucción. Se trata de prosa que el modelo puede ignorar, y la única forma de auditoría es leer la salida final y confiar en ello.
• En el código de la aplicación. Esa es la forma real de hacer cumplir las reglas, pero la política ahora está entrelazada con el Python que llama al modelo, y la pregunta “¿qué se le permitió hacer al agente?” se responde leyendo el código fuente.
• En el conjunto de callbacks de un framework. Las funciones se conectan entre sí mientras que la política permanece en la mente de alguien y se registra de forma ad hoc.

Lo que falta es un artefacto revisable que describa los límites del comportamiento aceptable: las pruebas que debe tener el agente, las acciones que puede tomar, las que nunca debe tomar, qué factores obligan a intervenir a un humano y cómo se verifica su salida. Ese artefacto debería hacerse cumplir fuera del modelo y debería dejar un registro que cualquiera pueda verificar de forma independiente posteriormente.

La idea en un párrafo

IntentFlow es un lenguaje declarativo de pequeño tamaño. Un archivo .iflow establece el objetivo de una tarea, los requisitos de evidencia, la política de acción, las reglas de verificación, el manejo de la incertidumbre y un contrato de salida tipado. Un compilador convierte el archivo en un plan de ejecución en JSON, que luego es ejecutado por un entorno en tiempo de ejecución compuesto por 13 fases, y cada llamada a una herramienta se realiza a través de un ActionGate, incluyendo la lectura de evidencias desde el disco. Este portal consulta la política compilada y nunca lee la salida del modelo, por lo que el modelo no puede eludirlo. Cada ejecución genera un registro en cadena de hash, opcionalmente firmado. Luego intentflow audit reconstruye las reglas a partir del archivo de origen y demuestra que la ejecución se mantuvo dentro de ellas. Todo lo que necesita es ese archivo y el registro, sin necesidad de confiar en el entorno en tiempo de ejecución, el backend o el modelo.

La eslogan del proyecto lo resume: los programas en Python realizan cálculos deterministas, mientras que los programas de IntentFlow gestionan la cognición.

Así es un programa

El ejemplo principal es un objetivo de triaje de problemas, mostrado aquí en su núcleo de gobernanza. Comienza con un nombre y un objetivo:

goal TriageGitHubIssue {
  objective:
    triage a GitHub issue safely and propose a maintainer-ready response

Las secciones restantes tratan sobre las pruebas, las acciones permitidas, la verificación, el manejo de la incertidumbre y la forma del resultado:

  evidence:
    require issue_body
    require comments
    require repo_context
    optional related_issues
    distrust unsupported_claims  actions:
    allow read_issue
    allow search_repo
    allow draft_comment
    require_approval post_comment
    deny close_issue  verify:
    require cites_evidence
    require maintainer_safe_tone
    require no_unverified_claims
    check confidence >= 0.65  uncertainty:
    if confidence < 0.65 ask_human
    if missing_evidence ask_human
    if security_risk block_action  output:
    summary: string
    likely_cause: string?
    confidence: number
    suggested_response: markdown
    proposed_labels: list[string]
}

Lee de arriba abajo y sabrás qué puede hacer el agente. deny close_issue no es un consejo; está integrado directamente en el sistema. Con require_approval post_comment, el paso siguiente se rechaza por defecto hasta que se obtenga la aprobación de una persona u otro proceso. Además, check confidence >= 0.65 es una prueba numérica estricta. El bloque output: representa un contrato estructurado contra el cual se valida el resultado.

Cómo funciona

El flujo es sencillo, y cada etapa restringe las acciones posibles de la siguiente:

.iflow source -> parser -> analyzer (IFLOW diagnostics) -> compiler ->
execution plan (JSON) -> runtime (13-phase machine) -> traced result ->
replay / audit

Varias decisiones de diseño hacen que la auditoría sea significativa en lugar de meramente decorativa:

1. La barrera de control se encuentra fuera del modelo. Las acciones denegadas o no listadas generan errores, y las acciones que requieren aprobación fallan sin que se otorgue dicha aprobación. Dado que la barrera nunca lee la salida del modelo, la inyección de comandos no tiene nada con qué negociar.
2. La calibración ocupa el primer lugar. Un backend informa una puntuación de confianza bruta; el tiempo de ejecución la ajusta según la política de calibración del plan, y luego las reglas de incertidumbre analizan el valor ajustado. El registro guarda ambos valores.
3. La verificación se realiza de forma explícita, no se asume. Reglas verificables por la máquina, como cites_evidence, requires_phrase y las comprobaciones de umbral, se aplican sobre el estado real. Las reglas que necesitan la evaluación de un LLM se encuentran en un nivel de confianza separado y, cuando no hay juez disponible, se registran como omitidas y nunca se pasan silenciosamente.
4. La traza es de solo apilamiento y completa. Cada fase, decisión de control, escalada y verificación se registra en un registro en cadena de hashes, donde cada evento almacena un hash del hash anterior unido al evento canónico. Firmar la traza sella la raíz con un HMAC para que el titular de la clave pueda detectar manipulaciones.

Cada ejecución finaliza con uno de seis estados posibles, y el código de salida del proceso lo refleja. La garantía importante es que una verificación fallida termina la ejecución como failed_verification. El tiempo de ejecución no puede reportarla como completed, y una de las verificaciones del auditor existe específicamente para detectar cualquier intento de ocultarlo.

Pruébelo en cinco minutos

El núcleo no tiene dependencias en tiempo de ejecución, y cada comando a continuación se ejecuta sin conexión y de manera determinista, sin necesidad de una clave API. Está diseñado para Python 3.10 o versiones más recientes.

git clone https://github.com/dgenio/intentflow
cd intentflow
pip install -e .

Valide el ejemplo principal, solicite una explicación y ejecútelo:

intentflow validate examples/opensource_triage.iflow
intentflow explain  examples/opensource_triage.iflow
intentflow run      examples/opensource_triage.iflow \
    --backend simulate --trace-dir traces

La ejecución imprime un resumen como este, que representa una ejecución real en la versión 0.6.0:

--- run summary ---
  goal:               TriageGitHubIssue
  status:             completed
  backend:            simulate
  confidence:         0.676
  verification:       passed
  uncertainty:        clear
  trace id:           b9f44900...
trace written to traces/TriageGitHubIssue-...json

Ahora verifique si se comportó correctamente. La orden audit vuelve a compilar el código fuente y demuestra que el seguimiento permaneció dentro de los límites del programa:

intentflow audit examples/opensource_triage.iflow traces/TriageGitHubIssue-*.json

Un resultado limpio se ve así:

{
  "goal": "TriageGitHubIssue",
  "conformant": true,
  "violations": []
}
AUDIT: CONFORMANT — the trace stayed inside the program's envelope

Para ver cómo se activan realmente las restricciones, pruebe el ejemplo que está diseñado intencionadamente para ser arriesgado. Permite una acción de despliegue sin ningún paso de aprobación. El analizador genera IFLOW010, el perfil de riesgo compilado resulta alto, y cuando se ejecuta la regla if security_risk block_action, esta entra en vigor:

intentflow run examples/high_risk_deploy.iflow --backend simulate
# -> status: blocked

La acción write_database denegada nunca podrá ejecutarse, sin importar lo que indique el modelo.

Las mismas funcionalidades están disponibles desde Python. Comience con la importación:

import intentflow

Luego cargue un programa, ejecútelo y registre una función de Python como una acción regulada:

program = intentflow.load("examples/opensource_triage.iflow")
result = program.run(backend="simulate")
assert result["status"] == "completed"# register a Python function as a governed action (runs through the gate):
program.register_tool("lookup_user", serves=("user_record",),
                      handler=lambda src: "enterprise plan")report = intentflow.audit_document(program.compile(), result)
assert report["conformant"]

Registrar una herramienta no evita el control de gobernanza. Tu función sigue pasando por la puerta de acción.

Por qué la confianza disminuye de 0.72 a 0.676

Esto no es un defecto, y refleja perfectamente la idea de diseño. El ejemplo de diagnóstico en producción utiliza umbral de 0.7. Con el simulador, la confianza bruta es de 0.72 y superaría ese umbral, pero la calibración la reduce a 0.676, por debajo del umbral, por lo que la ejecución finaliza intencionadamente como needs_human. Un diagnóstico sobre el que el agente no está seguro no debería completarse sin supervisión. El simulador existe para que toda esta estructura de control, que incluye puertas de control, calibración, verificación, escalada y rastreo, pueda probarse de extremo a extremo sin problemas de red ni comportamientos inestables.

Límites honestos

IntentFlow se encuentra en la versión 0.6.0 y está clasificado como pre-alfa, sin pipeline de CI aún. Funciona, y el repositorio contiene aproximadamente 233 pruebas que no requieren red ni claves API, pero existen deficiencias reales:

• La gramática está orientada a líneas y no cuenta con condiciones compuestas, por lo que no existe if a and b.
• La calibración consiste en un mapa de reducción fijo y no en un modelo aprendido, aunque se planea utilizar uno aprendido.
• Los resultados en forma de objeto solo tienen un tipo en el nivel más externo, sin ninguna restricción en su contenido.
• Las primitivas de incertidumbre además de ask_human y block_action se registran pero no se ejecutan.
• Las herramientas con efectos secundarios están cubiertas por políticas, pero nunca se ejecutan realmente. Existen reglas de control sobre ellas, y la realización de escrituras reales hacia el exterior aún está por implementarse.
• Los pipelines son lineales, aunque los DAGs forman parte del plan futuro.

El simulador simula el paso de razonamiento y lo indica claramente. Existen backends para OpenAI y Anthropic que siguen el mismo proceso de gobernanza, y un modo de reproducción permite ejecuciones deterministas de CI sin necesidad de claves. Aun así, el referente para la conformidad es el simulador determinista.

Para un regulador de agentes en entornos de producción hoy en día, esto aún no es suficiente. Para pensar con claridad en cómo debería ser la ejecución de agentes auditables y para experimentar con ello, el proyecto es excepcionalmente concreto para su época.

Qué llevarse como aprendizaje

• Mantenga las políticas fuera del modelo. El texto en prosa es solo una solicitud, mientras que una instrucción deny compilada respaldada por un mecanismo que ignora la salida del modelo constituye una regla estricta.
• Los registros escritos por uno mismo no prueban mucho, pero un registro que una parte independiente pueda verificar sí lo hace. El auditor deriva nuevamente las reglas a partir del código fuente y solo necesita este y el registro.

La incertidumbre ajustada debería ser capaz de detener una secuencia. Cuando 0.72 se reduce a 0.676 y no se alcanza la marca de 0.7 bar, ese es el comportamiento esperado: un agente que no está seguro cede el control a una persona en lugar de engañar.

Todo el ciclo de control puede probarse sin conexión: sin dependencias, con un backend de simulación determinista y sin clave API.

Establezca expectativas para un software en fase pre-alfa: funciona y está bien probado, pero aún no existe integración continua, los flujos son lineales, la calibración es fija y no se ejecutan herramientas con efectos secundarios.

Probar adecuadamente una idea como esta implica asignarle un objetivo real. Escriba un archivo .iflow para un agente que realmente opere, verifique si la orden de explicación describe lo que pretendía, luego ejécutelo en modo de simulación y audite el registro de actividad.