Conectar agente de IA ao Notion ou Confluence sem bagunça

Para conectar um agente de IA ao Notion ou Confluence, crie uma conta dedicada, somente leitura, que enxergue um conjunto pequeno e nomeado de espaços, e faça o agente responder apenas com base em páginas que tenham um marcador explícito de aprovação. Mantenha os rascunhos de fora por status, por localização e por data de revisão, para que texto inacabado nunca chegue ao agente. O trabalho é, em grande parte, editorial: decidir quais páginas valem como verdade antes de qualquer integração tocar nelas.

Principais pontos

• Libere espaços de acordo com as perguntas que o agente precisa responder, não pela conveniência. Comece com poucos espaços que tenham dono e manutenção, e deixe todo o resto de fora.
• Use uma conta exclusiva do agente, com acesso somente leitura. As permissões dela são o teto do que ele poderá repetir.
• Marque as páginas aprovadas com metadados: status, responsável, público e data de revisão. Só o dono da página aplica o marcador, nunca o agente.
• Filtre antes de indexar, não depois. Texto que nunca foi carregado não pode aparecer em uma resposta.
• Faça o agente citar a página, o responsável e a data de revisão, e dizer com clareza quando nenhuma página aprovada cobre a pergunta.

Por que conectar um agente a uma wiki costuma dar errado?

Uma wiki é escrita por muita gente ao longo de muito tempo. Ela guarda procedimentos atuais ao lado de procedimentos aposentados, propostas que ninguém terminou, atas de reunião cheias de opiniões e páginas coladas de outros lugares. Uma pessoa que lê nota o aviso de rascunho, confere a data ou pergunta a um colega. Um agente que recupera trechos enxerga apenas texto, e uma regra desatualizada soa tão segura quanto a vigente.

Quatro falhas aparecem com frequência:

• Respostas desatualizadas: o agente cita uma regra que já foi substituída, porque a página antiga nunca foi arquivada.
• Conteúdo vazado: um espaço privado (RH, financeiro, jurídico) ficou acessível porque a conexão foi concedida no nível do workspace inteiro.
• Conflitos não resolvidos: duas páginas se contradizem e o agente escolhe uma em silêncio.
• Instruções embutidas: uma página contém um texto que parece um comando, e o agente o trata como tal. Materiais como o guia da OWASP sobre prevenção de prompt injection explicam por que o conteúdo das páginas deve ser sempre tratado como dado, nunca como instrução.

Cenário ilustrativo: uma empresa de serviços conecta seu assistente ao workspace inteiro. Um cliente pergunta quanto tempo leva o onboarding, e o agente responde com base em uma página de brainstorming na qual um gerente rascunhou uma meta ambiciosa. A página nunca foi feita para clientes, nunca foi aprovada e ainda assim era a melhor correspondência de texto. Nada estava quebrado na integração. A wiki simplesmente não tinha como dizer quais páginas eram verdadeiras.

Quais espaços liberar primeiro?

Parta da função, não da ferramenta. Anote as perguntas principais que o agente precisa responder em seu primeiro papel e descubra onde estão as respostas oficiais. Isso costuma apontar para um punhado de espaços, não para o workspace todo.

Use este guia de decisão:

• Liberar primeiro: procedimentos operacionais, descrições de serviços, políticas voltadas ao cliente e guias de onboarding, cada um com uma equipe responsável que ainda os mantém.
• Liberar depois, após revisão: espaços de projetos, FAQs internos que misturam públicos e manuais de equipe com qualidade irregular.
• Nunca liberar: RH, financeiro, jurídico, material de conselho, páginas pessoais ou privadas, anotações confidenciais de clientes e qualquer página onde alguém colou uma credencial. Remova essas credenciais das páginas de qualquer forma, com ou sem agente.
• Deixar de fora: arquivos mortos, espaços migrados e tudo o que não tem dono. Se ninguém responde por uma página, o agente não deve falar por ela.

Depois, molde a conexão em si. Crie uma identidade dedicada ao agente em vez de emprestar o login de uma pessoa. No Notion, isso normalmente significa uma integração que enxerga apenas as páginas e bancos de dados compartilhados com ela de forma explícita. No Confluence, significa um usuário de serviço com permissão nos espaços escolhidos e em nada mais. Deixe tudo somente leitura até o caminho de leitura provar que funciona. O raciocínio é o mesmo do menor privilégio para agentes de IA: comece com o menor acesso possível e amplie de forma deliberada. Se você está em dúvida entre conta de serviço e tokens delegados, o texto sobre conta de serviço ou OAuth para agentes de IA explica a troca.

O público também importa. Se o agente atende a equipe interna, ele pode ler procedimentos internos. Se atende clientes, deve ler somente páginas seguras para clientes, mesmo que a wiki guarde mais coisas. A orientação da OWASP sobre autorização lembra que decisões de acesso pertencem a permissões aplicadas pelo sistema, não a uma frase no prompt pedindo que o agente tenha cuidado.

Como marcar uma página como aprovada?

A aprovação precisa estar visível nos metadados da página, para que um script ou um filtro de recuperação consiga lê-la. Um parágrafo dizendo que a página foi revisada não basta.

No Notion, um banco de dados com propriedades funciona bem: uma propriedade de status, um responsável, um público e uma data da próxima revisão. No Confluence, rótulos e propriedades de página cumprem o mesmo papel: um rótulo como agente-aprovado, mais um bloco de propriedades com responsável, público e data de revisão. Os campos exatos importam menos do que usar os mesmos em todo lugar.

Uma página conta como aprovada quando atende a todas estas condições:

• Tem um responsável nomeado que continua na empresa e ainda responde pelo tema.
• Trata de um único assunto com clareza, em vez de misturar uma política com comentários.
• Informa o público: equipe, clientes ou ambos.
• Tem uma data de revisão que ainda não venceu.
• O próprio responsável aplicou o marcador de aprovado, não um script em massa e não o agente.

Duas regras mantêm o sistema honesto. Primeiro, editar cancela a aprovação. Se uma página muda depois de aprovada, ela sai do alcance do agente até que o responsável aprove de novo. Nenhuma das duas ferramentas pode fazer isso nativamente do jeito que você quer, então uma pequena etapa de sincronização que compara o horário da última edição com o da aprovação é uma salvaguarda sensata. Segundo, datas de revisão vencem. Uma página fora do prazo sai automaticamente das fontes do agente, o que empurra os responsáveis a revisar em vez de deixar a wiki se deteriorar em silêncio.

Isso também define como o agente busca. Em uma arquitetura de recuperação (o padrão básico é conhecido como geração aumentada por recuperação, ou RAG), carregue no índice apenas as páginas aprovadas. Filtrar na ingestão é mais forte do que filtrar na hora da pergunta, porque uma página não aprovada que nunca foi indexada não pode ser encontrada por acidente.

Como manter rascunhos fora das respostas do agente?

Nenhum controle sozinho basta. Combine várias camadas, para que um erro isolado não vire uma resposta errada.

• Localização: mantenha os rascunhos em um espaço ou seção separada que a conta do agente não enxerga. É a camada mais forte, pois não depende de alguém lembrar de colocar um rótulo.
• Status: tudo o que não tem o marcador de aprovado fica de fora, inclusive páginas marcadas como em andamento, proposta ou arquivada.
• Somente versões publicadas: quando a ferramenta distingue um rascunho não publicado da versão ativa da página, o agente lê só a versão ativa.
• Atualidade: páginas com a data de revisão vencida são removidas do índice.
• Comportamento na resposta: toda resposta cita a página, o responsável e a data de revisão. Se nenhuma página aprovada cobre a pergunta, o agente diz isso e encaminha para uma pessoa, em vez de improvisar.
• Conteúdo como dado: o texto dentro de uma página nunca altera as regras do agente, não importa como esteja escrito.

Conflitos merecem uma regra própria. Quando duas páginas aprovadas divergem, o agente deve relatar o conflito e citar os dois responsáveis, em vez de escolher em silêncio. Isso transforma um problema escondido da wiki em uma tarefa visível para quem pode resolvê-lo.

Menos também é melhor para a qualidade das respostas. A orientação da Anthropic sobre engenharia de contexto defende dar ao agente um conjunto enxuto e relevante de informações, em vez de tudo o que está disponível. Um conjunto curado de páginas aprovadas é mais fácil de consultar e mais fácil de auditar do que um workspace inteiro.

Qual é um plano seguro, passo a passo, para a primeira conexão?

Siga esta ordem. Cada passo tem um resultado claro, e nenhum exige reescrever a wiki inteira.

• Passo um: defina o papel do agente e liste as perguntas que ele precisa responder, com o público de cada uma.
• Passo dois: relacione essas perguntas aos espaços candidatos e escolha os poucos que têm responsáveis ativos. Anote também os espaços excluídos.
• Passo três: adicione os campos de aprovação (status, responsável, público, data de revisão) aos espaços escolhidos e peça aos responsáveis que aprovem suas páginas principais. Aprove primeiro um núcleo pequeno.
• Passo quatro: crie a identidade dedicada, somente leitura, e conceda acesso apenas aos espaços escolhidos. Guarde as credenciais em um cofre de segredos gerenciado, nunca em uma página da wiki.
• Passo cinco: monte o índice só com páginas aprovadas, com uma atualização agendada que remove páginas quando o marcador, a data de revisão ou o acesso mudam.
• Passo seis: defina as regras de resposta: citar fonte, responsável e data de revisão, relatar conflitos e recusar quando nada aprovado se aplica.
• Passo sete: teste com perguntas reais, incluindo perguntas armadilha. Pergunte sobre temas que só existem em rascunhos, em espaços excluídos e em páginas vencidas, e confirme que o agente recusa todas as vezes.
• Passo oito: decida o que vem depois. Se o agente puder criar ou editar páginas, deixe-o escrever apenas em uma área de rascunhos isolada e exija a aprovação de uma pessoa, como explicado em ler, preparar e enviar: três permissões diferentes de IA.
• Passo nove: passe a conexão por um checklist para aceitar uma integração de agente de IA antes que alguém dependa dela.

Verificação ilustrativa para o passo sete: um testador pergunta ao agente sobre uma política de licença que existe apenas como rascunho em um espaço privado. O resultado correto é uma recusa com a indicação do responsável pela política. O resultado errado é um resumo cheio de segurança. Mantenha esse teste no conjunto permanente, para que rode de novo a cada mudança na configuração.

Como é a manutenção contínua?

Uma conexão com a wiki não termina no lançamento. Páginas mudam, responsáveis saem, espaços são reorganizados e, cedo ou tarde, alguém move um rascunho para um espaço liberado. Planeje estas tarefas recorrentes:

• Revise a lista de espaços liberados em um calendário regular e confirme que cada um ainda tem responsável.
• Verifique se as permissões do agente correspondem à lista e remova qualquer acesso que ninguém consiga justificar.
• Rode de novo os testes de rascunho e de página vencida após qualquer mudança na estrutura da wiki.
• Leia uma amostra de respostas reais e compare com as páginas citadas.
• Acompanhe as perguntas que o agente recusou, porque elas mostram onde a wiki tem lacunas que valem ser preenchidas.

A Be Human cuida disso como parte do desenho e da operação da infraestrutura de um agente. Um primeiro projeto define o papel, os espaços que ele pode ler, os marcadores de aprovação e o critério de sucesso. A operação gerenciada cobre então monitoramento, avaliações recorrentes, manutenção das integrações e revisão de permissões, para que a conexão permaneça dentro dos limites enquanto a wiki continua mudando. Sua equipe mantém o controle sobre quais páginas são aprovadas e o que o agente pode fazer com elas.

Perguntas frequentes

Precisamos limpar a wiki inteira antes? Não. Limpe apenas os espaços que o agente vai ler e aprove um núcleo pequeno de páginas para começar. O resto da wiki pode ficar como está, porque tudo o que não foi aprovado simplesmente fica invisível para o agente.

O agente deve poder editar ou criar páginas? Não no início. Comece somente com leitura e, se escrever se tornar útil, limite a uma área separada de rascunhos, onde uma pessoa revisa e aprova cada mudança. Assim, texto escrito pelo agente não entra no conjunto aprovado sem uma decisão humana.

Podemos conectar com o login pessoal de um funcionário para ganhar tempo? É melhor não. Um login pessoal carrega todo o acesso daquela pessoa, quebra quando ela sai da empresa e impede distinguir o que foi feito pelo agente e o que foi feito por ela. Uma conta dedicada, com permissões estreitas e somente leitura, é mais fácil de auditar e de revogar.

O que o agente deve fazer quando nenhuma página aprovada responde à pergunta? Deve dizer que não tem uma fonte aprovada e oferecer o encaminhamento da pergunta ao responsável pelo tema mais próximo. Uma recusa clara é mais útil do que um palpite plausível, e as recusas registradas mostram quais páginas a equipe deve escrever ou aprovar em seguida.

Orientação editorial Be Human. Exemplos são ilustrativos, salvo atribuição explícita. Fontes oferecem contexto; a implementação depende do seu processo.