Mapa de dependências de agentes de IA: o que checar antes de falhar

Um mapa de dependências de agentes de IA é uma lista de uma página com tudo de que o agente precisa para funcionar: os modelos que ele chama, as contas e credenciais que usa, as APIs e ferramentas que acessa, os documentos que lê e as pessoas que aprovam ou mantêm o trabalho. Para cada item, você registra um responsável, como a falha se manifesta e se existe uma alternativa. Qualquer item sem alternativa e sem uma segunda pessoa que o entenda é um ponto único de falha, e esses são os primeiros a corrigir.

Principais pontos

• Liste as dependências em cinco grupos: modelos, contas e credenciais, APIs e ferramentas, documentos e dados, e pessoas.
• Para cada entrada, anote o responsável, o que para sem ela, como você perceberia o problema e qual é a alternativa.
• Ponto único de falha é tudo o que tem um só responsável, uma só cópia, um só login ou um só fornecedor, sem um caminho alternativo testado.
• Contas pessoais e conhecimento humano não documentado são as dependências ocultas mais comuns.
• Revise o mapa em datas fixas e sempre que mudarem a função, as ferramentas ou as permissões do agente.

Por que mapear as dependências antes de algo quebrar?

Um agente que funciona bem na primeira semana parece autossuficiente. Ele responde perguntas, redige respostas ou atualiza registros, e ninguém pergunta o que existe por baixo. Na prática, o agente é uma cadeia: um modelo produz o raciocínio, uma conta o deixa entrar em um sistema, uma API devolve dados, um documento informa a política vigente e uma pessoa decide quando o resultado está bom o bastante para ser usado. Se qualquer elo muda, o agente em geral não trava com uma mensagem clara. Ele piora em silêncio, ou simplesmente para, e a primeira pessoa a perceber muitas vezes é um cliente.

A maioria dos incidentes com agentes empresariais não são falhas dramáticas do modelo. São eventos comuns: um funcionário sai e o login dele é desativado, um fornecedor muda uma interface, uma pasta compartilhada é reorganizada, um token expira no fim de semana. O mapa transforma essas surpresas em riscos conhecidos, com resposta conhecida.

O mapa também ajuda a decidir. Quando alguém propõe conectar uma nova ferramenta ou uma nova fonte de dados, você enxerga o que isso acrescenta à cadeia. Se a empresa já mantém um diagrama de arquitetura de IA em uma página, o mapa de dependências é o complemento dele: o diagrama mostra as partes, e o mapa mostra quais partes você não pode perder.

O que entra no mapa?

Comece pelo que o agente de fato toca, não pelo que o fornecedor diz que ele usa. Acompanhe uma tarefa real, do pedido até o trabalho concluído, e anote tudo de que ele precisou no caminho. Depois, agrupe as entradas.

Modelos. Nomeie cada modelo que o agente chama, inclusive os usados em etapas menores, como classificação, resumo ou verificação. Anote quem hospeda cada um, qual versão ou apelido você usa e se o provedor pode aposentar ou alterar esse modelo. Se você chama um único modelo, escreva isso com clareza. É um fato que vale ver no papel.

Contas e credenciais. Liste cada login, chave de API, conta de serviço e token que o agente possui. Registre em nome de quem a conta está, onde o segredo é guardado, quando expira e o que ela pode fazer. A documentação do Google OAuth 2.0 é uma boa referência sobre acesso delegado e expiração de tokens, e o OWASP Authorization Cheat Sheet ajuda a definir o que cada conta deve poder fazer.

APIs e ferramentas. Liste cada sistema do qual o agente lê ou no qual escreve: o CRM, a ferramenta de chamados, a agenda, o serviço de e-mail, o banco de dados interno. Se as ferramentas são expostas por um padrão como o Model Context Protocol, trate cada servidor conectado como uma entrada própria. Anote quem mantém a conexão e o que acontece se o outro lado mudar.

Documentos e dados. Liste as políticas, regras de preço, fichas de produto, modelos, bases de conhecimento e arquivos de exemplo que o agente consulta. Para cada um, registre onde fica a cópia principal, quem pode editá-la e como o agente encontra a versão atual. Os textos da Anthropic sobre engenharia de contexto para agentes explicam por que o que o agente enxerga no momento da tarefa molda o comportamento dele, e é exatamente por isso que documentos desatualizados ou ausentes importam.

Pessoas. Liste quem aprova ações de risco, quem responde quando o agente escala um caso, quem mantém as conexões e quem decide sobre mudanças. Inclua a pessoa que sabe por que o agente foi configurado do jeito que foi. Este é o grupo mais esquecido no mapa e o que falha de forma mais silenciosa.

O que registrar para cada dependência?

O mapa só serve se todas as linhas responderem às mesmas perguntas. Mantenha poucos campos, para que as pessoas realmente os preencham.

• O que é, em palavras simples (por exemplo, a caixa de e-mail compartilhada de onde o agente envia).
• Para que o agente a usa, em uma frase.
• O responsável, como um papel nomeado e um substituto nomeado.
• Onde o acesso é controlado e como é renovado.
• Como a falha aparece vista de fora: erros, silêncio, respostas erradas ou lentidão.
• Como você perceberia e com que rapidez.
• A alternativa, se houver, e quando foi testada pela última vez.
• A data da última verificação da entrada.

Os dois últimos campos são os que mais trabalham. Uma alternativa que existe no papel, mas nunca foi exercitada, deve ser registrada como não testada, não como coberta.

Como reconhecer um ponto único de falha?

Um ponto único de falha nem sempre é um componente grande ou caro. É qualquer dependência em que um único evento tira do agente a capacidade de fazer seu trabalho e você não tem um caminho alternativo preparado. Faça estas perguntas a cada linha.

• Se isso sumisse hoje, o agente pararia ou produziria uma resposta errada?
• Só uma pessoa sabe como funciona ou como renovar?
• Está ligado a uma conta pessoal, a um dispositivo pessoal ou a um e-mail pessoal?
• Existe uma única cópia, e ela tem um backup do qual você já restaurou de verdade?
• Existe um único fornecedor, sem alternativa para a qual você possa migrar em prazo razoável?
• O agente depende de uma versão, apelido ou configuração que o fornecedor pode mudar sem consultar você?
• Você descobriria pelo seu próprio monitoramento ou por um cliente?

Uma linha com resposta sim em qualquer uma das cinco primeiras perguntas é candidata. Uma linha com sim em duas ou mais vai para o topo da lista. As duas últimas perguntas medem a gravidade da falha quando ela acontecer, então use-as para ordenar os candidatos.

Cuidado com dependências que parecem redundantes, mas não são. Dois modelos do mesmo provedor compartilham a mesma conta e a mesma indisponibilidade. Dois aprovadores da mesma equipe compartilham o mesmo calendário de férias. Duas cópias de um documento no mesmo drive compartilham as mesmas permissões. A redundância só conta quando a falha de um não derruba o outro.

Como montar o mapa em uma sessão de trabalho?

Você não precisa de uma ferramenta especial. Um documento ou planilha compartilhada com os campos acima basta. O objetivo é ter uma primeira versão honesta em poucas horas, não uma versão perfeita.

• Escolha um agente e uma tarefa real. Pegue a tarefa mais importante, como responder a um cliente, preparar uma proposta ou conciliar um registro.
• Acompanhe a tarefa do começo ao fim. Peça ao dono do processo que a percorra enquanto outra pessoa anota cada sistema, arquivo, login e pessoa envolvidos.
• Confira cada entrada com a realidade. Abra as configurações. Veja em qual conta cada conexão roda, em vez de confiar na memória.
• Preencha os campos de cada linha. Onde não souber a resposta, escreva desconhecido. Desconhecidos são achados.
• Marque os pontos únicos de falha com as perguntas acima e ordene-os pela rapidez com que você perceberia o problema e pelo dano que a falha causaria.
• Atribua um responsável e uma primeira ação a cada linha marcada. Mantenha as ações pequenas: nomear um substituto, mover um segredo para um cofre compartilhado, escrever os passos de renovação.
• Defina uma data de revisão e ligue o mapa ao processo de mudanças do agente, para que novas conexões ou alterações de permissão o atualizem.

Ligue o mapa à sua revisão de contas, chaves e permissões do agente. Os dois exercícios se sobrepõem: a revisão de permissões pergunta se cada acesso se justifica, e o mapa de dependências pergunta se cada acesso é sustentável.

Como isso fica na prática? (Um cenário ilustrativo)

Este cenário é ilustrativo, não um projeto real. Imagine uma distribuidora com um agente que responde a clientes sobre status de pedidos e devoluções. Ele lê dados do sistema de pedidos da empresa, responde a partir de uma caixa de suporte compartilhada e segue uma política de devoluções mantida em um documento.

A equipe acompanha uma tarefa: um cliente pergunta se uma devolução é aceita. O mapa mostra o seguinte.

• A conexão com o sistema de pedidos roda no login de um gerente de operações, a única pessoa que já a renovou.
• A política de devoluções existe como um documento no drive pessoal de uma coordenadora, e o agente lê uma cópia colada meses atrás.
• O agente chama um único modelo, por uma única conta de provedor, sem alternativa testada.
• As escalações vão para um líder de equipe, sem substituto nomeado.
• A caixa de e-mail compartilhada está em ordem: tem dois administradores e um processo de recuperação documentado.

Quatro linhas são pontos únicos de falha, e nenhuma é uma surpresa técnica. As correções são modestas: criar uma conta de serviço dedicada para o sistema de pedidos, com um passo de renovação documentado; mover a política para um local compartilhado, com responsável nomeado e um processo claro para atualizar o que o agente lê; nomear um substituto para as escalações; e decidir de antemão o que o agente faz se o modelo estiver indisponível (por exemplo, parar e passar o caso para uma pessoa, com uma mensagem curta de espera). A linha da caixa de e-mail fica como está. O valor do mapa foi separar o que exigia ação do que não exigia.

O que fazer com cada ponto único de falha?

Nem todo ponto único de falha merece a mesma resposta. Use este guia de decisão para escolher uma resposta proporcional.

• Se for uma pessoa, nomeie um substituto e escreva os passos que ele seguiria. A documentação reduz o risco de o líder interno de IA sair sem uma passagem de bastão.
• Se for uma conta pessoal, troque-a por uma conta de serviço dedicada, de propriedade da empresa, com as menores permissões que a tarefa exige.
• Se for um documento ou conjunto de dados, mantenha uma cópia principal com responsável nomeado e faça backup de um modo que você já tenha testado. Salve o que for necessário para restaurar o agente: configurações, instruções, documentos de referência e a lista de conexões.
• Se for um modelo ou provedor, decida se uma segunda opção compensa a complexidade adicional. Às vezes a resposta certa é um modo degradado definido. O texto sobre como escolher modelo de IA para empresa ajuda a avaliar quando um segundo modelo se paga, e o guia de como migrar agentes de IA para outro fornecedor mostra como manter suas opções abertas.
• Se for uma API externa, defina o que o agente faz quando a chamada falha: tentar de novo, enfileirar, parar ou passar para uma pessoa. Torne esse comportamento explícito, em vez de deixá-lo ao acaso.
• Se você não consegue corrigir agora, aceite o risco por escrito. Registre o responsável, o motivo e a data da próxima revisão.

Para cada correção, decida também como você perceberá uma falha. Uma alternativa que você nunca aciona vale pouco se a falha passa despercebida. Um alerta simples para credenciais vencidas ou chamadas que falharam costuma valer mais do que um segundo fornecedor.

Como a Be Human trata o mapeamento de dependências?

A Be Human trata o mapa de dependências como parte do primeiro trabalho com o cliente. Ao definir a função do agente, a equipe lista os modelos, contas, ferramentas, documentos e pessoas de que essa função precisa, registra os limites de aprovação e marca os pontos únicos de falha junto com o cliente. Durante a operação gerenciada, o mapa é revisado junto com o monitoramento, a revisão de permissões e a manutenção das integrações, e as mudanças em ferramentas ou acessos passam por um processo de mudanças combinado. A empresa mantém o controle das contas e decisões que lhe pertencem, e a verificação do dia a dia faz parte do trabalho gerenciado. Para entender como a responsabilidade é dividida, veja agência de automação com IA ou provedor gerenciado, e para a rotina recorrente, veja o que é AgentOps.

Perguntas frequentes

Com que frequência devo atualizar o mapa de dependências? Atualize sempre que o agente ganhar uma nova ferramenta, uma nova fonte de dados, uma nova permissão ou um novo responsável, e revise o mapa inteiro em uma periodicidade que sua equipe consiga cumprir. Uma revisão feita só depois de um incidente chega tarde demais para ser útil.

Quem deve ser o dono do mapa? Um dono do negócio ou líder de operações, porque as perguntas tratam de continuidade e responsabilidade, não apenas de tecnologia. A equipe técnica ou o seu provedor preenchem os detalhes, mas uma pessoa nomeada deve ser responsável por mantê-lo atualizado e agir sobre o que ele mostra.

Preciso de um mapa separado para cada agente? Sim, pelo menos no começo. Cada agente tem função, ferramentas e documentos próprios, então sua cadeia é diferente. Itens compartilhados, como uma caixa de e-mail comum ou uma conta de modelo, aparecerão em vários mapas, e essa sobreposição é útil em si: mostra onde uma única falha afetaria muitos agentes.

E se eu encontrar pontos únicos de falha demais para corrigir? Ordene-os pela rapidez com que você notaria a falha e pelo dano que ela causaria, e corrija os primeiros. Aceite o restante por escrito, com responsável e data de revisão. Uma lista curta e honesta que está sendo trabalhada vale mais do que um plano longo que ninguém segue.

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