Conecte sua própria API ao agente sem escrever código

Existe um teto claro no que um agente de IA consegue entregar: enquanto ele só conversa, o melhor que ele faz é “vou verificar e te retorno”. O salto acontece quando ele consulta o seu sistema e responde “seu pedido saiu hoje às 14h20”.

Esse salto tem nome no CollaborAI: Habilidades personalizadas. E não exige programar.

O que são

Uma habilidade é uma conexão entre o agente e um endpoint HTTPS seu. Consultar um CEP, buscar um pedido no ERP, verificar estoque, checar a segunda via de um boleto, abrir um chamado no seu sistema interno.

Você configura pelo construtor visual em Habilidades > Nova Habilidade, no menu lateral. A IA decide sozinha quando usar, com base no que você escreveu na descrição — e preenche os parâmetros a partir do que o cliente falou na conversa.

A configuração, campo a campo

Identidade

Nome e categoria, para você achar depois.

Descrição — o campo mais importante da tela inteira. É isto que o agente lê para decidir se aquela habilidade serve para a mensagem que acabou de chegar. Não é documentação para humano: é instrução para a IA.

Compare:

❌ Consulta pedidos.

✅ Consulta o status e a data de entrega de um pedido a partir do número do pedido. Use quando o cliente perguntar onde está a compra dele, se já saiu para entrega ou quando chega. Não use para trocas, devoluções ou cancelamentos.

A segunda versão diz quando usar e quando não usar. É a diferença entre um agente que consulta na hora certa e um que consulta em toda mensagem.

Conexão

URL do endpoint — precisa ser HTTPS.

Método HTTP — GET para consultar, POST para criar, PUT para atualizar, DELETE para remover.

Autenticação — três opções:

• Nenhuma, para APIs públicas.
• Bearer token, guardado criptografado. Depois de salvo, ele nunca mais é reexibido na interface — nem para você.
• OAuth via conector, quando a API já está ligada por um dos conectores da plataforma.

Parâmetros

Aqui você declara o que a habilidade precisa receber, com tipo. A IA preenche esses campos sozinha, extraindo da conversa.

Se o cliente escreve “oi, cadê meu pedido 48213?”, o agente entende que numero_pedido é 48213 e chama a API. Você não escreve nenhuma regra de extração — descreve o parâmetro e a IA faz o resto.

Vale nomear os parâmetros de forma óbvia (numero_pedido, não np) e descrever cada um. É pela descrição que a IA sabe o que colocar ali.

Corpo e tentativas

Corpo JSON fixo, para valores que não mudam entre chamadas — chave de canal, identificador da loja, versão da API.

Política de tentativas, para quando a sua API estiver instável. Vale configurar: uma falha momentânea não deveria virar “não consegui te ajudar” na frente do cliente.

Como ligar no agente

A habilidade nasce solta e é compartilhada entre todos os seus agentes. Para usá-la, ative no passo Habilidades do agente, junto das ferramentas dos conectores (Gmail, Google Agenda, Outlook, WhatsApp).

Cada habilidade mostra um contador de quantos agentes a utilizam, e há proteção contra exclusão de habilidade em uso — você não derruba o atendimento sem perceber.

Como testar antes de expor ao cliente

Converse com o agente pelo Chat do painel e observe o bloco Bastidores, que mostra as ferramentas acionadas em cada resposta. É ali que você vê se a habilidade foi chamada, com quais parâmetros e o que voltou.

Os três erros que aparecem nesse teste:

Habilidade nunca é chamada. A descrição está vaga demais. Reescreva dizendo explicitamente quando usar.

Habilidade é chamada sempre. A descrição está larga demais. Acrescente o “não use para…”.

Parâmetro errado. O nome ou a descrição do parâmetro está ambíguo. Renomeie.

Segurança

Três garantias que valem saber antes de conectar um sistema interno:

• Credenciais criptografadas e nunca reexibidas depois de salvas.
• HTTPS obrigatório — não há como configurar um endpoint em texto claro.
• Os tokens nunca são expostos ao modelo de IA. A IA decide que a habilidade deve ser chamada e com quais parâmetros; quem executa a chamada com a credencial é a plataforma.

Ainda assim, vale a higiene básica de integração: crie uma credencial dedicada para o agente, com o menor escopo possível. Se ele só precisa consultar status de pedido, ele não precisa de permissão de escrita.

Cinco habilidades que valem o esforço

1. Status de pedido. A pergunta mais frequente de qualquer e-commerce, e a mais fácil de automatizar por inteiro.

2. Consulta de disponibilidade. Estoque, vaga, horário. Transforma “vou verificar” em resposta imediata.

3. Busca de cliente no CRM. O agente reconhece quem está falando e personaliza o atendimento a partir do histórico real.

4. Abertura de chamado. O agente registra o problema no seu sistema e devolve o número do protocolo na mesma mensagem.

5. Consulta de CEP ou CNPJ. Simples, barata e resolve boa parte do preenchimento de cadastro sem digitação.

---

Comece pela pergunta que sua equipe mais responde manualmente e que tem resposta em algum sistema seu. Quase sempre é status de pedido ou disponibilidade — e quase sempre a API já existe.