IA e agentes
As chaves de IA do provedor que você escolher, os blocos de IA nos fluxos, os agentes atendentes e o uso.
A IA fica na área do cliente, em IA: as chaves do seu provedor, os agentes que atendem pelos números e o uso do mês. Os fluxos também têm blocos de IA. Tudo usa a sua chave do provedor (OpenRouter, OpenAI, Anthropic, Gemini ou outro compatível), e cada chamada conta na cota de IA do plano.
/api/v1/ai/... não abrem com uma chave de API (wck_...), e uma chave de API também não cria, edita, publica nem inicia um fluxo que tenha um bloco de IA ou o bloco Agente: a resposta é 403 CLIENT_KEY_SCOPE. Esses recursos usam o que é do dono da conta: as chaves de IA, a cota e os agentes. Para ligar um sistema seu à IA, veja Pela sua integração.O plano precisa incluir a IA; os agentes têm a própria função e o próprio limite de quantos podem existir.
As chaves de IA
Em IA > Chaves você cadastra a chave do provedor, com o formato da API dele:
| Formato | Provedores | Endereço padrão |
|---|---|---|
openai_chat | OpenRouter, Groq, DeepSeek, Ollama, OpenAI e outros compatíveis | OpenRouter |
openai_responses | OpenAI (Responses) | OpenAI |
anthropic_messages | Anthropic | Anthropic |
gemini | Google Gemini | Gemini |
- O endereço é opcional: vazio, vale o padrão do formato. Preenchido, precisa ser
httpspúblico, sem endereço interno. - A chave é guardada cifrada e nunca volta inteira: a tela mostra só os 4 últimos caracteres.
- Testar faz uma chamada real e mínima ao provedor, que conta na cota do mês.
Os blocos de IA nos fluxos
No editor de fluxos, sete blocos chamam o modelo com uma das suas chaves:
| Bloco | Faz | Saídas | Variável |
|---|---|---|---|
Classificar (ai_classify) | Escolhe uma das categorias para o texto. | uma por categoria, outro, error | {{intencao}} |
Extrair (ai_extract) | Tira dados do texto (nome, empresa...) e pode salvar no contato. | ok, incompleto, error | {{extraido.<campo>}} |
Responder (ai_reply) | Escreve uma resposta e pode enviá-la. | ok, error | {{resposta_ia}} |
Resumir (ai_summarize) | Resume as últimas mensagens da conversa e pode salvar como nota. | ok, error | {{resumo}} |
Traduzir (ai_translate) | Traduz o texto. | ok, error | {{traducao}} |
Sentimento (ai_sentiment) | Diz se o texto é positivo, neutro ou negativo. | positivo, neutro, negativo, error | {{sentimento}} |
Decidir (ai_decide) | Escolhe uma das opções pela regra de cada uma. | uma por opção, nenhuma, error | {{decisao}} |
- Cada bloco tem a chave e, opcional, o modelo (vazio = o da chave).
- O fluxo não trava: um tempo esgotado ou uma resposta fora do formato tenta mais uma vez; depois disso, ou com a cota acabada, o bloco sai por
error. - Responder nunca envia uma resposta com um link que não estava no pedido.
- O bloco Agente (
ai_agent) roda um turno de um agente salvo dentro do fluxo e sai porok,handoff(passou para uma pessoa) ouerror; a resposta fica em{{agente.resposta}}.
Os agentes
Em IA > Agentes você monta um atendente: as instruções, a chave e o modelo, quantas mensagens da conversa ele lê, as ferramentas e os limites. Ligado num número, ele responde sozinho as mensagens que nenhum fluxo pegou, só em conversas sem uma pessoa atendendo, e no horário que você definir.
As ferramentas, cada uma com a sua autonomia:
act: a ferramenta roda;suggest: não roda; o agente escreve uma nota na conversa para uma pessoa decidir;off: o agente nem a vê.
Ele pode passar para uma pessoa, marcar uma etiqueta, salvar um campo, consultar o contato, chamar um endpoint seu (até 10, só endereços públicos), iniciar um fluxo e, com o CRM no plano, consultar, criar, mover, ganhar e perder os negócios do contato. Por padrão, só a passagem para humano age; as do CRM que escrevem começam como suggest.
A espera antes de responder (de 0 a 60 segundos, padrão 8): o agente espera o contato terminar de escrever e responde tudo de uma vez. Com 8 segundos, "oi", "tudo bem?" e "quero saber o preço" em 5 segundos ganham uma resposta só. Com 0, ele responde cada mensagem.
A passagem para humano acontece pela ferramenta, por uma palavra como "atendente" ou depois de muitas respostas seguidas. A conversa vai para a pessoa escolhida (ou fica sem dono, com a etiqueta "precisa de humano"), ganha uma nota com o motivo, e o contato recebe a mensagem de passagem, se houver. Uma pessoa que responde ou assume a conversa também pausa o agente.
Testar abre um chat com o agente: ele responde como responderia, mostra as ferramentas que chamaria, e nada é enviado nem gravado. A chamada ao provedor é real e conta na cota.
O uso
Cada chamada de IA (bloco, agente ou teste) conta uma na cota mensal de IA do plano; acabada a cota, as chamadas param até o mês seguinte. Em IA > Uso ficam as chamadas por dia e por origem, os tokens, os erros e o tempo médio. O uso guarda o modelo, os tokens e o tempo de cada chamada, nunca o texto enviado nem a resposta.
Pela sua integração
- Um fluxo com IA, chamado pelo seu sistema: monte o fluxo na área do cliente e chame o webhook de entrada dele. O webhook não usa chave: o token do fluxo vai no caminho, e os campos do corpo viram variáveis do fluxo.
- Uma IA sua usando o WhatsApp: ligue-a ao número pelo MCP.
- Saber quando uma mensagem chega: use os webhooks ou o tempo real.
Por exemplo, para chamar pelo webhook de entrada um fluxo que responde com IA:
curl -X POST "$API_URL/api/v1/hooks/flows/fwh_seu_token_aqui" \
-H "Content-Type: application/json" \
-d '{"phone": "+55 81 99999-0001", "name": "Ana", "pergunta": "Qual o prazo de entrega?"}'