Ir para o conteúdo

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.

A IA é configurada pela área do cliente. As rotas /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:

FormatoProvedoresEndereço padrão
openai_chatOpenRouter, Groq, DeepSeek, Ollama, OpenAI e outros compatíveisOpenRouter
openai_responsesOpenAI (Responses)OpenAI
anthropic_messagesAnthropicAnthropic
geminiGoogle GeminiGemini
  • O endereço é opcional: vazio, vale o padrão do formato. Preenchido, precisa ser https pú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:

BlocoFazSaídasVariá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 por ok, handoff (passou para uma pessoa) ou error; 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:

bash
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?"}'