> ## 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.

# Identidade da Máquina (MAIP)

> Registe, autorize e monitorize agentes de IA com identidade criptográfica e restrições comportamentais.

# Protocolo de Identidade de Máquina e Identidade de Agente

O **Protocolo de Identidade de Agente de Máquina (MAIP)** fornece registros de identidade para agentes de IA, bots e serviços automatizados — para registrar agentes e registrar suas permissões e atividades.

> [!WARNING]
>
> Algumas operações MAIP atualmente registram resultados fornecidos pelo chamador em vez de executá-los ou verificá-los independentemente. A extração de documentos e os veredictos de IA são simulados; os guardrails classificam uma pontuação enviada; a orquestração e os manipuladores de fluxo de trabalho criam registros de rastreamento. Vários recibos gerados usam marcadores de sistema em vez de assinaturas criptográficas. Leia as limitações de implementação da operação antes de confiar em sua saída como evidência.

## Por que Identidade de Máquina?

À medida que os agentes de IA proliferam nos fluxos de trabalho empresariais, as organizações enfrentam um desafio crítico: **Como saber qual agente fez o quê e se foi autorizado?**

O MAIP resolve isso com:

* **Identidade criptográfica do agente** — Cada agente recebe um ID único (`maip-agent:<ulid>`) e chaves de assinatura
* **Autorização baseada em escopo** — Escopos de permissão granulares controlam o que cada agente pode fazer
* **Aplicação de política em tempo de execução** — [políticas MAIP](https://docs.truthlocks.com/pt/guides/maip-policies.md) avaliam pontuações de confiança, escopos e profundidade de delegação antes de cada ação sensível
* **Pontuação de confiança** — A avaliação comportamental contínua produz uma pontuação de confiança de 0 a 100
* **Gerenciamento de sessão** — Contextos de execução com tempo limitado e expiração automática
* **Delegação entre locatários** — Agentes podem delegar autoridade entre limites organizacionais
* **Interruptor de segurança** — Revogação de emergência instantânea do acesso de qualquer agente

## Arquitetura

```
┌─────────────────────────────────────────────┐
│              Your Application                │
│  ┌─────────┐  ┌─────────┐  ┌─────────────┐  │
│  │ Agent A │  │ Agent B │  │  Agent C    │  │
│  └────┬────┘  └────┬────┘  └──────┬──────┘  │
│       │            │              │          │
│  ┌────▼────────────▼──────────────▼──────┐  │
│  │         MAIP SDK (JS / Go / Py)       │  │
│  └────────────────┬──────────────────────┘  │
└───────────────────┼─────────────────────────┘
                    │ HTTPS
    ┌───────────────▼───────────────┐
    │   Machine Identity Service    │
    │  ┌──────┐ ┌───────┐ ┌──────┐ │
    │  │Agents│ │Scopes │ │Trust │ │
    │  │      │ │       │ │Scores│ │
    │  └──────┘ └───────┘ └──────┘ │
    └───────────────────────────────┘
```

## Experimente no playground

Cada endpoint MAIP possui um playground de API interativo integrado à documentação. Você pode construir requisições, alternar entre ambientes [Sandbox e Produção](https://docs.truthlocks.com/pt/environments.md#try-it-in-the-api-playground) e enviá-las diretamente — nenhuma ferramenta separada é necessária.

Todos os endpoints MAIP são cobertos, abrangendo dez grupos de API: [Agentes de Máquina](https://docs.truthlocks.com/pt/api-reference/machine-identity/agents/register.md), [Sessões e Ferramentas de Agente](https://docs.truthlocks.com/pt/api-reference/machine-identity/sessions/create.md), [Confiança e Testemunha](https://docs.truthlocks.com/pt/api-reference/machine-identity/trust-scores/get.md), [Políticas MAIP](https://docs.truthlocks.com/pt/api-reference/machine-identity/policies/list.md), [Reivindicações e Documentos de Verdade](https://docs.truthlocks.com/pt/api-reference/machine-identity/truth-claims/create.md), [Conformidade e Anomalias](https://docs.truthlocks.com/pt/api-reference/machine-identity/compliance/create-check.md), [Conjuntos de Dados e Modelos](https://docs.truthlocks.com/pt/api-reference/machine-identity/datasets/attest.md), [Orquestrações e Fluxos de Trabalho](https://docs.truthlocks.com/pt/api-reference/machine-identity/orchestrations/execute.md), [Guardrails e Delegação](https://docs.truthlocks.com/pt/api-reference/machine-identity/guardrails/check.md), e [Observabilidade](https://docs.truthlocks.com/pt/api-reference/machine-identity/observability/events.md).

O playground suporta autenticação `X-API-Key` e Bearer JWT. Use `X-API-Key` para testes rápidos e Bearer JWT quando precisar autenticar com um token de sessão de um agente em execução.

> [!TIP]
>
> Abra qualquer endpoint na referência da API [Machine Agents](https://docs.truthlocks.com/pt/api-reference/machine-identity/agents/register.md) e clique em **Enviar** para testá-lo ao vivo contra o Sandbox.

## Início rápido

### 1. Registrar um agente

```bash cURL theme={null}
curl -X POST https://api.truthlocks.com/v1/agents \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "order-processor",
    "type": "autonomous",
    "scopes": ["receipts:write", "attestations:read"],
    "metadata": {
      "framework": "langchain",
      "model": "gpt-4o",
      "owner": "platform-team"
    }
  }'
```

```javascript JavaScript theme={null}
import { TruthlocksMAIP } from "@truthlocks/sdk";

const maip = new TruthlocksMAIP({ apiKey: process.env.TL_API_KEY });

const agent = await maip.agents.register({
  name: "order-processor",
  type: "autonomous",
  scopes: ["receipts:write", "attestations:read"],
  metadata: {
    framework: "langchain",
    model: "gpt-4o",
    owner: "platform-team",
  },
});
```

### 2. Criar uma Sessão

```bash theme={null}
curl -X POST https://api.truthlocks.com/v1/agent-sessions \
  -H "X-API-Key: $API_KEY" \
  -d '{
    "agent_id": "maip-agent:01JXXXX",
    "scopes": ["receipts:write"],
    "ttl_seconds": 3600,
    "ip_allowlist": ["10.0.0.0/8"]
  }'
```

### 3. Executar com Pontuação de Confiança

Cada ação que o agente realiza é registrada e pontuada. A pontuação de confiança é atualizada continuamente:

```bash theme={null}
# Check current trust score
curl https://api.truthlocks.com/v1/trust-scores/maip-agent:01JXXXX \
  -H "X-API-Key: $API_KEY"
```

Resposta:

```json theme={null}
{
  "agent_id": "maip-agent:01JXXXX",
  "score": 87,
  "factors": {
    "behavioral_compliance": 92,
    "scope_adherence": 95,
    "anomaly_score": 12,
    "peer_attestations": 78
  },
  "trend": "stable",
  "computed_at": "2026-04-06T12:00:00Z"
}
```

### 4. Interruptor de Emergência

Revogue instantaneamente todo o acesso do agente:

```bash theme={null}
curl -X POST https://api.truthlocks.com/v1/agents/maip-agent:01JXXXX/kill \
  -H "X-API-Key: $API_KEY" \
  -d '{ "reason": "Anomalous behavior detected", "revoke_sessions": true }'
```

## Conceitos Essenciais

### Tipos de Agente

| Tipo | Descrição | Caso de Uso |
| - | - | - |
| `autonomous` | Tomada de decisão totalmente autónoma | Bots de negociação, motores de fluxo de trabalho |
| `supervised` | Requer aprovação humana para ações críticas | Moderação de conteúdo, conformidade |
| `delegated` | Atua em nome de outro agente ou usuário | Contas de serviço, proxies |
| `system` | Agente de nível de infraestrutura | Monitoramento, verificações de saúde |

### Escopos

Os escopos seguem um padrão `resource:action`:

* `agents:read` / `agents:write` — Gerenciamento de agentes
* `receipts:write` — Emitir recibos de ação
* `attestations:read` — Ler dados de atestado
* `trust-scores:read` — Acessar pontuações de confiança
* `delegations:offer` / `delegations:accept` — Delegação entre inquilinos
* `compliance:write` — Executar verificações de conformidade
* `orchestrations:execute` — Executar fluxos de trabalho multiagente

### Componentes da Pontuação de Confiança

| Fator | Peso | Descrição |
| - | - | - |
| Conformidade comportamental | 35% | Ações dentro do escopo declarado |
| Adesão ao escopo | 25% | Nenhuma tentativa de acesso fora do escopo |
| Pontuação de anomalia | 20% | Desvio dos padrões históricos |
| Atestados de pares | 10% | Outros agentes atestando o comportamento |
| Higiene da sessão | 10% | Criação/término adequado da sessão |

## Faturamento e Cotas

Os recursos de identidade da máquina são medidos de acordo com seu plano. Quatro contadores de uso do MAIP são rastreados a cada ciclo de faturamento:

| Métrica | O que conta | Desenvolvedor | Negócios | Empresa |
| :- | :- | :- | :- | :- |
| `maip.agents` | Agentes de máquina registrados | 2 | 50 | Dependente do plano |
| `maip.sessions` | Sessões de agente criadas por mês | 100 | 10.000 | Dependente do plano |
| `maip.trust_computes` | Cálculos de pontuação de confiança sob demanda | 50 | 5.000 | Dependente do plano |
| `maip.compliance_checks` | Pedidos de verificação de conformidade | 10 | 500 | Dependente do plano |

Monitore seu consumo com a [API de uso](https://docs.truthlocks.com/pt/api-reference/billing/usage.md) ou no console em **Configurações > Faturamento > Uso** na seção **MAIP**.

> [!NOTE]
>
> Consulte a [visão geral de faturamento](https://docs.truthlocks.com/pt/billing/overview.md#metered-products) para a lista completa de 16 produtos medidos. Atualize seu plano em [console.truthlocks.com/billing](https://console.truthlocks.com/billing) para aumentar os limites.

## Integrações de editor e pipeline

O MAIP se integra às ferramentas que sua equipe já usa. Cada integração gera recibos criptográficos automaticamente.

| Categoria | Integrações |
| :- | :- |
| **Plugins de editor** | [VS Code](https://docs.truthlocks.com/pt/guides/maip-integrations.md#vs-code-extension), [JetBrains](https://docs.truthlocks.com/pt/guides/maip-integrations.md#jetbrains-plugin), [Neovim](https://docs.truthlocks.com/pt/guides/maip-integrations.md#neovim-plugin) (Telescope, statusline, auto-receipt ao salvar) |
| **Assistentes de IA** | [MCP Server](https://docs.truthlocks.com/pt/guides/maip-integrations.md#mcp-server) — 20 ferramentas para assistentes de codificação de IA consultarem agentes, recibos e pontuações de confiança |
| **Pipelines de dados** | [Biblioteca de fluxo de eventos e conector Kafka](https://docs.truthlocks.com/pt/guides/maip-integrations.md#event-streaming) — adaptadores de provedor exigem clientes concretos; gateway autônomo não está pronto |
| **CI/CD** | [GitHub Action](https://docs.truthlocks.com/pt/guides/maip-integrations.md#github-action) — recibos para commits, PRs, releases e artefatos de build |
| **Estruturas de IA** | LangChain, LlamaIndex, CrewAI, AutoGen, OpenAI, Anthropic, AWS Bedrock |
| **Ferramentas da equipe** | Slack, Linear, Notion |

Consulte o [guia de integrações MAIP](https://docs.truthlocks.com/pt/guides/maip-integrations.md) para instruções de configuração e exemplos de código.

## Próximos passos

> [card] [Autorização do agente](https://docs.truthlocks.com/guides/agent-authorization.md)
>
> Aprofunde-se na autorização baseada em escopo e no gerenciamento de sessões.

> [card] [Políticas MAIP](https://docs.truthlocks.com/guides/maip-policies.md)
>
> Regras de aplicação em tempo de execução baseadas em pontuações de confiança, escopos e profundidade de delegação.

> [card] [Pontuações de confiança](https://docs.truthlocks.com/guides/trust-scores.md)
>
> Compreendendo e configurando a avaliação contínua de confiança.

> [card] [Delegação entre locatários](https://docs.truthlocks.com/guides/cross-tenant-delegation.md)
>
> Permitir que agentes operem em diferentes limites organizacionais.

> [card] [Orquestração de IA](https://docs.truthlocks.com/guides/ai-orchestration.md)
>
> Execução de fluxo de trabalho multiagente com salvaguardas de segurança.

> [card] [Integrações MAIP](https://docs.truthlocks.com/guides/maip-integrations.md)
>
> Conecte agentes ao Slack, GitHub, VS Code, Neovim, LangChain e muito mais.


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