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

# Integrações MAIP

> Conecte seus agentes de IA às ferramentas e plataformas que sua equipe já usa.

# Integrações MAIP

O Machine Agent Identity Protocol (MAIP) vem com integrações que trazem identidade de agente, recibos e pontuação de confiança para seus fluxos de trabalho existentes. Evidências locais, envio de recibos hospedados e verificação de assinatura são operações separadas. Configure e teste a integração que você usa; a instalação por si só não cria um registro de auditoria completo.

> [!NOTE]
>
> **Pré-requisitos:** Você precisa de uma conta Truthlocks com uma chave de API e pelo menos um agente registrado. Consulte o [guia de identidade de máquina](https://docs.truthlocks.com/pt/guides/machine-identity.md) para registrar seu primeiro agente.

> [!TIP]
>
> Navegue pelas integrações disponíveis no [Hub de Integrações](https://truthlocks.com/resources/integrations). Os links são agrupados por SDK, framework de IA, editor e ferramenta de colaboração.

## Ferramentas do desenvolvedor

### Extensão VS Code

Um painel lateral para navegar por recibos, gerar recibos do seu editor e visualizar dados de confiança. Instale-o no [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=truthlocks.maip-vscode).

**O que ele faz:**

* Navegar e pesquisar recibos MAIP na barra lateral
* Gerar recibos para alterações de código diretamente do editor
* Visualizar pontuações de confiança do agente e cadeias de recibos

**Instalação:**

1. Abra o VS Code e vá para a visualização de Extensões (`Ctrl+Shift+X` / `Cmd+Shift+X`).
2. Procure por "Truthlocks MAIP".
3. Clique em **Instalar**.

Alternativamente, instale pela linha de comando:

```bash theme={null}
code --install-extension truthlocks.maip-vscode
```

Após a instalação, abra o painel lateral do MAIP e insira sua chave de API e ID de agente para conectar.

### Plugin JetBrains

Integração MAIP para IntelliJ, PyCharm e WebStorm com os mesmos recursos de navegação e geração de recibos da extensão do VS Code.

### Plugin Neovim

Instale o plugin `truthlocks/maip.nvim` lançado, com curl disponível no seu PATH:

```lua theme={null}
-- lazy.nvim
{ "truthlocks/maip.nvim", tag = "v1.1.0", main = "maip",
  opts = {
    api_url = "https://sandbox-api.truthlocks.com/v1",
    api_key = vim.env.MAIP_API_KEY or "",
    agent_id = vim.env.MAIP_AGENT_ID or "",
    auto_receipt_on_commit = false,
    telescope = false,
  } }
```

Use `:MAIPListAgents`, `:MAIPCreateReceipt`, `:MAIPListReceipts`,
`:MAIPVerifyReceipt`, `:MAIPShowTrust` e `:MAIPDashboard`. Os metadados do recibo são
não é uma assinatura verificada. Os recibos de commit automáticos são opcionais e observam os suportados
eventos de commit concluídos; não há opção `auto_receipt` de salvamento nesta versão.
Consulte o [README versionado](https://github.com/truthlocks/maip.nvim) para Telescope
configuração e os limites atuais de teste interativo.

### Servidor MCP

Instale o executável na máquina que executa o seu host MCP:

```sh theme={null}
npm install --global @truthlocks/maip-mcp-server@1.2.4
```

```json theme={null}
{
  "mcpServers": {
    "truthlocks": {
      "command": "maip-mcp-server",
      "env": {
        "MAIP_API_URL": "https://sandbox-api.truthlocks.com/v1",
        "MAIP_API_KEY": "REPLACE_WITH_WORKSPACE_TEST_KEY",
        "MAIP_TIMEOUT_MS": "30000",
        "MAIP_MAX_RETRIES": "3"
      }
    }
  }
}
```

Forneça credenciais através da configuração segura do host. Use uma chave e um agente
do mesmo ambiente. Peça ao host para listar as ferramentas disponíveis e, em seguida, use
`maip_list_agents`, `maip_list_receipts` e `maip_verify_receipt`. Uma assinatura positiva
o resultado requer `valid: true`, `signature_verified: true` e `verdict: "VALID"`.
A verificação de transparência é um resultado separado. As gravações não são automaticamente repetidas.

## Colaboração em equipe

As integrações Slack, Linear e Notion exigem seus próprios aplicativos/espaços de trabalho reais
credenciais além da autenticação Truthlocks. Sua cadeia completa de provedor-para-recibo
a aceitação ainda está pendente. Não trate a disponibilidade da fonte, testes locais ou um
Chave de API do Truthlocks como prova de que um espaço de trabalho externo está conectado.

Revise o README do pacote de origem para permissões e configuração do provedor:
[Slack](https://github.com/truthlocks/truthlock/tree/main/packages/maip-slack),
[Linear](https://github.com/truthlocks/truthlock/tree/main/packages/maip-linear),
[Notion](https://github.com/truthlocks/truthlock/tree/main/packages/maip-notion).
Use um espaço de trabalho de teste dedicado antes de habilitar o processamento de eventos reais.

### Configuração e validação do Slack

Slack é uma instalação de origem, não um pacote npm `@truthlocks/maip-slack` publicado.
Sua autenticação de bot e uma submissão de mensagem de teste autorizada passaram pelo provedor
verificações. Os fluxos de trabalho completos de comando de barra de usuário pessoal e eventos hospedados permanecem em desenvolvimento
validação. Siga o [README do Slack](https://github.com/truthlocks/truthlock/tree/main/packages/maip-slack)
para a compilação revisada e todas as configurações necessárias.

Vincule o aplicativo a `SLACK_TEAM_ID` e `SLACK_ALLOWED_USER_IDS` pessoais explícitos.
Use `MAIP_AGENT_ID` de um agente Truthlocks registrado existente para criação;
um ID de Membro do Slack não é uma identidade de máquina. Forneça uma chave de sandbox e
`https://sandbox-api.truthlocks.com/v1` durante a avaliação. Comandos são registrados
nas configurações do aplicativo do Slack. Tanto o modo HTTP quanto o Socket fornecem `/webhook/maip`, mas
hospedar o listener não assina automaticamente os eventos do Truthlocks a ele.
As aprovações de delegação permanecem em revisão no Console autenticado. Proteção de repetição local
é local ao processo; a entrega em produção precisa de rastreamento upstream durável.

### Configuração e validação do Notion

Notion é um pacote de origem privada, não uma instalação npm. Aceitação de QA real
criou uma página filha e esquemas de banco de dados, inseriu um recibo de espaço de trabalho existente,
repetiu a sincronização sem duplicar essa página e verificou a leitura do provedor.
A automação contínua hospedada e a recuperação durável permanecem em validação.

Conecte apenas a página pretendida usando o menu **••• → Conexões** do Notion. Siga o
[README do Notion](https://github.com/truthlocks/truthlock/tree/main/packages/maip-notion)
para inicializar bancos de dados uma vez e reutilizar seus IDs. Use `WEBHOOK_SECRET` com o
contrato HMAC/timestamp versionado; solicitações não assinadas são rejeitadas. Status do recibo
é metadados, então um recibo concluído não verifica automaticamente o Notion
caixa **Verificado**. Use a verificação explícita de assinatura separadamente.

## CI/CD

As entradas da ação MAIP são `maip-api-url`, `maip-api-key` e `maip-agent-id`.
Os nomes mais antigos `api-key` e `agent-id` não são entradas declaradas. Para um revisado
checkout da fonte com seu `dist/index.js` construído, um fluxo de trabalho de QA explicitamente acionado
pode usar esta etapa:

```yaml theme={null}
- uses: ./packages/maip-github-action
  with:
    maip-api-url: https://sandbox-api.truthlocks.com/v1
    maip-api-key: ${{ secrets.TRUTHLOCKS_API_KEY }}
    maip-agent-id: ${{ vars.TRUTHLOCKS_AGENT_ID }}
    mode: receipt
    event-type: commit
    create-check: 'false'
    post-comment: 'false'
```

Este é um caminho de ação local após o checkout e a construção, não um Marketplace não verificado
tag. Fixe as versões revisadas ao distribuir a ação. Verifique/comente a publicação
requer permissões deliberadas do GitHub e aceitação separada; nunca exponha segredos
para fluxos de trabalho de forks não confiáveis. Consulte o [README da ação](https://github.com/truthlocks/truthlock/tree/main/packages/maip-github-action).

## Conectores de modelo de IA

Os wrappers Python capturam eventos emitidos através da integração configurada. Hashes locais não são assinaturas de servidor. As credenciais do provedor, as credenciais do Truthlocks e o envio hospedado são configurados separadamente; inspecione os metadados que você envia e não presuma que o hashing remove as obrigações de privacidade.

### Frameworks suportados

| Framework | Instalar |
| :- | :- |
| LangChain | `pip install truthlocks-langchain` |
| LlamaIndex | `pip install truthlocks-llamaindex` |
| CrewAI | `pip install truthlocks-crewai` |
| AutoGen | `pip install truthlocks-autogen` |
| OpenAI | `pip install truthlocks-openai` |
| Anthropic | `pip install truthlocks-anthropic` |
| AWS Bedrock | `pip install truthlocks-bedrock` |

**Exemplo completo de LangChain local (sem solicitação hospedada):**

```python theme={null}
from langchain_core.runnables import RunnableLambda
from truthlocks_langchain import MAIPRunnableWrapper
from maip_ai_connectors.config import MAIPConfig

chain = RunnableLambda(lambda value: value.upper())
wrapped = MAIPRunnableWrapper(chain, config=MAIPConfig(auto_receipt=False))
print(wrapped.invoke("hello"))
receipts = wrapped.get_receipts()
print(receipts[0].payload_hash)
wrapped.clear_receipts()
```

`payload_hash` descreve evidências locais. Para envio hospedado, use `MAIPClient.create_receipt`
e verifique o `receipt_id` do servidor retornado; o [README do LangChain](https://github.com/truthlocks/truthlock/tree/main/packages/truthlocks-langchain)
contém o exemplo de submissão assíncrona. Para hooks automáticos assíncronos, descarregue e
fechar o wrapper e inspecionar os resultados da submissão antes do desligamento. Chamadas fora do
wrapper configurado não são observadas.

## Pipelines de dados e ML

### Conector Kafka

O conector Go envia impressões digitais de mensagens como recibos MAIP `data.attestation`
usando um agente existente. Seu cliente HTTP usa `/v1/agent-receipts`, preserva parcial
resultados de lote e requer uma assinatura confirmada para verificação bem-sucedida.

Instale `github.com/truthlocks/kafka-maip-connector@v0.1.0` com `go get`.
Consulte o [exemplo de lançamento e conclusão](https://github.com/truthlocks/kafka-maip-connector/releases/tag/v0.1.0).
A chave de API seleciona o espaço de trabalho e o ambiente; um ID de locatário fornecido pelo chamador não
não substitui a autorização. Bytes de mensagem e chaves de mensagem brutas não são carregados.

Os wrappers produtor/consumidor armazenam recibos em buffer na memória. Entrega e recebimento do broker
entrega são operações separadas; uma gravação bem-sucedida no Kafka não garante uma
recibo foi retido. A entrega de auditoria necessária precisa de uma caixa de saída de aplicativo durável
e tratamento explícito de falhas. Consulte a evidência de lançamento antes do uso em produção.

### Streaming de eventos

Instale [Go event-stream v0.1.0](https://github.com/truthlocks/maip-event-stream/releases/tag/v0.1.0):

```sh theme={null}
go get github.com/truthlocks/maip-event-stream@v0.1.0
```

A biblioteca inclui um cliente Redis concreto e interfaces de adaptador para NATS
JetStream, EventBridge e Kinesis. Consumidores Redis reconectando escaneiam seus próprios
entradas pendentes antes de novas mensagens; o processamento falho permanece não reconhecido.
Mantenha os nomes dos consumidores estáveis entre as reinicializações. Reivindicando o pendente de outro consumidor
entradas ainda requer um processo de recuperação explícito. O artefato publicado passou
um teste isolado de reinício/reconhecimento real do Redis e o conjunto completo de testes de corrida do Go.
Outros adaptadores de backend exigem implementações de cliente reais e autenticadas. Esses adaptadores
envelopes de eventos de transporte; eles não criam ou verificam automaticamente assinaturas MAIP.
A geração de recibos Kafka é um conector separado, descrito acima.

> [!WARNING]
>
> O gateway autônomo não está pronto para implantação: suas fábricas de clientes de backend
> não estão conectados, e agora ele se recusa a iniciar em vez de relatar tarefas não realizadas
> publicações como aceitas. Não há `truthlocks_streaming.StreamingGateway` lançado
> API Python correspondente ao exemplo mais antigo nesta página.

A deduplicação agora usa um cache exato limitado de identidades de eventos confirmadas, com escopo
para locatário e fonte. Publicações com falha não são armazenadas em cache. As tentativas padrão são zero;
tentativas explícitas fornecem entrega pelo menos uma vez, não garantias de exatamente uma vez.
O middleware de lote lida com um evento por vez, portanto, não pode adivinhar itens com falha
de contagens agregadas. A remoção do cache e a reinicialização do processo podem permitir duplicatas.

O validador de recibos verifica a estrutura e os links de hash locais; não é uma assinatura
verificador. Mantenha o roteamento autenticado, retenção durável e validação criptográfica
no design da sua aplicação.

### MLflow, DVC e Delta Lake

Instale `mlflow-maip`, `dvc-maip` ou `delta-lake-maip` para os metadados correspondentes
construtores. Esses pacotes produzem evidências estruturadas locais; a instalação de um não
tornar cada operação de framework um recibo hospedado assinado. Não há suporte
`truthlocks_mlflow.TruthlocksPlugin.enable` API correspondente ao exemplo mais antigo.

Use os exemplos locais e hospedados completos nos READMEs de origem:
[MLflow](https://github.com/truthlocks/truthlock/tree/main/packages/mlflow-maip),
[DVC](https://github.com/truthlocks/truthlock/tree/main/packages/dvc-maip),
[Delta Lake](https://github.com/truthlocks/truthlock/tree/main/packages/delta-lake-maip).
Os metadados do provedor e os URIs de artefato não verificam independentemente os bytes do artefato ou
provar que uma operação externa ocorreu. A verificação de assinatura hospedada não
estabelecer a inclusão no log de transparência, a menos que essa verificação separada seja bem-sucedida.

## Docker

Os arquivos de origem do contêiner não estabelecem que uma imagem pública foi lançada ou
passou na aceitação. As imagens `truthlocks/*:latest` listadas anteriormente e combinadas
O exemplo de composição não foi verificado como uma implantação funcional e não é um
início rápido suportado. Não infira a disponibilidade da imagem a partir desses nomes históricos.

Use o lançamento do pacote publicado e seu README para cada integração. Se estiver construindo
um contêiner de fonte revisada, fixe essa revisão e dependências, forneça segredos
através do seu tempo de execução e teste a conexão real do provedor. O Slack adicionalmente
requer suas credenciais de aplicativo reais; uma chave de API Truthlocks sozinha é insuficiente.
O gateway de fluxo de eventos autônomo permanece indisponível conforme descrito acima.

## Próximos passos

> [card] [Identidade da máquina](https://docs.truthlocks.com/guides/machine-identity.md)
>
> Registre seu primeiro agente e entenda o protocolo MAIP.

> [card] [Autorização do agente](https://docs.truthlocks.com/guides/agent-authorization.md)
>
> Configure escopos, sessões e acesso a ferramentas para seus agentes.

> [card] [Downloads](https://truthlocks.com/resources/downloads)
>
> Encontre as versões publicadas de CLI, SDK e IDE e suas instruções de instalação.

> [card] [Central de integrações](https://truthlocks.com/resources/integrations)
>
> Navegue por todas as integrações por categoria.

### Linear

Autenticação real do provedor, pesquisa de problemas do SDK e um comentário de recibo com leitura de volta
passou em uma questão de QA explicitamente autorizada. Isso não estabelece webhook hospedado
criação de recibo ou sincronização contínua. O listener de origem verifica o Linear
Assinatura HMAC e carimbo de data/hora assinado, e restringe eventos à organização configurada
e IDs de equipe. A automação de marcos de projeto permanece indisponível em vez de emitir
evidência estimada. Consulte a [configuração e limites do Linear](https://github.com/truthlocks/truthlock/tree/main/packages/maip-linear#readme).


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