Como configurar agentes de IA

Cada agente é uma entidade própria (não um usuário fantasma). Tela /admin/chat-ai-agents. Ele assume conversas 1:1 da fila Aguardando, responde com LLM e ferramentas, e devolve o atendimento quando um humano clica em Assumir.

Pré-requisito Chat ligado e Agentes de IA do Chat ligado em Gerais. Uma conexão LLM (padrão da plataforma ou token do tenant). Departamento da conexão WhatsApp/caixa de e-mail ajuda a escolher o agente certo.

Maquete

Agentes de IA

1Nome

FAQ Fiscal

2Tom

Humano / Formal

3Departamento

Fiscal · ou todos

4Padrão

Sim — assume se não houver agente do depto

5Instruções

Você é o atendimento fiscal do escritório. Não invente prazos. Transfira se pedir humano.

6FAQs {title, body}

Prazo DAS · O DAS vence no dia 20…

7Ferramentas

Responder · Consultar FAQs · Reenviar arquivos · Transferir

Passo a passo

Ligue Chat e Agentes de IA em Gerais. Cadastre a conexão LLM se não for usar a API padrão.
Configurações → Agentes de IA → novo agente. Nome, instruções, tom, departamento (ou todos), marque padrão se for o coringa.
Cadastre FAQs em pares título/texto. A ferramenta “Consultar FAQs” busca nesses itens.
Marque as ferramentas: sem “Responder” o agente não fala com o cliente; sem “Transferir” ele não passa para humano/departamento.
Deixe assunção automática ligada para ele pegar a fila waiting (nunca grupo).
Na inbox, a aba IA lista o que ele está atendendo. Humano clica em Assumir (takeover) quando quiser o controle.

Como a fila funciona

Mensagem inbound 1:1 em Aguardando → o sistema escolhe um agente habilitado do departamento da conexão/caixa, ou o default global → a conversa abre com o agente → o job HandleChatAiTurnJob roda na fila Horizon chat-ai (um job por conversa). O orquestrador manda histórico, FAQs e arquivos da thread ao LLM e pode chamar até 8 ferramentas.

Takeover humano Assumir tira assigned_ai_agent_id, coloca você como atendente e libera o composer. Notas internas já eram permitidas durante o turno da IA.

Glossário

Campo	O que faz
Nome	Aparece na bolha outbound (“FAQ Fiscal”, não “Você”) e no header.
Instruções	System prompt. Seja específico: o que pode, o que deve transferir.
Tom	Humano ou Formal — ajusta o estilo da resposta.
Conexão LLM	API padrão ou uma conexão do tenant.
Departamento / todos	Escopo. “Todos” compete pelo default se marcado como padrão.
Padrão (`is_default`)	Usado quando a conexão não tem agente do mesmo departamento.
Assunção automática	Pega fila `waiting` 1:1. Não assume grupo.
FAQs `{title, body}`	Base de conhecimento do agente. Não é a base do Ask do admin.
Responder	Permite enviar texto ao cliente.
Consultar FAQs	Tool de busca na knowledge do próprio agente.
Reenviar arquivos da conversa	Lista e reenvia mídia já presente na thread.
Transferir departamento/atendente	Passa a conversa para humano ou outro departamento.
Fila Horizon `chat-ai`	Onde o turno roda. Sem worker dessa fila, a IA não responde.

Erro comum Esperar que a IA atenda grupo, ou que responda com Chat on mas Agentes de IA off. Outro: Horizon sem a fila chat-ai — o job não processa. Confira também se existe agente default ou do mesmo departamento da conexão.