Bracket: biblioteca de Python que evalúa la integridad de ejecución de agentes LLM mediante contratos

Los agentes LLM informan que "leyeron un archivo" o "ejecutaron las pruebas", pero a veces en realidad se saltan esos pasos. Los frameworks de agentes como LangGraph o Google ADK ejecutan bien, pero no verifican si se siguieron los pasos necesarios.

Bracket es una pequeña biblioteca de Python que cubre esa brecha. Durante la ejecución recopila evidencia (lectura de archivos, cambios en archivos, ejecución de comandos, llamadas al LLM, etc.) y la compara con condiciones contractuales definidas de antemano para determinar mecánicamente si pasa o falla. No decide un LLM; deciden reglas definidas en código.

Problemas que resuelve

• Detecta cuando un agente finge modificar un archivo sin siquiera haberlo leído (read-before-write)
• Inyecta por la fuerza pasos de validación en el pipeline, como "confirmar que las pruebas pasan"
• Guarda los logs de ejecución y permite volver a evaluar (replay) ejecuciones pasadas cuando cambian las reglas de evaluación
• Unifica la lógica de validación al mezclar varios frameworks

Perfiles integrados

• code_change - read-before-write, file changed, comando de verificación obligatorio
• research - lectura de archivos, web fetch, evidencia de grounding
• file_task - file changed, artifact emitted
• text_answer - evidencia de grounding

Todos los perfiles incluyen las condiciones de "intent resolved" y "sin hard failure".

Usuarios objetivo y efectos

• Desarrolladores que necesitan llevar pipelines de agentes a producción: convierten condiciones como "tests pass" en contratos explícitos para prevenir regresiones
• Equipos que están comparando y evaluando varios frameworks de agentes: hay adaptadores para LangChain/LangGraph/Google ADK, por lo que se mantiene el mismo criterio de evaluación aunque se cambie de framework
• Operadores de pipelines de eval/regression: se pueden volver a evaluar en lote ejecuciones pasadas con los logs JSON de .bracket/runs/*

Instalación y ejemplo pip install bracket

from bracket import Harness, ExecutionContract

contract = ExecutionContract.code_change(goal="Fix failing test")
harness = Harness(app_name="my-agent", artifact_dir=".bracket")
run = harness.start_run(contract)

run.record_file_read("app.py", byte_count=1842)
run.record_file_changed("app.py")
run.record_command("pytest tests/", exit_code=0, kind="verification")

result = harness.finish_run_sync(run, final_output="Fixed the bug.")
print(result.verdict.outcome)  # VERIFIED / BLOCKED / PARTIAL

Python 3.12+, el core no tiene dependencias externas. Los adaptadores de LangChain/LangGraph/Google ADK se instalan opcionalmente como extras.

Lo que Bracket evita ser

• No es un reemplazo de framework de agentes (se usa junto con LangGraph, etc.)
• No es un sistema de guardrails (no filtra entradas y salidas; valida el proceso de ejecución)
• No es una herramienta de observabilidad (no es un visor de logs, sino un evaluador de pass/fail)
• No es una plataforma de eval (no valida la calidad de la respuesta, sino la integridad de la ejecución)