Por que conectar seu agente de IA ao seu app com uma API

O que é uma API de agente de IA?

Uma API de agente de IA permite que seu próprio software envie uma mensagem a um agente que você já criou e receba a resposta dele. O agente mantém as instruções, o conhecimento, o modelo, as ferramentas e as regras de segurança. Seu app só envia a pergunta.

Essa é a diferença em relação a uma API de modelo pura. Uma API de modelo entrega geração de texto e deixa todo o resto com você: prompts, busca em documentos, memória, limites de requisições, cobrança. A API REST da IMFA entrega um agente gerenciado que já tem tudo isso, protegido por uma única chave vinculada ao agente.

Você cria o agente com o criador de chatbots com IA. A API é mais um lugar onde ele pode responder, ao lado do seu site, WhatsApp, Instagram, Facebook, Telegram, Discord e da linha de voz.

Quando conectar seu agente por uma API?

Use a API quando a conversa acontece dentro de algo que é seu:

• Seu app ou portal do cliente precisa de um assistente de ajuda que conheça suas políticas, sem um segundo chatbot para manter.
• Seu backend deve responder a perguntas vindas de outro sistema, como páginas de pedidos, uma ferramenta de agendamento ou um painel interno.
• Você quer os leads no seu CRM. A API devolve os leads que o agente captou em todos os canais, para você sincronizá-los periodicamente.
• Você precisa do histórico das conversas para relatórios ou revisão de qualidade.

Se você só precisa de uma bolha de chat em um site, a incorporação com uma linha de código é mais simples. A API é para quando a interface é o seu produto, não o widget.

Como funciona a API de agentes da IMFA

A URL base é https://site.imfa.app/v1. Toda chamada precisa da chave do agente e deve partir de código de servidor confiável, nunca de um navegador ou de um app mobile.

1. Publique o agente. Defina as instruções, o conhecimento, o modelo e as ferramentas na IMFA, teste perguntas reais e publique. A API usa a versão publicada.
2. Gere a chave. Abra a visualização de API do agente ou a tela de Chaves de API e gere uma chave. Ela aparece uma única vez e é armazenada apenas como hash. Guarde-a em uma variável de ambiente do servidor, como IMFA_API_KEY.
3. Envie uma requisição de chat. POST /v1/agents/{slug}/chat com Authorization: Bearer <key>, uma Idempotency-Key única (de 8 a 128 caracteres) e um corpo JSON com message e um sessionId opcional. A resposta volta com um sessionId e usage.credits.
4. Continue a conversa. Não envie sessionId na primeira mensagem; depois, envie de volta o que você recebeu. O agente lembra o contexto.
5. Veja o que aconteceu. GET /v1/agents/{slug}/sessions lista as conversas, GET /v1/agents/{slug}/sessions/{sessionId}/messages lê uma delas e GET /v1/agents/{slug}/leads devolve os leads captados. As listas trazem 20 itens por padrão, até 100, com um cursor. GET /v1/agents confirma qual agente a chave atende.

Os limites são explícitos: são usados os primeiros 4.000 caracteres de uma mensagem, o corpo da requisição tem no máximo 64.000 bytes e os erros são tipados (validação, autenticação, créditos, limite de requisições, servidor). Um 429 vem com Retry-After; um 402 significa que os créditos do proprietário acabaram.

Por que usar a API de agentes em vez de construir a sua

Você economiza meses de infraestrutura. Busca em documentos, sessões, limites de requisições, novas tentativas, contabilização de créditos e regras contra injeção de prompt já estão funcionando. Sua equipe escreve uma única chamada HTTP.

Um agente, um comportamento. A resposta que seu app mostra é a mesma que seu site e seu WhatsApp dão, porque é o mesmo agente. Atualize uma vez na IMFA e todos os canais acompanham.

Novas tentativas são seguras. A chave de idempotência faz com que uma nova tentativa por falha de rede devolva a resposta original, em vez de cobrar uma segunda mensagem.

Os leads deixam de ficar isolados. Puxe todos os leads captados por um único endpoint, venham de qualquer canal.

Você ainda pode partir para algo totalmente personalizado. Se precisa controlar cada camada, uma API de modelo pura dá esse controle, ao custo de construir e manter tudo por conta própria. Agentes de programação como Codex e Claude Code também podem gerenciar agentes da IMFA via MCP, enquanto seu servidor usa a chave REST para atender os clientes.

Perguntas frequentes sobre a API de agentes de IA

Posso chamar a API de agentes de IA direto do navegador?

Não. A chave consome os créditos do proprietário e precisa ficar em um servidor confiável. A API não libera acesso amplo a navegadores. Faça o navegador chamar um endpoint protegido seu, que então chama a IMFA.

Como autenticar uma requisição à API de agentes da IMFA?

Gere uma chave vinculada ao agente na visualização de API do agente ou na tela de Chaves de API e envie Authorization: Bearer YOUR_API_KEY a partir de código de servidor. Um token MCP é uma credencial diferente e não funciona aqui.

Como continuar a mesma conversa pela API?

Não envie sessionId na primeira requisição de chat, guarde o sessionId que a API devolver e envie-o com a próxima mensagem. IDs de sessão de conversas do site ou de canais são somente leitura e não podem continuar uma conversa pela API.

Por que a Idempotency-Key é obrigatória no chat?

Ela torna as novas tentativas seguras. Uma nova tentativa idêntica com a mesma chave devolve o mesmo resultado, em vez de criar uma nova mensagem. Use uma chave nova para cada nova mensagem.

A API de agentes usa meu conhecimento e minhas ferramentas?

Sim. Ela chama o agente publicado com as instruções, o modelo, o conhecimento, as skills, as ferramentas e as regras de segurança dele. As respostas continuam dependendo da configuração publicada, dos seus créditos e dos limites atuais do serviço.

O que acontece quando a API atinge o limite de requisições ou fica sem créditos?

Você recebe um 429 com o cabeçalho Retry-After quando atinge o limite, e um 402 quando os créditos do proprietário acabam. Trate todos os códigos de status documentados na sua integração.