Onde guardar senhas e chaves de API de agentes de IA?

As senhas e chaves de API de um agente de IA devem ficar em um gerenciador de segredos dedicado, fora do prompt, da memória do agente, da base de conhecimento e de qualquer repositório de código. A camada de ferramentas do agente busca a credencial apenas no momento da chamada, e o modelo nunca a lê. Cada credencial deve ter o menor acesso que a função exige, um responsável com nome e uma rotação em calendário que você consiga verificar.

Principais pontos

• Guarde as credenciais em um gerenciador de segredos com criptografia e registro de acesso, nunca em prompts, memória, conversas, planilhas ou documentos compartilhados.
• Mantenha o segredo na camada de ferramentas, não no contexto do modelo. O modelo pede uma ação; a ferramenta anexa a credencial.
• Prefira credenciais estreitas e revogáveis: tokens delegados ou contas de serviço com escopo limitado antes de chaves-mestras amplas.
• Faça a rotação em calendário e após qualquer suspeita de exposição, com janela de sobreposição e um teste depois de cada troca.
• Peça ao fornecedor que mostre onde os segredos ficam, quem pode lê-los, como são rotacionados e o que acontece quando um vaza.

Onde as credenciais de um agente devem ficar, na prática?

A resposta curta é um gerenciador de segredos: um sistema feito para guardar valores sensíveis, criptografá-los, controlar quem e o que pode lê-los e registrar cada leitura. As grandes plataformas de nuvem oferecem um, e também existem opções independentes. O produto específico importa menos que as propriedades: criptografia em repouso, regras de acesso por identidade, trilha de auditoria e um jeito de trocar um valor sem reimplantar o agente.

Vale listar os lugares onde credenciais não devem ficar, porque é ali que os vazamentos costumam começar:

• O prompt de sistema ou qualquer arquivo de instruções que o modelo leia.
• A memória de longo prazo ou a base de conhecimento do agente.
• Conversas, chamados de suporte e e-mails, inclusive mensagens enviadas ao próprio agente.
• Planilhas, documentos compartilhados e quadros de projeto.
• Repositórios de código e arquivos de configuração versionados junto com o código.
• Notebooks pessoais, gerenciadores de senha do navegador e anotações de quem montou a integração.

A memória merece atenção especial. Um agente que lembra das coisas é útil, mas tudo o que fica ali pode ser recuperado, resumido e repetido depois. Para pensar no que pertence à memória e no que não pertence, veja como estruturar a memória de um agente de IA. Credenciais não pertencem a nenhum dos dois lugares: nem à memória, nem ao histórico de conversa.

Por que o modelo nunca deve ver o segredo?

Um modelo de linguagem trata tudo o que está no contexto como texto que ele pode repetir. Se uma chave está no prompt, um e-mail manipulado, uma página da web ou um documento lido pelo agente pode tentar convencer o modelo a exibi-la. É uma classe de risco reconhecida: a orientação da OWASP sobre injeção de prompt e a lista de riscos para aplicações com LLM descrevem ataques em que conteúdo não confiável leva o modelo a revelar dados ou executar ações indevidas.

O desenho mais seguro separa pensar de executar. O modelo decide que quer criar um rascunho de resposta ou consultar um pedido. Ele emite uma solicitação estruturada. Uma camada de ferramentas, que é software comum e sem julgamento que se possa convencer, confere se a solicitação é permitida, busca a credencial no cofre, faz a chamada e devolve apenas o resultado. O segredo nunca entra na conversa, então não pode ser repetido, registrado em uma transcrição nem guardado na memória.

Isso também muda o que é uma boa ferramenta. Uma ferramenta que aceita do modelo um campo livre chamado "api_key" ou "senha" é sinal de mau projeto. A credencial deve ser vinculada à ferramenta por configuração, e não fornecida pelo modelo em tempo de execução. O artigo sobre contratos de ferramentas de IA explica como definir entradas e saídas para que valores sensíveis nunca façam parte da interface.

O mesmo vale para os protocolos que conectam agentes a ferramentas. Se você usa um padrão como o MCP, o servidor que expõe a ferramenta é o lugar certo para as credenciais, e não as instruções do agente. O que é MCP e por que importa para agentes de negócio? traz o contexto.

Que tipo de credencial o agente deve ter?

Nem toda credencial é igual. Antes de decidir onde guardar uma, decida qual tipo o agente deve ter. Um guia de decisão:

• Se o agente age em nome de uma pessoa específica, como ler a agenda dela, use um token OAuth delegado com escopos limitados. Ele pode ser revogado pelo usuário ou por um administrador sem afetar mais ninguém. A documentação de OAuth 2.0 do Google descreve como funcionam escopos e consentimento.
• Se o agente executa uma tarefa de sistema que pertence à empresa e não a uma pessoa, use uma conta de serviço com identidade própria e somente as permissões que essa tarefa exige. Assim, quando alguém sai da empresa, a integração não vai junto.
• Se o fornecedor só oferece uma chave de API, crie uma chave exclusiva para o agente, restrita à menor permissão que o fornecedor permitir, e identifique-a com o nome e a finalidade do agente.
• Se a única opção é o usuário e a senha de uma pessoa, trate como último recurso. Logins compartilhados escondem quem fez o quê e raramente aceitam permissões limitadas ou revogação limpa.
• Nunca reutilize uma chave que uma pessoa, outro sistema ou outro agente já usa. Uma credencial por agente em cada sistema simplifica a revogação e a auditoria.

Os prós e contras das duas primeiras opções estão em conta de serviço ou OAuth para agentes de IA. Seja qual for a escolha, o escopo deve seguir o princípio de menor privilégio para agentes de IA: comece com o menor acesso e acrescente só quando uma tarefa real exigir. Também vale separar as permissões de leitura, rascunho e envio, como descrito em ler, preparar e enviar: três permissões diferentes de IA, porque o vazamento de uma chave somente de leitura é um problema muito menor que o de uma chave que pode enviar mensagens ou pagar.

Como a rotação deve funcionar?

Rotacionar é substituir uma credencial por uma nova e aposentar a antiga. Isso limita por quanto tempo um valor vazado continua útil e prova que a sua equipe realmente sabe trocá-lo. Uma chave que ninguém ousou rotacionar é uma chave que ninguém entende.

Um plano prático:

• Defina um responsável para cada credencial, uma pessoa ou um cargo, e não um e-mail de equipe que ninguém lê.
• Estabeleça um calendário de rotação conforme o risco do sistema. Credenciais que movimentam dinheiro, enviam mensagens ou acessam dados de clientes pedem um intervalo menor que o de uma chave somente de leitura para relatórios.
• Crie a nova credencial no cofre enquanto a antiga ainda funciona.
• Atualize a camada de ferramentas para usar o novo valor, de preferência por referência à entrada do cofre, para que nenhuma alteração de código seja necessária.
• Execute um teste pequeno que exercite a ação real, como criar um rascunho ou ler um registro de teste, e confirme que funciona.
• Revogue a credencial antiga só depois que o teste passar e uma janela curta de sobreposição terminar.
• Registre a mudança: quem rotacionou, quando e o que foi testado.

Algumas credenciais expiram sozinhas, principalmente tokens OAuth. Isso é uma vantagem, mas o agente precisa lidar bem com a expiração, em vez de falhar em silêncio ou pedir que alguém cole um token novo na conversa. O artigo sobre o que um agente deve fazer quando uma conexão expira descreve um caminho de recuperação que mantém os segredos fora das conversas.

A rotação também deve ser disparada por eventos. Rotacione de imediato quando alguém com acesso sair, quando o contrato de um prestador terminar, quando um fornecedor comunicar um incidente ou quando você encontrar o valor em qualquer lugar onde ele não deveria estar.

O que conta como exposição e o que fazer a respeito?

Exposição é algo mais amplo que um vazamento público. Conta qualquer lugar em que uma credencial possa ser lida por alguém ou algo que não precisa dela. Caminhos comuns incluem:

• Uma pessoa colando uma chave na conversa com o agente para "fazer funcionar".
• Mensagens de erro e logs de depuração que imprimem cabeçalhos de requisição.
• Saídas de ferramentas que devolvem a configuração usada.
• Transcrições exportadas, capturas de tela e chamados de suporte que incluem qualquer um dos itens acima.
• Documentos de configuração escritos por quem montou a integração e depois compartilhados amplamente.
• Backups e ambientes de teste que copiam segredos de produção.

Uma boa configuração reduz esses caminhos por desenho: os logs ocultam padrões conhecidos de segredos, as respostas das ferramentas nunca incluem cabeçalhos de requisição, e o agente é instruído a recusar e sinalizar qualquer mensagem que contenha algo parecido com uma credencial.

Quando há suspeita de exposição, a ordem das ações importa:

• Revogue ou rotacione a credencial primeiro. A investigação pode esperar alguns minutos; uma chave ativa não pode.
• Verifique o registro de acesso do cofre e do sistema de destino em busca de uso que você não reconheça.
• Remova o valor do lugar onde vazou, inclusive as cópias em transcrições e na memória.
• Avalie se o escopo da credencial era mais amplo que o necessário e restrinja a substituta.
• Registre o que aconteceu e o que mudou, para que a próxima revisão tenha evidências.

Um cenário ilustrativo: uma empresa tem um agente que redige e-mails para fornecedores. Durante a configuração, um integrante da equipe cola na conversa do agente um token de acesso à caixa de e-mail, porque a primeira tentativa de conexão falhou. Depois, a conversa é exportada para um treinamento. Nada de ruim acontece, mas o token agora está em uma transcrição, em uma exportação e no contexto recente do agente. A resposta correta é revogar o token, reconectar pelo fluxo de autorização aprovado, apagar as cópias da transcrição e criar uma regra para que o agente sinalize qualquer credencial colada. O incidente custa uma hora em vez de virar uma história maior. Para a parte de e-mail dessa configuração, veja como conectar um agente de IA ao e-mail sem colocar sua caixa em risco.

Como a Be Human trata as credenciais dos agentes?

A Be Human trata as credenciais como parte do contexto operacional do agente, e não como um detalhe deixado para o fim. Na primeira etapa do trabalho, cada função é definida com as ferramentas de que precisa e as permissões que cada ferramenta exige, e cada credencial é criada somente para essa finalidade. Os segredos ficam em um repositório gerenciado e são anexados pela camada de ferramentas, de modo que o modelo não os vê. A operação gerenciada inclui revisão de permissões, rotação, monitoramento de acessos e uma resposta definida para quando uma conexão falha ou um valor pode ter sido exposto, com os aprovadores do cliente decidindo o que o agente pode fazer.

O que pedir ao fornecedor que confirme?

Você não precisa inspecionar o cofre pessoalmente. Precisa de respostas claras, de preferência por escrito e demonstradas. Uma lista para levar à conversa com o fornecedor:

• Onde as nossas credenciais ficam armazenadas e qual produto ou serviço as guarda?
• O modelo consegue ler alguma credencial, diretamente ou por meio da resposta de uma ferramenta?
• Quem na sua empresa e quem na nossa pode recuperar o valor de uma credencial? Cada recuperação fica registrada?
• Cada credencial é exclusiva do nosso agente e do nosso sistema, ou é compartilhada entre clientes ou ferramentas?
• Qual é o escopo de cada credencial e por que ele é o menor escopo viável?
• Qual é o calendário de rotação, quem é o responsável e como a rotação é testada?
• O que acontece com as credenciais quando alguém de qualquer um dos lados deixa o projeto?
• Como os logs e as transcrições evitam capturar segredos?
• Qual é o procedimento se uma credencial for exposta e com que rapidez o acesso pode ser revogado?
• No fim do contrato, como as credenciais são revogadas e os segredos apagados?

Use as mesmas perguntas ao comparar opções. O checklist para aceitar uma integração de agente de IA é um bom lugar para registrar as respostas e as evidências por trás delas, e o checklist para avaliar uma demonstração de agente de IA ajuda quando mais de um fornecedor está na disputa.

Se uma resposta for vaga, como "nós mantemos tudo seguro", peça detalhes. Um fornecedor competente descreve o mecanismo em poucas frases e mostra uma linha de log que prova que ele funciona. Ações sensíveis merecem escrutínio extra: antes de entregar ao agente qualquer credencial que possa movimentar dinheiro, leia agente de IA pode fazer pagamentos? Limites seguros para definir.

Perguntas frequentes

É aceitável guardar uma chave de API em uma variável de ambiente? É melhor que escrevê-la no código, e muitas configurações pequenas começam assim. Mas variáveis de ambiente vazam com facilidade por logs, relatórios de falha e configurações copiadas, e tornam a rotação trabalhosa. Para qualquer coisa que toque dados de clientes, mensagens ou dinheiro, um gerenciador de segredos com registro de acesso é o lugar mais seguro.

Posso dar ao agente o meu próprio login para que ele faça o que eu faço? Pode, mas raramente é uma boa ideia. O agente herdaria todas as permissões que você tem, as ações apareceriam como suas nas trilhas de auditoria, e revogar o acesso significaria trocar a sua própria senha. Um token delegado com escopos limitados, ou uma conta de serviço dedicada, dá ao agente só o que a função exige e pode ser removido sem atrapalhar você.

Com que frequência as credenciais do agente devem ser rotacionadas? Não existe um intervalo único e correto. Defina pelo risco: credenciais que enviam, gravam ou pagam devem ser rotacionadas com mais frequência que as somente de leitura, e toda credencial deve ser trocada de imediato após mudanças na equipe ou suspeita de exposição. O mais importante é que o calendário exista, tenha um responsável e seja testado.

O que fazer se alguém colar uma senha na conversa do agente? Trate como exposta. Revogue ou troque a credencial, apague a mensagem das transcrições e de qualquer memória, e verifique nos registros de acesso se há uso desconhecido. Depois configure o agente para recusar e sinalizar mensagens que pareçam credenciais, e ofereça às pessoas um jeito aprovado de conectar sistemas sem digitar segredos em uma conversa.

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