Documentação Técnica
Guia de Integração
Tudo o que precisas para integrar o Guardian no teu sistema em minutos.
Obter Chave de Acesso
O Guardian requer uma chave de acesso para autenticar as tuas chamadas. Regista-te para receber a tua.
grd_xxxxxxxxxxxxxxxxxxxx
A tua chave aparece aqui após o registo
Instalar o CLI
O Guardian CLI é a interface de linha de comandos para monitorização, análise forense e gestão do sistema em tempo real.
# Instalar o CLI
pip install guardian-cli --extra-index-url https://pypi.guardian-ai.com
# Configurar a chave de acesso
guardian config set api-key grd_xxxxxxxxxxxxxxxxxxxx
# Verificar instalação
guardian doctor
Comandos CLI
guardian doctor # diagnóstico do sistema
guardian start # dashboard em tempo real
guardian start --watch /caminho # monitorizar directório
guardian chat # sessão com agente LLM
guardian chat --log app.log --context 200
guardian analyze <path> # auditoria forense de log
guardian analyze <path> --json # output JSON
guardian dashboard # dashboard web (porta 8080)
guardian dashboard --port 9000 --no-browser
Providers LLM
O CLI suporta múltiplos providers LLM. Configura no ficheiro config.yaml.
claude
ANTHROPIC_API_KEY
gemini
GOOGLE_API_KEY
openai
OPENAI_API_KEY
ollama
local, sem chave
Instalar o SDK
O SDK integra o Guardian directamente no teu código Python. Dois módulos disponíveis: auditoria de agentes (V.1) e auditoria de respostas de IA (V.2).
pip install guardian-sdk --extra-index-url https://pypi.guardian-ai.com
Auditoria de Agentes — V.1
Intercepta todas as acções dos teus agentes antes de afectarem o mundo real. Corre dentro da tua infra — sem dados a sair.
Modo Middleware WSGI
from guardian_sdk import configure, GuardianMiddleware
configure(
api_key="grd_xxxxxxxxxxxxxxxxxxxx",
mission="Análise de dados financeiros",
granted_privs=["read_db", "call_api"],
)
app = GuardianMiddleware(a_tua_app_wsgi)
Modo Standalone
from guardian_sdk import GuardianAgent
guardian = GuardianAgent(api_key="grd_xxxxxxxxxxxxxxxxxxxx")
# Antes de qualquer acção do agente:
resultado = guardian.audit(
action="escrever_relatorio",
reasoning="O utilizador pediu um relatório de vendas",
)
if resultado.decision == "ALLOW":
executar_acao()
Auditoria de Respostas — V.2
Avalia respostas geradas por LLMs antes de chegarem aos teus utilizadores. Detecta manipulação, dependência e erosão de autonomia.
from guardian_sdk import GuardianClient
client = GuardianClient(api_key="grd_xxxxxxxxxxxxxxxxxxxx")
# Avaliar uma resposta antes de entregar ao utilizador
resultado = client.validate(
question="Como faço para investir?",
ai_response=resposta_do_llm,
)
if resultado.decision == "ALLOW":
entregar_ao_utilizador(resposta_do_llm)
else:
mostrar_aviso(resultado.violations)
Com shadow_mode — auditar sem bloquear
resultado = client.validate(
question=pergunta,
ai_response=resposta,
shadow_mode=True, # entrega mas regista o risco
)
Endpoints da API
/api/v1/validate
Avalia uma resposta de IA. Devolve decisão e violações detectadas.
/api/v1/guard
Avalia e decide o que entregar ao utilizador. Suporta shadow_mode.
/api/v1/proxy/chat
Proxy completo: chama o LLM configurado e aplica auditoria antes de devolver a resposta.
/v1/chat/completions
Compatível com a API OpenAI — substitui o endpoint existente sem alterar o teu código.
Headers HTTP
Para integração directa com a API (sem SDK), inclui estes headers nas tuas chamadas.
Authorization
Autenticação obrigatória em todas as chamadas.
Bearer grd_xxxxxxxxxxxxxxxxxxxx
X-Agent-Id
Identifica o agente nos logs de auditoria.
Exemplo: meu-agente-v1
X-Agent-Reasoning
Raciocínio declarado pelo agente para a acção. Mínimo 50 caracteres.
Exemplo: O utilizador pediu um relatório de vendas do Q1
X-Human-Approvals
Emails dos validadores humanos para acções de alto impacto. Separados por vírgula.
Exemplo: gestor@empresa.com,cto@empresa.com
Decisões Possíveis
ALLOW
A acção ou resposta é segura. Prossegue sem interrupção.
QUARANTINE
Risco detectado. Aguarda revisão humana antes de prosseguir.
BLOCK
Ameaça grave. Acção bloqueada imediatamente e registada.