> ## Documentation Index
> Fetch the complete documentation index at: https://docs.truthlocks.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Políticas MAIP

> Defina regras de aplicação em tempo de execução que controlam o que os agentes de IA podem fazer com base em pontuações de confiança, escopos, profundidade de delegação e tipo de agente.

As políticas MAIP permitem que você aplique guardrails ao comportamento do agente de IA em tempo de execução. Quando um agente solicita acesso a um recurso com escopo, todas as políticas ativas são avaliadas antes que a ação prossiga. Se alguma política negar a solicitação, a ação será bloqueada.

> [!NOTE]
>
> As políticas MAIP são diferentes das [políticas de emissão](https://docs.truthlocks.com/pt/guides/issuance-policies.md). As políticas de emissão governam a **criação e verificação de credenciais** para usuários humanos e emissores. As políticas MAIP governam o **comportamento do agente de máquina** em tempo de execução — controlando o que os agentes podem fazer com base em pontuações de confiança, profundidade de delegação, escopos e tipo de agente.

## Quando usar políticas MAIP

Use as políticas MAIP quando precisar:

* Bloquear agentes com baixas pontuações de confiança de realizar operações sensíveis
* Exigir aprovação humana quando um agente está profundamente em uma cadeia de delegação
* Restringir tipos específicos de agentes (por exemplo, `llm` ou `worker`) de acessar certos escopos
* Impor regras diferentes para diferentes níveis de risco sem alterar o código do agente
* Adicionar guard-rails de tempo de execução a fluxos de trabalho de orquestração multiagente

Se você não criar nenhuma política MAIP, o acesso do agente será controlado apenas por atribuições de escopo e status do agente.

## Como as políticas funcionam

Cada política MAIP contém uma ou mais **regras**. Cada regra tem:

* **Condições** — verificações em nível de campo avaliadas em relação ao contexto do agente solicitante
* **Efeito** — `allow`, `deny`, ou `require_approval`
* **requires\_approval** — flag opcional que aciona um fluxo de trabalho de aprovação humana

As regras dentro de uma política são avaliadas independentemente. Se **qualquer** regra com um efeito `deny` corresponder, a ação é bloqueada independentemente de quaisquer regras `allow`. Este é um modelo de **negação-prevalece**.

```
Agent requests scope → Evaluate all active policies (priority order)
                              │
                     ┌────────┼────────┐
                     ▼        ▼        ▼
                  Policy A  Policy B  Policy C
                  (p: 10)   (p: 20)  (p: 100)
                     │        │        │
                     ▼        ▼        ▼
               Any deny? ──yes──→ Action BLOCKED
                  │
                  no
                  │
                  ▼
             Action ALLOWED
```

### Ordem de avaliação

1. **Status do agente** — o agente deve estar `active`. Agentes suspensos ou revogados são sempre negados.
2. **Verificação de escopo** — o escopo solicitado deve estar nos escopos concedidos do agente. Escopos explicitamente negados (prefixados com `!`) sempre bloqueiam o acesso.
3. **Regras de política** — todas as políticas de locatário ativas são avaliadas em ordem de prioridade (números menores primeiro). As condições de cada regra são combinadas com AND.

### Campos de condição

| Campo | Tipo | Operadores | Descrição |
| - | - | - | - |
| `trust_score` | number | `lt`, `gt`, `le`, `ge` | Pontuação de confiança atual do agente (0.0–1.0) |
| `scope` | string | `eq`, `ne`, `in`, `contains` | O escopo sendo solicitado (por exemplo, `data:write`) |
| `agent_type` | string | `eq`, `ne`, `in` | Tipo de agente (por exemplo, `llm`, `worker`, `orchestrator`) |
| `delegation_depth` | number | `gt`, `ge`, `lt`, `le` | Posição na cadeia de delegação (0 = direto) |

### Operadores

| Operador | Descrição | Valor de exemplo |
| - | - | - |
| `eq` | Igual a | `"data:write"` |
| `ne` | Diferente de | `"system"` |
| `lt` | Menor que | `0.5` |
| `gt` | Maior que | `3` |
| `le` | Menor ou igual | `0.3` |
| `ge` | Maior ou igual | `0.7` |
| `in` | Corresponde a qualquer valor em uma lista | `["llm", "worker"]` |
| `contains` | A string contém a substring | `"write"` |

### Efeitos

| Efeito | Comportamento |
| - | - |
| `allow` | Permitir explicitamente a ação. Não anula negações de outras regras. |
| `deny` | Bloquear a ação. A primeira negação vence. |
| `require_approval` | Permitir a ação, mas sinalizá-la para aprovação humana antes de prosseguir. |

## Criar uma política

```bash cURL theme={null}
curl -X POST https://api.truthlocks.com/v1/maip/policies \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Block Low-Trust Write Operations",
    "description": "Deny data:write scope for agents with trust score below 0.5",
    "category": "trust",
    "priority": 10,
    "rules": [
      {
        "conditions": [
          {"field": "trust_score", "op": "lt", "value": 0.5},
          {"field": "scope", "op": "eq", "value": "data:write"}
        ],
        "effect": "deny",
        "requires_approval": false
      }
    ]
  }'
```

```javascript JavaScript theme={null}
const response = await fetch("https://api.truthlocks.com/v1/maip/policies", {
  method: "POST",
  headers: {
    "X-API-Key": "tl_live_...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Block Low-Trust Write Operations",
    description: "Deny data:write scope for agents with trust score below 0.5",
    category: "trust",
    priority: 10,
    rules: [
      {
        conditions: [
          { field: "trust_score", op: "lt", value: 0.5 },
          { field: "scope", op: "eq", value: "data:write" },
        ],
        effect: "deny",
        requires_approval: false,
      },
    ],
  }),
});
const policy = await response.json();
```

```python Python theme={null}
import requests

response = requests.post(
    "https://api.truthlocks.com/v1/maip/policies",
    headers={
        "X-API-Key": "tl_live_...",
        "Content-Type": "application/json",
    },
    json={
        "name": "Block Low-Trust Write Operations",
        "description": "Deny data:write scope for agents with trust score below 0.5",
        "category": "trust",
        "priority": 10,
        "rules": [
            {
                "conditions": [
                    {"field": "trust_score", "op": "lt", "value": 0.5},
                    {"field": "scope", "op": "eq", "value": "data:write"},
                ],
                "effect": "deny",
                "requires_approval": False,
            }
        ],
    },
)
policy = response.json()
```

Todas as novas políticas são criadas com `status: "active"` e entram em vigor imediatamente.

### Categorias de política

| Categoria | Caso de uso |
| - | - |
| `scope` | Restringir acesso com base em escopos ou recursos específicos |
| `trust` | Restringir acesso com base em limites de pontuação de confiança |
| `rate` | Restringir frequência ou volume de acesso |
| `custom` | Lógica de aplicação personalizada (padrão se omitida) |

### Prioridade

O campo `priority` controla a ordem de avaliação. Números menores são avaliados primeiro. Intervalo: 1–1000. Padrão: `100`. Se várias políticas compartilharem a mesma prioridade, elas serão avaliadas na ordem de criação.

## Avaliando políticas em tempo de execução

Chame o endpoint de avaliação antes que seu agente execute uma operação sensível. A resposta informa se a ação é permitida, negada ou requer aprovação humana.

```bash theme={null}
curl -X POST https://api.truthlocks.com/v1/maip/policies/evaluate \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "maip:t1234567:01HYX3KPZQ7RJGBN0WFMV8SDEH",
    "scope": "data:write",
    "action": "update_customer_record",
    "resource": "customers/cust_12345"
  }'
```

**Resposta permitida:**

```json theme={null}
{
  "allowed": true,
  "requires_approval": false
}
```

**Resposta negada:**

```json theme={null}
{
  "allowed": false,
  "denied_by": ["Block Low-Trust Write Operations"],
  "reason": "denied by policy",
  "requires_approval": false
}
```

**Requer resposta de aprovação:**

```json theme={null}
{
  "allowed": true,
  "requires_approval": true
}
```

Quando `requires_approval` é `true`, sua aplicação deve rotear a ação através de um fluxo de trabalho de aprovação humana antes de prosseguir.

## Listando políticas

```bash theme={null}
curl https://api.truthlocks.com/v1/maip/policies \
  -H "X-API-Key: $API_KEY"
```

Retorna todas as políticas MAIP para seu inquilino, incluindo suas regras, prioridade e status.

## Padrões comuns

### Bloquear agentes não confiáveis de gravar dados

Negar a qualquer agente com pontuação de confiança abaixo de 0,5 o acesso a escopos de gravação.

```json theme={null}
{
  "name": "Block Low-Trust Writes",
  "category": "trust",
  "priority": 10,
  "rules": [
    {
      "conditions": [
        { "field": "trust_score", "op": "lt", "value": 0.5 },
        { "field": "scope", "op": "eq", "value": "data:write" }
      ],
      "effect": "deny"
    }
  ]
}
```

### Exigir aprovação para cadeias de delegação profunda

Agentes com mais de três níveis de profundidade em uma cadeia de delegação devem obter aprovação humana para qualquer ação.

```json theme={null}
{
  "name": "Approval for Deep Delegation",
  "category": "scope",
  "priority": 20,
  "rules": [
    {
      "conditions": [
        { "field": "delegation_depth", "op": "gt", "value": 3 }
      ],
      "effect": "require_approval",
      "requires_approval": true
    }
  ]
}
```

### Restringir agentes LLM de executar ferramentas

Impedir que agentes do tipo LLM invoquem escopos de execução de ferramentas, permitindo outros tipos de agentes.

```json theme={null}
{
  "name": "No Tool Execution for LLMs",
  "category": "scope",
  "priority": 15,
  "rules": [
    {
      "conditions": [
        { "field": "agent_type", "op": "eq", "value": "llm" },
        { "field": "scope", "op": "eq", "value": "tool:execute" }
      ],
      "effect": "deny"
    }
  ]
}
```

### Bloquear vários tipos de agente de um escopo

Use o operador `in` para corresponder a uma lista de valores em vez de escrever regras separadas para cada tipo de agente.

```json theme={null}
{
  "name": "No Autonomous Writes",
  "category": "scope",
  "priority": 10,
  "rules": [
    {
      "conditions": [
        { "field": "agent_type", "op": "in", "value": ["llm", "worker"] },
        { "field": "scope", "op": "eq", "value": "data:write" }
      ],
      "effect": "deny"
    }
  ]
}
```

### Negar todos os escopos de gravação com uma única regra

Use o operador `contains` para corresponder a qualquer escopo que inclua uma substring, em vez de listar cada escopo de gravação individualmente.

```json theme={null}
{
  "name": "Read-Only for Low Trust",
  "category": "trust",
  "priority": 10,
  "rules": [
    {
      "conditions": [
        { "field": "trust_score", "op": "lt", "value": 0.5 },
        { "field": "scope", "op": "contains", "value": "write" }
      ],
      "effect": "deny"
    }
  ]
}
```

### Combinar várias regras em uma política

Uma única política pode conter várias regras para aplicação em camadas:

```json theme={null}
{
  "name": "Production Safety Net",
  "category": "custom",
  "priority": 5,
  "rules": [
    {
      "conditions": [
        { "field": "trust_score", "op": "lt", "value": 0.3 }
      ],
      "effect": "deny"
    },
    {
      "conditions": [
        { "field": "trust_score", "op": "lt", "value": 0.7 },
        { "field": "scope", "op": "eq", "value": "data:write" }
      ],
      "effect": "require_approval",
      "requires_approval": true
    }
  ]
}
```

Esta política bloqueia agentes com pontuações de confiança abaixo de 0,3 e exige aprovação humana para operações de escrita de agentes com pontuações entre 0,3 e 0,7.

## Políticas MAIP vs. políticas RBAC

| | Políticas MAIP | Políticas RBAC (emissão) |
| - | - | - |
| **Governa** | Comportamento de tempo de execução do agente de máquina | Criação, verificação e exportação de credenciais |
| **Assuntos** | Agentes de IA identificados por ID MAIP | Usuários e emissores humanos |
| **Campos de condição** | `trust_score`, `scope`, `agent_type`, `delegation_depth` | `jurisdiction`, `trust_tier`, `risk_rating`, `key.age_days` |
| **Modelo de avaliação** | Deny-overrides (qualquer bloqueio de negação) | Primeira correspondência vence |
| **Caminho da API** | `/v1/maip/policies` | `/v1/policies` |

## Relacionado

> [card] [Referência da API de Políticas MAIP](https://docs.truthlocks.com/api-reference/machine-identity/policies/list.md)
>
> Crie, liste e avalie políticas MAIP via API REST.

> [card] [Pontuações de confiança](https://docs.truthlocks.com/guides/trust-scores.md)
>
> Entenda o sistema de pontuação de confiança que alimenta as condições da política.

> [card] [Autorização do agente](https://docs.truthlocks.com/guides/agent-authorization.md)
>
> Autorização baseada em escopo e gerenciamento de sessão para agentes.

> [card] [Identidade da máquina](https://docs.truthlocks.com/guides/machine-identity.md)
>
> Visão geral completa do Protocolo de Identidade do Agente de Máquina.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.