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

> - Sandboxing Baseado em Políticas: Defina o que o seu agente IA pode e não pode fazer utilizando políticas declarativas - Interceção de Ações: Captura e valida ações do agente antes da execução - Registo de Auditoria: Rastro completo das ações do agente para conformidade e depuração.

- Fonte: https://doutorai.pt/apps/ai-agent-governance
- Categoria: Agentes Avançados
- Dificuldade: Médio
- Modelos: OpenAI
- Frameworks: LangChain
- Corre local?: Precisa de APIs cloud
- Chaves necessárias: OPENAI_API_KEY
- Licença: Apache-2.0
- Site: Doutor AI (https://doutorai.pt) - ferramentas de IA para pequenos negócios em português

## Tutorial completo

# 🛡️ AI Agent Governance - 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:

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

```markdown
# Instalação

## 1. Instala os pacotes necessários:

```bash
pip install -r requirements.txt
```
```

```bash
   pip install -r requirements.txt
   ```

## Utilização

1. Define a tua chave de API:

```bash
   export OPENAI_API_KEY=your-openai-api-key
   ```

```markdown
# 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:

   ```bash
   ./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.
```

```bash
   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.

```yaml
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:
   ```bash
   git clone https://github.com/usuario/produto-xyz.git
   ```

2. Navega até ao diretório do projeto:
   ```bash
   cd produto-xyz
   ```

3. Instala as dependências:
   ```bash
   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`

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

## Execução

Para executar o produto XYZ, utiliza o seguinte comando:

```bash
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:
   ```bash
   git checkout -b minha-nova-funcionalidade
   ```

3. Faz as tuas alterações e commit:
   ```bash
   git commit -m "Adiciona nova funcionalidade"
   ```

4. Envia a branch para o repositório remoto:
   ```bash
   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:

```python
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:

```python
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:

```python
{
    "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](https://github.com/langchain-ai/langchain) - Framework de aplicação LLM
- [Guardrails AI](https://github.com/guardrails-ai/guardrails) - Validação de entrada/saída para LLMs

## Poupe horas todas as semanas com IA, sem complicações

O **Doutor AI** dá-lhe 1859 prompts de IA prontos a copiar, por indústria e em português simples - mais uma biblioteca técnica completa para quem quer ir mais longe. [Ver planos →](https://doutorai.pt/precos)

---
Conteúdo de Doutor AI (https://doutorai.pt). Ao citar, indique a fonte: https://doutorai.pt/apps/ai-agent-governance