# Agentes

Um agente de IA pode ser conectado à conta para consultar a sua configuração, tipos de evento, campos, regras, métricas, monitoramentos e listas, e os valores das métricas ao longo do tempo. A conexão usa o protocolo MCP (Model Context Protocol), suportado pelos assistentes de código e de chat mais comuns.

O recurso está **em fase de testes**. As funcionalidades disponíveis e os limites de uso podem mudar a qualquer momento, sem aviso prévio.

## O que o agente pode ver

O acesso é concedido em seu nome e opera com as **suas** permissões: o agente nunca alcança algo que o seu [perfil de acesso](/pt/admin/users/#perfis-de-acesso) não alcança. Duas verificações são aplicadas a cada chamada, e ambas precisam passar: a permissão do usuário que autorizou e a permissão consentida ao agente no momento da conexão.

| Permissão | O que autoriza |
| :-------- | :------------- |
| Leitura da configuração | consultar tipos de evento, campos, regras, análises, métricas, monitoramentos e listas |
| Leitura dos dados da conta | consultar os eventos recebidos, os valores medidos de uma métrica e os valores já recebidos por um campo |
| Escrita da configuração | alterar o nome e a descrição de um campo |

A leitura dos dados da conta alcança dados pessoais presentes nos eventos, como emails, endereços IP, BINs de cartão e identificadores de dispositivo. Por isso ela é consentida à parte da leitura da configuração: uma conexão pode ler a configuração da conta sem alcançar nenhum dado de evento.

O agente atua sobre uma conta por vez, indicada na tela de conexão. Para consultar outra conta, conecte o agente novamente a partir dela.

## Como conectar

Em **Agentes > Conectar agente**:

1. Selecione o agente pelo logotipo. A tela passa a exibir as instruções específicas dele.
2. Configure o agente com a **URL do servidor MCP** e o **client_id** informados na tela. Onde o agente pedir um segredo do cliente (`client secret`), deixe em branco: a conexão não usa segredo.
3. Autorize o acesso à conta pelo navegador, quando o agente solicitar.

Agentes de linha de comando apresentam, em vez dos passos acima, um comando pronto para executar no terminal, seguido da mesma autorização pelo navegador.

Estão previstos hoje **Claude Code**, **Claude Desktop**, **Cursor**, **VS Code** e **Gemini CLI**. Um agente ainda não cadastrado precisa ser habilitado por nós antes de conectar: fale com o suporte se o seu não estiver na lista.

## Agentes conectados

**Agentes** lista as conexões existentes na conta em nome do usuário autenticado, com o cliente, a data da autorização e a última atividade registrada, atualizada em intervalos de quinze minutos. Uma conexão que nunca foi usada é identificada como tal.

**Desconectar** encerra o acesso do agente de imediato, sem afetar as demais conexões nem as dos outros usuários. Um agente desconectado volta a operar apenas depois de uma nova autorização.

## O que o agente consegue fazer

O agente dispõe de operações de listagem e de detalhamento sobre cada tipo de configuração, além da consulta aos valores já observados em um campo:

| Operação | Conteúdo |
| :------- | :------- |
| Conta | dados gerais da conta conectada, com os consentimentos concedidos à conexão |
| Tipos de evento | lista dos tipos e o detalhe de cada um, com os seus campos |
| Campos | valores já observados em um campo, inclusive os valores recebidos por um campo de lista sem itens cadastrados |
| Eventos | contagem dos eventos de um período em blocos de tempo, opcionalmente dividida por um campo, e as próprias linhas de evento |
| Regras | lista das regras e o detalhe de uma versão, com as suas condições e ações |
| Análises | lista das análises e o detalhe de uma, com o efeito de cada célula e as regras que a executam e a registram |
| Métricas | lista das métricas, o detalhe de uma, com dimensões, agregações e filtros, e os valores medidos por período, com a faixa esperada e os alertas do intervalo |
| Monitoramentos | lista dos monitoramentos e o detalhe de um, com os seus critérios |
| Listas | lista das listas configuradas e o detalhe de uma |
| Edição de campo | alteração do nome e da descrição de um campo |

A consulta de eventos admite os mesmos filtros de [Explorar](/pt/admin/explore/), inclusive a referência a uma lista e a [comparação entre campos](/pt/admin/explore/#comparação-entre-campos). Ela responde sobre uma janela recente, não sobre todo o histórico da conta.

Em clientes compatíveis com interfaces do MCP, a consulta de valores de uma métrica é apresentada como gráfico na própria conversa.

As perguntas típicas são de orientação e de revisão: qual regra decide determinado tipo de evento, quais métricas existem sobre um campo, o que uma versão de regra faz antes de publicá-la, quantos eventos de um tipo chegaram por status no período.

Cada resposta traz também o endereço do artigo correspondente desta documentação, de modo que o agente consulte a referência em lugar de deduzir o comportamento da plataforma.

## Consentimentos

As operações que o agente alcança dependem dos consentimentos concedidos no momento da conexão. Uma operação não consentida não aparece para o agente, o que a torna indistinguível de uma que não existe.

Por isso a consulta à conta informa quais consentimentos a conexão recebeu e quais operações ficaram retidas, com o consentimento que falta em cada uma. Um agente que responde não ser possível fazer algo pode, com isso, verificar se a operação existe e apenas não foi consentida.

A liberação exige reconectar o agente concedendo o consentimento que falta, conforme [Como conectar](#como-conectar). Uma conexão existente não passa a alcançar mais nada sem essa nova autorização.

As operações que o [perfil de acesso](/pt/admin/users/#perfis-de-acesso) do usuário não alcança não são relacionadas como retidas: nenhuma reautorização as concederia, porque a verificação que as barra é a do usuário, não a do agente.

### Mudança no consentimento de leitura

A consulta dos valores de uma métrica e a listagem dos valores de um campo passaram a exigir a **leitura dos dados da conta**, antes alcançadas pela leitura da configuração. Uma conexão autorizada apenas para ler a configuração deixa de alcançar as duas, e volta a alcançá-las depois de reconectada com o novo consentimento.

## Limites de uso

As chamadas são limitadas por usuário e por conta em uma janela de tempo, com um limite próprio para cada operação, dimensionado conforme o custo e a frequência esperada. Um agente que ultrapassa o limite recebe a recusa e volta a operar na janela seguinte.