README.pt-br.md

⚠️ This is an auto-generated translation. For the latest version, see the English README. Community corrections welcome!

🇺🇸 English | 🇨🇳 简体中文 | 🇯🇵 日本語 | 🇰🇷 한국어 | 🇪🇸 Español | 🇧🇷 Português | 🇩🇪 Deutsch | 🇫🇷 Français | 🇷🇺 Русский | 🇮🇳 हिन्दी | 🇹🇷 Türkçe | 🇻🇳 Tiếng Việt | 🇮🇹 Italiano | 🇸🇦 العربية | 🇮🇱 עברית

---

---

Harnesses suportados

Doze harnesses em duas classes — dez CLIs de codificação e dois gateways de chat e assistente (Hermes, OpenClaw). Uma única API de políticas e um único histórico de sessões para todos eles. O que uma política pode bloquear varia por harness: interromper uma chamada de ferramenta antes de executar está verificado nos doze; portões de fim de turno funcionam em oito. A matriz por harness lista os eventos que cada um respeita.

Agentes que não rodam em nenhum deles reportam via Python SDK, que oferece rastreamento, sessões e auditorias. Enforcement nesses casos requer um hook no seu próprio runtime — fale conosco e mapeamos juntos.

{/* A 6-column table instead of inline runs: table columns never re-wrap, so the grid stays 2×6 at any window width (scrolling on very narrow screens instead of collapsing into ragged orphan rows). */}

Instalação

npm install -g failproofai
failproofai config                             # conecte seus agentes e o daemon
failproofai policies add FailproofAI/policies  # escolha o que aplicar
failproofai                                    # dashboard em localhost:8020

A configuração conecta os hooks e não seleciona nenhuma política — o segundo comando é o que coloca as proteções na máquina, e qualquer pacote é adicionado da mesma forma (failproofai policies add <owner>/<repo>; policies show <owner>/<repo> lê um antes). Execute failproofai config sem terminal — em CI, num container, com um agente controlando — e ele aplica as configurações em vez de perguntar. Em uma máquina que nunca foi configurada, qualquer outro comando executa o mesmo assistente primeiro; desative isso com FAILPROOFAI_NO_FIRST_RUN=1.

Até que um pacote chegue, a única coisa em vigor é block-failproofai-commands, que está sempre ativa e não pode ser desligada ou pausada: um agente que pode pausar o enforcement consegue desligar todas as outras políticas.

---

O que ele bloqueia

Política	O que bloqueia
block-env-files	Leitura de .env e outros arquivos de segredos
warn-repeated-tool-calls	O agente em loop na mesma chamada
block-sudo	Escalada de privilégios
warn-destructive-sql	DROP, TRUNCATE, DELETE sem restrição
block-terraform / block-kubectl	Alterações não revisadas em infraestrutura ativa
block-rm-rf	Exclusão recursiva de arquivos
block-force-push / block-push-master	git push --force, pushes diretos para main

Cada uma dessas políticas intercepta a chamada antes de executar, então funcionam nos doze harnesses. As quatro primeiras se aplicam a qualquer agente que possa chamar uma ferramenta; as três últimas são as favoritas dos desenvolvedores — CLIs de codificação são a classe de harness que cobrimos com mais profundidade. A família sanitize-* é separada: ela roda após o retorno de uma ferramenta, então reporta um segredo na saída da ferramenta em vez de impedi-lo de entrar no contexto.

→ Todas as 39 políticas embutidas

---

Suas próprias políticas

Coloque um arquivo em .failproofai/policies/ — ele é carregado automaticamente, sem flags necessárias. Faça commit e toda a equipe recebe na próxima vez que fizer pull.

import { customPolicies, deny, allow } from "failproofai";

customPolicies.add({
  name: "no-production-writes",
  match: { events: ["PreToolUse"] },
  fn: async (ctx) => {
    if (ctx.toolInput?.file_path?.includes("production"))
      return deny("Writes to production paths are blocked.");
    return allow();
  },
});

Três decisões disponíveis para cada política:

Decisão	Efeito
allow()	Permite a operação
deny(message)	Bloqueia — a mensagem é enviada de volta ao agente
instruct(message)	Deixa passar, mas adiciona contexto ao próximo prompt do agente

→ Escrever uma política

---

Observabilidade

Enforcement é uma metade. A outra metade é ver o que o agente realmente fez.

Execute failproofai sem argumentos e ele serve um dashboard em localhost:8020 lendo o histórico de execuções já presente na sua máquina — sem conta, sem cadastro, nada sai da máquina. Você obtém a lista de sessões, a sequência de chamadas ao modelo, chamadas de ferramentas e decisões de hooks dentro de cada execução, o que foi bloqueado e o que a política disse ao agente, além de uma auditoria offline (failproofai audit) que varre seu histórico em busca de padrões arriscados e sugere políticas para evitá-los.

→ Dashboard local · Ler um trace · Auditoria local

Failproof AI Observability é o lado hospedado do mesmo modelo de dados, para equipes que rodam agentes em uma frota: todas as execuções de todos os harnesses em um só lugar, um grafo de execução com sub-agentes paralelos em suas próprias trilhas, latência p50/p95/p99 para modelos, ferramentas e hooks, rastreamento de custo e janela de contexto por modelo, rastreamento de erros, SQL sobre seus próprios traces com dashboards compartilháveis, avaliações pontuadas pelo seu próprio serviço, auditorias programadas que transformam falhas recorrentes em descobertas embasadas em evidências, e alertas roteados para Slack, e-mail ou um webhook assinado. Auto-hospedagem no seu próprio cluster está disponível no plano Enterprise.

→ Sessões · Auditorias · Agendar uma demo

---

Documentação

Começar
Quickstart	Instale, conecte um harness, veja a primeira execução
Conceitos	Como o sistema de hooks funciona
Harnesses suportados	Todos os 12 e o que cada um pode aplicar

Observar
Sessões	Acompanhe uma execução: modelos, ferramentas, erros, latência
Ler um trace	O que o grafo de execução está dizendo
Auditorias	Encontre padrões de falha em muitas sessões
Dashboard local	localhost:8020, sem conta necessária

Aplicar
Pacotes de políticas	As políticas do Failproof AI e pacotes do hub de políticas
Escrever uma política	A partir de uma auditoria ou em código
Configuração	Escopos de configuração, regras de mesclagem e parâmetros de política

Instrumentar seu próprio agente
Python SDK	Reporte execuções de um agente sem harness
Policy SDK	Referência de allow / deny / instruct

---

Licença

MIT com Commons Clause — gratuito para uso interno e pessoal; a revenda comercial do failproofai em si requer um acordo separado. Veja LICENSE para o texto completo.

---

Contribuindo

Veja CONTRIBUTING.md. Novas políticas, casos extremos e traduções são sempre bem-vindos.

Compile antes de começar. Execute bun install && bun run build primeiro. Este repositório roda os próprios hooks do failproofai sobre si mesmo, e eles resolvem o import failproofai contra o bundle compilado em dist/ — sem um build você receberá erros de hook Cannot find package 'failproofai'. Recompile após alterar src/. Veja Build before the in-repo dev hooks will work.

---

Feito com ❤️ por befailproof.ai em SF e Bengaluru.