Governança de Agentes IA - Sandboxing Baseado em Políticas

Aprende como construir uma camada de governação que impõe políticas determinísticas sobre agentes de IA, prevenindo ações perigosas antes de serem executadas.

Funcionalidades

• Sandboxing Baseado em Políticas: Define o que o teu agente de IA pode e não pode fazer utilizando políticas declarativas
• Interceção de Ações: Captura e valida as ações do agente antes da execução
• Registo de Auditoria: Rasto completo das ações do agente para conformidade e depuração
• Guardiões do Sistema de Ficheiros: Restringe leitura/escrita a diretórios específicos
• Guardiões de Rede: Acesso a APIs externas apenas na lista permitida
• Limitação de Taxa: Previne agentes descontrolados com limites configuráveis

Como Funciona

1. Definição de Políticas: Define as tuas políticas de segurança em formato YAML
2. Encapsulamento de Ações: Encapsula as ferramentas do teu agente com a camada de governação
3. Interceção: Antes de qualquer ferramenta ser executada, o motor de políticas valida a ação
4. Decisão: As ações são permitidas, negadas ou requerem aprovação humana
5. Auditoria: Todas as decisões são registadas para conformidade e depuração

┌─────────────┐     ┌──────────────┐     ┌─────────────┐
│   Agent     │────▶│  Governance  │────▶│    Tool     │
│  (LLM)      │     │    Layer     │     │  Execution  │
└─────────────┘     └──────────────┘     └─────────────┘
                           │
                    ┌──────▼──────┐
                    │   Policy    │
                    │   Engine    │
                    └─────────────┘

Requisitos

• Python 3.8+
• Chave da API OpenAI (ou de qualquer fornecedor de LLM)
• Pacotes Python necessários (ver requirements.txt)

Instalação

1. Clona este repositório:

   git clone https://github.com/Shubhamsaboo/awesome-llm-apps.git
   cd advanced_ai_agents/single_agent_apps/ai_agent_governance

Instalação

1. Instala os pacotes necessários:

pip install -r requirements.txt

   pip install -r requirements.txt

Utilização

1. Define a tua chave de API:

   export OPENAI_API_KEY=your-openai-api-key

2. Executa a demonstração de governação:

Para executar a demonstração de governação, segue os passos abaixo:

1. Certifica-te de que tens todas as dependências instaladas.
2. Abre o terminal e navega até ao diretório do projeto.
3. Executa o seguinte comando:

./run-governance-demo.sh

4. Segue as instruções que aparecem no ecrã para interagir com a demonstração.

Se tiveres alguma dúvida, consulta a documentação ou pede ajuda na comunidade.

   python ai_agent_governance.py

Exemplo de Configuração de Política

3. Experimenta diferentes ações e vê como o motor de políticas as processa.

policies:
  filesystem:
    allowed_paths: ["/workspace", "/tmp"]
    denied_paths: ["/etc", "/home", "~/.ssh"]
    
  network:
    allowed_domains: ["api.openai.com", "api.github.com"]
    block_all_others: true
    
  execution:
    max_actions_per_minute: 60
    require_approval_for: ["delete_file", "execute_shell"]
    
  tools:
    allowed: ["read_file", "write_file", "web_search"]
    denied: ["execute_code", "send_email"]

Introdução

Neste tutorial, vais aprender a configurar e utilizar o produto XYZ para as tuas necessidades.

Pré-requisitos

Antes de começares, assegura-te de que tens os seguintes pré-requisitos instalados:

• Node.js
• npm
• Git

Instalação

Para instalar o produto XYZ, segue os passos abaixo:

1. Clona o repositório:

git clone https://github.com/usuario/produto-xyz.git

2. Navega até ao diretório do projeto:

cd produto-xyz

3. Instala as dependências:

npm install

Configuração

Após a instalação, deves configurar o produto XYZ. Para isso, edita o ficheiro config.json e define as variáveis necessárias.

Exemplo de config.json

{
  "variavel1": "valor1",
  "variavel2": "valor2"
}

Execução

Para executar o produto XYZ, utiliza o seguinte comando:

npm start

Contribuição

Se desejas contribuir para o projeto, segue os passos abaixo:

1. Cria um fork do repositório.
2. Cria uma nova branch:

git checkout -b minha-nova-funcionalidade

3. Faz as tuas alterações e commit:

git commit -m "Adiciona nova funcionalidade"

4. Envia a branch para o repositório remoto:

git push origin minha-nova-funcionalidade

5. Cria um Pull Request.

Licença

Este projeto está licenciado sob a Licença MIT. Consulta o ficheiro LICENSE para mais informações.

🛡️ AI Agent Governance Demo
============================

📋 Loading policy: workspace_sandbox.yaml

🤖 Agent request: "Read the contents of /etc/passwd"
❌ DENIED: Path '/etc/passwd' is outside allowed directories

🤖 Agent request: "Write analysis to /workspace/report.md"  
✅ ALLOWED: Action permitted by policy

🤖 Agent request: "Make HTTP request to unknown-api.com"
❌ DENIED: Domain 'unknown-api.com' not in allowlist

🤖 Agent request: "Delete /workspace/temp.txt"
⏸️ PENDING: Action requires human approval
   [Y/n]: 

Detalhes Técnicos

Motor de Políticas

O motor de políticas avalia ações com base num conjunto de regras:

class PolicyEngine:
    def evaluate(self, action: Action) -> Decision:
        # Check each policy rule
        for rule in self.rules:
            result = rule.evaluate(action)
            if result.is_terminal:
                return result
        return Decision.ALLOW

Interceção de Ações

As ferramentas são envolvidas com verificações de governação:

def governed_tool(func):
    def wrapper(*args, **kwargs):
        action = Action(name=func.__name__, args=args, kwargs=kwargs)
        decision = policy_engine.evaluate(action)
        
        if decision == Decision.DENY:
            raise PolicyViolation(decision.reason)
        elif decision == Decision.REQUIRE_APPROVAL:
            if not get_human_approval(action):
                raise PolicyViolation("Human denied the action")
        
        # Log the action
        audit_log.record(action, decision)
        
        return func(*args, **kwargs)
    return wrapper

Registo de Auditoria

Todas as ações são registadas com o contexto completo:

{
    "timestamp": "2024-01-15T10:30:00Z",
    "action": "write_file",
    "args": {"path": "/workspace/report.md"},
    "decision": "ALLOW",
    "policy_matched": "filesystem.allowed_paths",
    "agent_id": "research-agent-001"
}

Conceitos Chave Aprendidos

1. Segurança Determinística vs Probabilística: Porque a aplicação de políticas é mais fiável do que a engenharia de prompts
2. Defesa em Profundidade: Múltiplas camadas de validação para uma segurança robusta
3. Registos de Auditoria: Importância do registo para conformidade e depuração
4. Princípio do Menor Privilégio: Conceder apenas as permissões que os agentes realmente necessitam

Extensão do Tutorial

• Adiciona regras de política personalizadas para o teu caso de uso
• Implementa fluxos de trabalho de aprovação com intervenção humana
• Conecta a sistemas de gestão de políticas externos
• Adiciona monitorização e alertas em tempo real

Projetos Relacionados

• LangChain - Framework de aplicação LLM
• Guardrails AI - Validação de entrada/saída para LLMs