Um agente de IA que não fala com os seus sistemas é um chat. Para valer como operação, ele precisa ler o pedido no ERP, gravar o contato no CRM e responder pelo WhatsApp oficial. E é exatamente aí que a maioria dos projetos descobre que o cronograma era otimista: não pelo agente, mas pelo acesso ao dado que ele precisa.
Este texto trata do que "sem projeto longo de integração" exige de verdade. A resposta curta: conector pronto é necessário e não é suficiente. Há quatro outras coisas, e são elas que separam semanas de trimestres.
Os quatro níveis de integração
Todo sistema que o agente precisa acessar cai em um destes quatro níveis, e o nível define o esforço antes de qualquer outra variável.
| Nível | O que existe | Esforço típico |
|---|---|---|
| Conector pronto | A plataforma já tem a integração construída e mantida. | Configuração: credencial e permissão. |
| API documentada | REST com documentação (Swagger/OpenAPI) ou equivalente. | Dias. A documentação vira ferramenta do agente. |
| Banco de dados acessível | Sem API, mas com acesso de leitura ao banco. | Semanas. Leitura é viável; escrita direta no banco é risco. |
| Legado sem API nem acesso | Sistema fechado, tela como única interface. | Projeto próprio. É aqui que cronogramas estouram. |
O primeiro trabalho de qualquer projeto é classificar cada sistema num desses níveis. Um projeto com três sistemas no nível 1 e um no nível 4 tem o cronograma do nível 4, e é melhor saber disso antes de prometer data.
O que "sem projeto longo" exige além do conector
1. Autenticação que sabe quem pediu
O caminho mais rápido é dar ao agente uma credencial de sistema com permissão ampla. Funciona na demonstração e reprova na revisão de segurança, porque o ERP passa a ver o diretor e o estagiário como o mesmo usuário. Integração que chega à produção propaga a identidade de quem pediu, ou restringe o escopo da credencial ao mínimo que aquele agente precisa. Isso precisa existir no conector, não ser construído depois.
2. Idempotência: o agente que tenta duas vezes não pode criar dois pedidos
Agente tenta de novo quando a chamada falha, quando o tempo estoura, quando o modelo decide repetir. Se a ação de "criar pedido" não for idempotente, a retentativa cria pedido duplicado, e a operação descobre isso no fechamento do mês. Toda ação de escrita precisa de chave de idempotência ou de verificação prévia. É o item mais esquecido e o mais caro de descobrir tarde.
3. Fronteira entre leitura e escrita
Dar ao agente acesso amplo de leitura e acesso estreito de escrita é o desenho que passa em revisão de segurança e que permite começar rápido. O agente consulta tudo que precisa para responder e só escreve o que foi explicitamente autorizado, uma operação por vez, com aprovação humana onde o valor ou o risco exigem. Integração que expõe tudo como escrita joga fora a única fronteira barata que existe.
4. Tratamento de erro que não vira silêncio
O ERP fica fora do ar às 3h. A API muda o formato de um campo. A credencial expira. Se o agente responde ao cliente como se nada tivesse acontecido, o erro vira informação errada entregue com confiança. Cada ferramenta precisa de comportamento definido para falha: repetir com limite, degradar para resposta parcial ou transferir para uma pessoa. E o erro precisa aparecer no painel, não só no log.
Conector pronto entrega o transporte. Os quatro itens acima entregam a confiança. Plataforma que tem a lista de conectores e não tem os quatro vai exigir que o seu time construa os quatro, sistema por sistema.
Padrões que encurtam o projeto
- Comece pela leitura. Um agente que consulta o ERP e responde já muda operação, e passa em revisão em dias. Escrita entra depois, uma operação por vez.
- Publique capacidade, não API. O agente não precisa das duzentas rotas do ERP. Precisa de "consultar pedido", "consultar estoque" e "abrir ocorrência". Ferramenta com nome de negócio e parâmetro tipado erra menos que ferramenta que espelha a API.
- Use a documentação existente. Se o sistema tem OpenAPI ou Swagger, essa documentação já descreve as ferramentas. Plataforma que lê esse formato transforma dias de integração em horas.
- MCP para o que vai ser consumido por mais de um agente. Publicar o sistema uma vez, num servidor MCP, e consumir em todos os agentes. Ver o que o MCP resolve e o que não resolve.
- Canal oficial desde o começo. WhatsApp não oficial parece mais rápido e derruba o projeto inteiro quando o número é bloqueado. A homologação da API oficial leva tempo; comece por ela.
O que perguntar antes de contratar
- Meus sistemas estão na lista de conectores? Quais, exatamente, e com quais operações?
- Para o sistema que tem API documentada mas não tem conector, quanto tempo leva? Quem faz?
- Como o agente se autentica no ERP: com credencial própria ou propagando o usuário?
- O que acontece se o agente tentar criar o mesmo registro duas vezes?
- Consigo dar leitura ampla e escrita restrita, por ferramenta?
- Quando o sistema integrado cai, o que o agente faz, e onde eu vejo isso?
- Para o legado sem API, qual é o caminho, e ele está no orçamento?
Como a Runflow trata integração
A plataforma traz mais de 150 conectores prontos para ERPs, CRMs, APIs e canais (HubSpot, Twilio, Slack e os seus sistemas legados entre eles), com MCP e ferramentas internas para o que não tem conector. Para sistema com API documentada, a descrição REST ou Swagger vira ferramenta do agente. No SDK TypeScript, cada ferramenta é definida com tipo e validação, o que é o que permite a fronteira entre leitura e escrita e a aprovação humana por operação.
O WhatsApp entra pelo Conversation Hub, na API oficial da Meta, e cada chamada de ferramenta fica registrada com parâmetro e retorno, reproduzível, que é onde a falha do sistema integrado aparece antes de virar resposta errada ao cliente. Para o sistema de nível 4, o legado sem API, a resposta honesta é que é projeto, e é o tipo de projeto que os engenheiros Forward Deployed fazem dentro da sua operação, com o seu time.
Perguntas frequentes
Como integrar um agente de IA ao ERP e ao CRM sem um projeto longo?
Classificando cada sistema em um de quatro níveis (conector pronto, API documentada, banco acessível, legado sem API) antes de prometer data, porque o cronograma é o do pior nível. E exigindo da plataforma quatro coisas além do conector: autenticação que propaga quem pediu ou restringe o escopo, idempotência nas ações de escrita, fronteira clara entre leitura ampla e escrita restrita, e tratamento de erro que não vira resposta errada ao cliente. Começar pela leitura e publicar capacidade de negócio em vez de espelhar a API encurta o projeto.
O que é idempotência e por que importa em agentes de IA?
É a propriedade de uma ação produzir o mesmo resultado se executada mais de uma vez. Agentes tentam de novo quando a chamada falha, quando o tempo estoura ou quando o modelo decide repetir. Se "criar pedido" não for idempotente, a retentativa cria pedido duplicado, e a operação descobre no fechamento do mês. Toda ação de escrita precisa de chave de idempotência ou verificação prévia.
Conector pronto é suficiente para integrar um agente de IA?
Não. O conector entrega o transporte. A confiança depende de autenticação que sabe quem pediu, idempotência na escrita, fronteira entre leitura e escrita, e tratamento de erro visível. Plataforma que tem a lista de conectores e não tem esses quatro vai exigir que o seu time os construa, sistema por sistema, e é aí que o projeto fica longo.
Como integrar um agente de IA com um sistema legado sem API?
Primeiro verificando se existe acesso de leitura ao banco de dados, que torna a consulta viável em semanas, evitando escrita direta no banco pelo risco. Se não há nem API nem acesso ao banco, é projeto próprio, e a resposta honesta de qualquer fornecedor é que ele precisa estar no orçamento e no cronograma desde o começo, não ser descoberto no meio.
Como usar a documentação Swagger ou OpenAPI para integrar um agente de IA?
A documentação já descreve cada operação com parâmetros e tipos, que é exatamente o que uma ferramenta de agente precisa. Plataforma que lê esse formato transforma a integração de dias em horas. O cuidado é não expor todas as rotas: o agente precisa de capacidades com nome de negócio (consultar pedido, abrir ocorrência), com parâmetro tipado, e não de um espelho da API inteira.