Credenciais HTTP e MCP: acesso seguro para agentes de voz

Diferencie as chaves

Confirme qual sistema fornece a chave e qual conexão vai utilizá-la. Uma chave de acesso do CRM não serve automaticamente para o sistema de reservas. Peça ao responsável pelo serviço uma conta com permissão apenas para as tarefas do agente.

Os serviços podem exigir formas diferentes de apresentar a chave. Use o tipo de autenticação indicado pelo responsável pela integração e preencha os campos correspondentes no Tigy. Uma chave correta no campo errado pode impedir a conexão.

Associe a credencial à ferramenta

Abra a ferramenta HTTP ou MCP, selecione uma credencial do workspace ou crie a necessária. Preencha o tipo e os campos apresentados, associe a credencial e salve. Faça uma consulta de teste.

Mantenha o segredo fora das instruções do agente, exemplos e conteúdos públicos. Para validar a integração, prefira uma conta com acesso apenas aos dados e operações necessários.

Investigue o tipo de falha

Uma resposta 401 pode indicar chave ausente, expirada ou formato incorreto. Uma resposta 403 pode indicar que a conta foi reconhecida, mas não tem acesso à operação. Confira a documentação e os logs do serviço para interpretar o caso.

Uma conexão que não chega ao destino exige investigar URL, disponibilidade e rede. Trocar a chave não corrige um servidor inacessível.

Inclua o acesso na rotina de manutenção

Quando um segredo mudar no serviço externo, atualize a credencial associada e repita a consulta antes de publicar alterações. Registre o responsável pela integração e o procedimento de teste.

O prompt pode limitar quais ações o agente tenta executar. A autorização efetiva precisa existir no serviço externo, inclusive quando uma requisição usa parâmetros inesperados.

Mantenha segredos fora da conversa e da revisão pública

Use os mecanismos de credenciais e cabeçalhos apropriados à ferramenta. Não coloque tokens nas instruções, em documentos consultáveis ou em exemplos que o agente pode repetir. Segredos também podem aparecer em URLs e mensagens de erro; revise o que seu adaptador devolve.

Ao compartilhar uma falha, preserve status, identificador e descrição reduzida sem copiar cabeçalhos sensíveis. A equipe precisa de evidência suficiente para diagnosticar, mas não de uma credencial espalhada por tickets e planilhas.

Teste com uma credencial expirada e uma sem permissão. A fala deve indicar que a consulta não foi concluída e seguir o caminho operacional, sem ler detalhes internos. Não tente resolver uma falha de autorização concedendo acesso amplo antes de descobrir qual ação foi recusada e qual permissão ela realmente exige.

Prepare a troca sem interromper o atendimento

Registre onde a credencial é usada, como validar a substituição e como retirar a anterior. Uma lista de ferramentas dependentes evita que a rotação conserte um agente e quebre outro. Confira o ambiente para não trocar a chave de produção por uma de teste.

Depois da atualização, execute uma consulta autorizada e uma operação que deve continuar recusada. O segundo teste verifica que o acesso não se tornou mais amplo. Para operações de escrita, use uma janela e dados controlados.

Mantenha um responsável e um procedimento para revogação urgente. Se houver suspeita de exposição, a correção inclui trocar a credencial no sistema responsável e revisar seus usos. Apagar a frase do prompt não invalida um segredo que já foi divulgado.

Identifique quem autentica quem

Uma credencial de ferramenta permite que o agente acesse um sistema externo. Use o segredo emitido pelo serviço de destino e mantenha-o fora das instruções. Antes de preencher o formulário, desenhe o pedido: quem envia, quem recebe, qual recurso será acessado e qual serviço emitiu a credencial.

Considere uma consulta fictícia a um sistema de pedidos. A ferramenta pede informações ao sistema da loja, que exige uma chave de acesso própria. A configuração deve usar a chave aceita pela loja e o formato indicado pelo responsável pela integração. O cliente que telefona não precisa fornecer essa chave, e ela deve ficar fora das instruções do agente.

Faça um inventário simples com serviço, finalidade, responsável e ambiente. Não copie o segredo para esse inventário. A informação útil para manutenção é saber qual conta autoriza a consulta, quais operações estão permitidas e quem pode rotacionar o acesso. Sem essa identificação, uma falha pode gerar mudanças em uma chave sem relação com a ferramenta.

Separe também contexto do cliente e identidade da integração. A credencial autentica a chamada entre sistemas; o identificador coletado na conversa seleciona um registro. Nenhum desses elementos elimina a necessidade de verificar autorização para aquele registro. O servidor externo deve conferir essa relação antes de devolver dados.

Siga o formato do serviço, não uma convenção presumida

No Tigy, selecione ou crie a credencial na configuração da ferramenta. O formulário muda conforme o tipo de acesso exigido pelo serviço. Peça ao responsável pela integração o tipo correto e os valores necessários. Não troque uma opção por outra só porque todas usam uma chave: cada serviço espera receber o acesso de uma forma específica.

Confira o nome do cabeçalho e a estrutura do valor. Authorization e X-API-Key podem representar contratos diferentes. Um segredo válido enviado no local errado continua sendo rejeitado. Use a documentação do próprio serviço como referência para configurar; não tente compensar a diferença pedindo ao modelo que coloque o segredo em parâmetros da conversa.

Depois de associar a credencial e salvar, faça uma consulta de ensaio conhecida. Verifique o resultado no sistema externo quando possível. Uma configuração aceita pela interface não prova que o destino reconheceu a autenticação. A primeira verificação deve ter um recurso e uma operação que a conta certamente pode acessar, permitindo separar formato e permissão.

Evite dados reais durante esse ensaio. Prepare um registro fictício no ambiente autorizado para teste. Se a ferramenta produz efeitos, use uma conta de ensaio e um destino que não envie comunicação a clientes. O objetivo é validar acesso e contrato, sem transformar investigação técnica em operação comercial.

Escolha permissões proporcionais às tarefas

A credencial deve corresponder ao que o agente precisa executar. Se o piloto só consulta status, uma conta capaz de apagar registros não acrescenta valor à tarefa. Peça ao responsável pelo sistema externo um acesso limitado às operações e dados necessários. O filtro de ferramentas e o prompt ajudam a orientar a conversa, mas a permissão precisa existir no serviço que executa.

Distinga leitura de escrita e ambientes de teste de produção. Uma consulta de ensaio não deve alcançar registros reais por engano. Uma ferramenta de criação não deve enviar mensagens ou cobranças enquanto a equipe está apenas avaliando parâmetros. Identifique destino e credencial juntos, pois trocar somente a URL ou somente o segredo pode misturar ambientes.

Teste também a recusa. Solicite um recurso fora do acesso autorizado e confira se o servidor bloqueia. A conversa deve explicar o limite sem divulgar dados do recurso recusado. Um resultado negativo bem tratado mostra que o recorte de acesso funciona, não que é preciso aumentar a permissão imediatamente.

Revise o acesso quando o escopo muda. Acrescentar cancelamento a um agente que antes apenas consultava pedidos exige um contrato e uma autorização diferentes. Essa decisão precisa ser deliberada, com critérios de confirmação e prevenção de duplicidade. Não amplie uma conta inteira para evitar planejar a nova capacidade.

Diferencie autenticação, autorização e conexão

A documentação do Tigy oferece uma orientação prática: um 401 pode indicar credencial ausente, expirada ou formato incorreto; um 403 pode indicar conta reconhecida sem acesso ao recurso ou à operação. Use esses códigos como pistas e confirme o contrato do serviço externo. Não trate qualquer rejeição como motivo para pedir uma chave mais poderosa.

Uma falha de conexão é outra investigação. URL incorreta, destino indisponível ou acesso de rede podem impedir a chamada antes de qualquer autenticação. Rotacionar um segredo não torna um servidor alcançável. Verifique a etapa que falhou para evitar alterações desnecessárias e perda de uma configuração que antes funcionava.

Quando várias ferramentas falham simultaneamente, procure dependências comuns. Elas podem compartilhar serviço, credencial ou mudança de permissão. Quando apenas uma operação falha, compare método, recurso e contrato. Essa divisão ajuda a localizar a causa sem reescrever todas as instruções do agente.

Na conversa, explique apenas o necessário ao cliente. Ele não precisa ouvir detalhes de cabeçalho ou segredo. Precisa saber que a consulta não foi concluída e qual alternativa está disponível. Não invente um resultado para esconder a falha e não faça a pessoa repetir dados quando a causa está no acesso entre sistemas.

Rotacione com uma verificação de continuidade

Quando o serviço externo muda um segredo, atualize a credencial associada e repita uma consulta antes de publicar alterações dependentes. Planeje a mudança com o responsável e identifique ferramentas que usam o acesso. A rotação está concluída quando as tarefas necessárias continuam funcionando e o acesso antigo foi tratado conforme o processo do serviço.

Não copie o segredo para o prompt como solução temporária. Esse atalho cria exposição e outra cópia para manter. Use o armazenamento apropriado e verifique a associação ao workspace e à ferramenta. Se o teste usa outra credencial, ele pode passar sem comprovar a configuração que atenderá clientes.

Mantenha o caso de ensaio para futuras rotações. Uma consulta pequena com resultado conhecido permite verificar a continuidade sem depender de uma chamada real. Para escrita, use um resultado controlado e confirme que nenhum efeito duplicado foi criado.