Aillom Docs
Dashboard

Aillom Connect

O Aillom Connect permite que cada workspace do MEX use uma conta Connect própria para expor ferramentas externas ao agente.

Na prática:

  • A chave mex_... continua sendo a chave da API do MEX.
  • A chave ac_live_... é a chave do Aillom Connect.
  • O MEX guarda a chave do Connect criptografada no workspace e usa essa chave apenas no backend.
  • A IA recebe as ferramentas disponíveis pelo manifesto do Connect e executa as ações pelo executor do Connect.

Vincular pelo dashboard

  1. Acesse Configurações.
  2. Abra a aba Integrações.
  3. No card Aillom Connect, cole a API key ac_live_... da conta Connect daquele cliente.
  4. Clique em Vincular conta.
  5. Clique em Testar conexão para validar o manifesto.

Depois de salva, a chave completa não aparece novamente no MEX. O dashboard mostra apenas o prefixo da chave, o status e a última validação.

Com o vínculo ativo, a página Ferramentas do MEX passa a listar também as tools dos apps conectados no Connect. Essas ferramentas são exibidas como itens somente-leitura porque a fonte canônica continua sendo o manifesto do Connect.

Listar tools no MEX

O endpoint autenticado do MEX também retorna a lista agregada de ferramentas:

curl https://api.mex.aillom.com.br/api/tools \
  -H "Authorization: Bearer mex_sua_chave_de_workspace" \
  -H "x-workspace-id: uuid-do-workspace"

A resposta inclui:

  • tools locais criadas no MEX com source: "local";
  • tools dos apps conectados no Aillom Connect com source: "aillom_connect";
  • metadados do Connect como provider, risk_level, requires_approval e readonly.

Exemplo de item vindo do Connect:

{
  "id": "aillom-connect:google_calendar_create_event",
  "name": "google_calendar_create_event",
  "display_name": "Criar evento no Google Calendar",
  "description": "Cria um evento no calendário primário conectado pelo Aillom Connect.",
  "url": "aillom-connect://google_calendar_create_event",
  "method": "POST",
  "params": {
    "type": "object",
    "properties": {
      "summary": { "type": "string" },
      "startDateTime": { "type": "string" },
      "endDateTime": { "type": "string" }
    }
  },
  "source": "aillom_connect",
  "provider": "google-calendar",
  "risk_level": "medium",
  "requires_approval": true,
  "readonly": true
}

Tools do Connect não são criadas, editadas ou removidas pelo MEX. Para alterar apps, escopos ou operações disponíveis, ajuste a conexão no Aillom Connect; o MEX reflete o manifesto no próximo carregamento.

Como a IA usa as tools

Quando o workspace está vinculado ao Connect, o MEX faz uma chamada server-side para:

GET /api/v1/tools/manifest
Authorization: Bearer ac_live_...

Cada capability retornada vira uma ferramenta disponível para o agente. Quando o modelo escolhe uma ferramenta, o MEX executa:

POST /api/v1/tools/execute
Authorization: Bearer ac_live_...
Content-Type: application/json

{
  "operation_id": "google_calendar_create_event",
  "params": {
    "summary": "Reunião com cliente",
    "startDateTime": "2026-05-20T14:00:00-04:00",
    "endDateTime": "2026-05-20T15:00:00-04:00"
  }
}

O usuário final não vê a chave do Connect e o modelo não recebe credenciais no prompt.

Endpoints do MEX

Os endpoints abaixo exigem autenticação no MEX e operam no workspace ativo via header x-workspace-id.

Obter status

curl https://api.mex.aillom.com.br/api/workspaces/active/aillom-connect \
  -H "Authorization: Bearer mex_sua_chave_de_workspace" \
  -H "x-workspace-id: uuid-do-workspace"

Resposta:

{
  "connected": true,
  "status": "connected",
  "api_key_prefix": "ac_live_abcd",
  "last_validated_at": "2026-05-17T16:00:00.000Z",
  "last_used_at": "2026-05-17T16:00:00.000Z"
}

Salvar ou substituir chave

curl -X PUT https://api.mex.aillom.com.br/api/workspaces/active/aillom-connect \
  -H "Authorization: Bearer mex_sua_chave_de_workspace" \
  -H "x-workspace-id: uuid-do-workspace" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "ac_live_sua_chave_do_connect"
  }'

Apenas proprietários e administradores do workspace podem salvar ou substituir a chave.

Testar conexão

curl -X POST https://api.mex.aillom.com.br/api/workspaces/active/aillom-connect/test \
  -H "Authorization: Bearer mex_sua_chave_de_workspace" \
  -H "x-workspace-id: uuid-do-workspace"

Resposta:

{
  "success": true,
  "workspace_id": "workspace-do-connect",
  "connection_count": 2,
  "tools_count": 12
}

Remover vínculo

curl -X DELETE https://api.mex.aillom.com.br/api/workspaces/active/aillom-connect \
  -H "Authorization: Bearer mex_sua_chave_de_workspace" \
  -H "x-workspace-id: uuid-do-workspace"

Segurança

  • A chave ac_live_... fica criptografada no banco do MEX.
  • O frontend recebe apenas o prefixo da chave.
  • O MEX só aceita URLs HTTP/HTTPS, e em produção exige HTTPS.
  • A execução das tools passa pelo backend do MEX e pelo middleware de API key do Connect.
  • O status do vínculo é atualizado quando o manifesto ou uma execução falha.