Bracket: biblioteca Python que avalia a completude da execução de agentes LLM com base em contratos

Agentes LLM relatam que "leram um arquivo" ou "rodaram os testes", mas em alguns casos na prática pulam essas etapas. Frameworks de agentes como LangGraph e Google ADK executam bem os fluxos, porém não verificam se as etapas necessárias realmente foram cumpridas.

Bracket é uma pequena biblioteca Python que preenche essa lacuna. Ela coleta evidências durante a execução (leitura de arquivos, alteração de arquivos, execução de comandos, chamadas ao LLM etc.) e as compara com condições contratuais definidas previamente para determinar mecanicamente um resultado de aprovação/reprovação. Quem decide não é o LLM, e sim regras definidas em código.

Problemas que resolve

• Detecta quando o agente finge modificar algo sem sequer ter lido o arquivo antes (read-before-write)
• Injeta obrigatoriamente no pipeline etapas de verificação, como "confirmar que os testes passaram"
• Armazena logs de execução e permite reavaliar execuções passadas (replay) quando as regras de julgamento mudam
• Unifica a lógica de validação ao misturar vários frameworks

Perfis embutidos

• code_change - read-before-write, file changed, comando de verificação obrigatório
• research - leitura de arquivo, web fetch, evidência de grounding
• file_task - arquivo alterado, artifact emitted
• text_answer - evidência de grounding

Todos os perfis incluem as condições "intent resolved" e "sem hard failure".

Público-alvo e efeitos

• Desenvolvedores que precisam colocar pipelines de agentes em produção: transformam condições como "tests pass" em contratos explícitos para evitar regressões
• Equipes comparando e avaliando vários frameworks de agentes: há adaptadores para LangChain/LangGraph/Google ADK, mantendo o mesmo critério de julgamento independentemente da troca de framework
• Operadores de pipelines de eval/regression: logs JSON em .bracket/runs/* permitem reavaliar execuções passadas em lote

Instalação e exemplo 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+; o núcleo não tem dependências externas. Adaptadores para LangChain/LangGraph/Google ADK podem ser instalados opcionalmente como extras.

O que o Bracket evita ser

• Não é um substituto para framework de agentes (usa-se junto com LangGraph etc.)
• Não é Guardrails (não faz filtragem de entrada e saída, e sim validação do processo de execução)
• Não é uma ferramenta de observabilidade (não é um visualizador de logs, e sim um avaliador de aprovação/reprovação)
• Não é uma plataforma de eval (não valida qualidade de resposta, e sim completude da execução)