Ir para conteúdo
be-human.ai
← Voltar ao blog

Infraestrutura de IA personalizada

Conectar software antigo a agentes de IA: teste de lacunas de API

Teste passo a passo para achar sistemas antigos sem API, exportação ou escrita segura, e criar uma camada fina para agentes de IA sem reescrever.

Capa tipográfica do Be Human com o título: Conectar software antigo a agentes de IA: teste de lacunas de API
Ilustração conceitual criada com IA · Be Human

Para conectar software antigo a agentes de IA, primeiro teste cada sistema em três caminhos: uma forma de ler os registros atuais, uma forma de exportá-los em uma agenda e uma forma restrita de gravar alterações, com validação e registro de quem fez cada mudança. Onde faltar algum caminho, adicione uma camada fina de integração que exponha poucas operações com nome, aplique as mesmas permissões que um funcionário teria e registre cada chamada. O sistema antigo continua funcionando como hoje, e o agente nunca mexe no seu funcionamento interno.

Principais pontos

  • Teste todo sistema antigo quanto aos caminhos de leitura, exportação, escrita e auditoria antes de escolher qualquer tecnologia.
  • Liste as tarefas específicas que um agente deve executar e veja de quais sistemas cada uma depende.
  • Crie uma camada fina com um conjunto pequeno de operações nomeadas, validação de entradas e registros, e não uma cópia do sistema antigo.
  • Mantenha toda escrita atrás de uma verificação de permissão e de uma etapa de aprovação até que a camada tenha histórico de comportamento confiável.
  • Teste a conexão com respostas corretas conhecidas do sistema de registro antes de qualquer agente entrar em operação.

Por que sistemas antigos travam os agentes

A maior parte dos sistemas empresariais mais antigos foi feita para pessoas olhando uma tela. Eles podem ter um formulário web, um arquivo de lote noturno, uma planilha compartilhada ou uma ferramenta hospedada por um fornecedor sem interface pública. Um agente precisa de algo diferente: consultar o estado atual de um registro, executar uma ação delimitada e deixar evidência do que fez. Quando o sistema não oferece nada disso, as equipes costumam recorrer a atalhos, como colar dados em prompts ou automatizar cliques na interface. Esses atalhos funcionam até uma tela mudar, e então falham em silêncio, que é o pior resultado para um processo de negócio.

A primeira pergunta útil, portanto, não é qual ferramenta de IA adotar. É saber quais dos seus sistemas guardam os fatos de que o agente precisa e como um programa pode ler e alterar cada um deles. Um mapa de arquitetura em uma página ajuda nisso, porque mostra onde cada sistema está e quais alimentam outros. Para o método completo, veja Revisão da arquitetura de IA da empresa: ache a camada mais fraca.

O teste de lacunas de API, passo a passo

Execute este teste uma vez por sistema, usando as tarefas que você já listou. Guarde as respostas em um documento compartilhado que a operação e o responsável pelo sistema revisem juntos, para que divergências sobre o que o sistema faz apareçam cedo.

  • Passo 1: liste as tarefas que o agente executaria nesse sistema, escritas como verbos simples, como consultar o status de um pedido, rascunhar uma mudança de entrega ou atualizar o endereço de um cliente.
  • Passo 2: verifique o caminho de leitura. Procure um endpoint de API documentado, uma exportação agendada, um relatório ou uma visão de banco de dados que uma conta somente leitura possa consultar. Registre quão atualizados estão os dados.
  • Passo 3: verifique o caminho de escrita. Procure uma chamada de API, um arquivo de importação com validação ou um formulário suportado pelo fornecedor. Pergunte se repetir a mesma requisição cria um duplicado. A documentação da Stripe sobre requisições idempotentes mostra como um fornecedor pode definir esse comportamento de forma explícita, e muitas ferramentas antigas não oferecem nada comparável.
  • Passo 4: verifique o caminho de auditoria. Confirme que o sistema registra quem alterou o quê e quando. Se não registra, a camada precisa manter esse histórico por conta própria.
  • Passo 5: verifique a identidade. Confirme que é possível criar uma conta de serviço dedicada e limitá-la a ações específicas, separada do login de qualquer pessoa.
  • Passo 6: pontue cada tarefa. Verde significa que existem caminhos de leitura, escrita e auditoria. Amarelo significa que existe apenas leitura ou exportação. Vermelho significa que o único caminho de escrita é uma tela manual ou que o sistema não deixa registro confiável.

Uma tarefa está pronta para um agente quando seu caminho de leitura é verde e seu caminho de escrita é verde ou está protegido por uma etapa de aprovação. As tarefas vermelhas continuam com pessoas até alguém construir um caminho adequado. As tarefas amarelas costumam começar como apoio somente leitura, em que o agente responde perguntas e rascunha alterações que uma pessoa então envia.

Cenário ilustrativo: um pequeno distribuidor usa um sistema de pedidos sem API. Ele tem uma exportação noturna dos pedidos e um formulário web para mudanças de entrega. O agente responde perguntas de status a partir da exportação e informa o horário da exportação em cada resposta, para que a equipe saiba que os dados podem ter um dia de atraso. As mudanças de entrega são rascunhadas pelo agente e enviadas por um funcionário, porque o único caminho de escrita é o formulário. A equipe pontua a consulta de status como amarela e a mudança de entrega como vermelha por enquanto, e ambas as decisões são registradas com data de revisão.

Criar uma camada fina que não mexe no núcleo

Uma camada fina é um pequeno serviço que fica entre o agente e o sistema antigo. Ela expõe uma lista curta de operações nomeadas, como consulta de status de pedido ou rascunho de mudança de entrega, cada uma com finalidade clara, entradas tipadas e um conjunto fixo de campos retornados. Ela não expõe acesso direto ao banco, tabelas inteiras ou consultas de uso geral. As descrições das ferramentas também importam. As orientações de engenharia da Anthropic sobre como escrever ferramentas para agentes preferem ferramentas estreitas e bem descritas a ferramentas amplas, porque o agente escolhe qual chamar com base nessas descrições.

Escolha o padrão de leitura com intenção. Fatos transacionais, como saldo de estoque ou faturas em aberto, devem ser consultados ao vivo quando o sistema permitir, ou marcados claramente como desatualizados quando vierem de uma exportação. Políticas, manuais e documentos longos são outro caso, mais adequado para recuperação a partir de um conjunto indexado de documentos. Misturar os dois é um erro comum. A arquitetura de referência do Google Cloud para geração aumentada por recuperação e a comparação da AWS entre recuperação e ajuste fino explicam quando cada abordagem se encaixa.

Hábitos operacionais mantêm a camada substituível. Use tempos limite e limites de taxa, devolva erros em linguagem simples em vez de resultados vazios silenciosos e anexe um identificador de rastreio a cada chamada, para que uma única requisição possa ser acompanhada do agente até o sistema antigo e de volta. A introdução de observabilidade do OpenTelemetry descreve esses conceitos em termos gerais. Uma camada construída em torno das suas operações e documentada nos seus próprios termos pode ser alterada ou trocada depois, o que importa pelos motivos explicados em Dependência de fornecedor em agentes de IA: o que testar antes de renovar.

Proteger escritas, permissões e entradas

As verificações de permissão pertencem ao lado do servidor da camada, em cada chamada. Não dependa das instruções do agente para mantê-lo dentro dos limites. A orientação da OWASP sobre autorização é clara: as decisões de acesso devem ser aplicadas pelo sistema que recebe a requisição, verificadas em cada chamada e baseadas na identidade de quem a faz. A conta de serviço do agente deve ter apenas as operações listadas no seu papel, e nenhuma outra.

As entradas exigem o mesmo cuidado. E-mails, chamados e páginas web que o agente lê podem conter texto escrito para manipulá-lo. A folha de referência da OWASP sobre prevenção de injeção de prompt descreve as defesas gerais: limitar quais ferramentas estão disponíveis para cada tarefa, validar cada valor que o agente envia a uma operação de escrita e manter uma pessoa no processo para ações com efeito financeiro ou voltadas ao cliente. Um padrão prático é que toda escrita exija aprovação no começo, e os limites de aprovação só sejam ampliados depois que o histórico mostrar que a camada se comporta como esperado. A rotina de revisão está descrita em Revisão trimestral de permissões de agentes de IA: checklist prático.

Testar a conexão antes da produção

Antes de um agente usar a camada em trabalho real, monte um pequeno conjunto de testes com solicitações que sua equipe já tratou. Para cada solicitação, registre a resposta correta e o sistema de registro onde ela está. Depois, verifique se o agente recupera o registro certo, recusa pedidos fora do seu escopo, mostra o aviso de dados desatualizados quando deveria e evita escritas duplicadas quando uma solicitação é repetida. A verificação de repetição é fácil de esquecer e cara de deixar passar.

As orientações da Anthropic sobre avaliações de agentes e o guia de avaliações da OpenAI descrevem como estruturar esses testes, com avaliadores que checam resultados em vez de redação. Mantenha o conjunto de testes sob controle de versão e execute-o de novo após cada mudança na camada ou no sistema do fornecedor. Defina regras de parada antes: se um teste de escrita falhar, as escritas são desligadas enquanto as leituras continuam, até a causa ser encontrada.

Operar a camada depois do lançamento

Uma conexão só funciona enquanto os sistemas dos dois lados permanecem estáveis, e eles costumam mudar. Fornecedores atualizam formulários, renomeiam campos ou mudam exportações para outra agenda. O monitoramento deve cobrir taxas de erro, latência, datas dos dados e resultados vazios inesperados, e não apenas quedas. Configure um alerta quando uma exportação estiver mais antiga do que a equipe espera, porque uma falha silenciosa é mais difícil de perceber do que uma falha barulhenta.

Toda trimestre, revise quais contas de serviço existem, quais operações elas podem chamar e quais aprovações foram concedidas. O roteiro em Quem supervisiona um agente de IA na empresa: revisão diária ajuda a definir quem faz essa rotina no dia a dia. Mantenha um interruptor de emergência que desative as operações de escrita separadamente das de leitura, para que um incidente possa ser contido sem parar o serviço inteiro.

Por onde começar com um modelo gerenciado

A Be Human projeta, implanta e opera esse tipo de camada para empresas como parte da operação gerenciada. Um primeiro projeto define um papel útil, a memória e as ferramentas que esse papel precisa, os limites de aprovação e um critério de sucesso que o negócio consiga observar. A Be Human conduz o teste de lacunas com a sua equipe, constrói o adaptador com operações nomeadas e registros sob o seu controle, mantém as permissões revisáveis e cuida depois do monitoramento, da manutenção das integrações e das mudanças controladas. O trabalho é remoto e disponível em inglês e português.

Se ainda não está claro quais dos seus sistemas devem ser conectados primeiro, o diagnóstico gratuito de IA da Be Human pode ajudar a encontrar a primeira tarefa que vale entregar a um agente.

Perguntas frequentes

Um agente consegue trabalhar com um sistema que não tem nenhuma API? Sim, mas de forma limitada. Comece com leituras a partir de uma exportação ou de uma visão de banco somente leitura, e trate qualquer escrita como um rascunho que uma pessoa envia até existir um caminho de escrita confiável. Automatizar a interface do usuário é possível, mas frágil, então deve ser a última opção.

Precisamos reescrever nosso software antigo antes de conectá-lo? Não. A camada fina descrita aqui fica ao lado do sistema e usa o acesso que ele já oferece. Uma reescrita pode valer a pena no futuro por motivos próprios, mas não é pré-requisito para um primeiro agente útil.

Como saber que a camada é segura o bastante para permitir escritas? A segurança aqui se apoia em registro, não em afirmação. As escritas devem passar no conjunto de testes, ser protegidas por verificações de permissão do lado do servidor e aprovações, e gerar registros que mostrem qual identidade fez cada mudança. Amplie os limites de aprovação com calma e só quando o histórico sustentar isso.

Quem deve ser responsável pela camada depois de construída? O negócio deve ser dono das suas definições: as operações, as permissões e as regras de aprovação. A operação ou o responsável pelo sistema deve revisar as mudanças, e quem mantém a camada deve ser nomeado por escrito, para que mudanças do fornecedor e incidentes tenham um caminho claro até a solução.

Seu próximo passo

Descubra primeiro onde um agente de IA cabe na sua empresa.

Faça o diagnóstico gratuito de IA da Be Human. Algumas perguntas sobre o seu trabalho mostram qual tarefa entregar primeiro a um agente, o que ele precisa saber e onde uma pessoa aprova.

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

Menos tarefas. Mais espaço para você.

Traga o trabalho para o qual falta tempo.

Agende uma conversa e teste 7 dias grátis um agente de IA personalizado ↗Ou faça o diagnóstico gratuito de IA →