Agente de IA — visao geral

O agente de IA e o cerebro conversacional de cada conexao. Ele responde DMs em linguagem natural no Instagram, Messenger e WhatsApp, usando um modelo de linguagem (LLM) do OpenAI ou do Anthropic.

Uma conexao, um agente

Cada conexao tem exatamente um agente. A configuracao vive em /dashboard/[connectionId]/agent. Voce define:

• Nome — rotulo interno (nao aparece para o cliente).
• Prompt do sistema (system instruction) — personalidade, papel, regras.
• Dados guiados — JSON opcional com informacoes estruturadas que o agente pode consultar.
• Provedor — OpenAI ou Anthropic.
• Modelo — gpt-4o-mini, claude-haiku-4-5, etc.
• Max tokens — tamanho maximo da resposta.
• Temperature — criatividade (0 = determinista, 1 = mais criativo).
• Delay de resposta (ms) — pausa artificial antes de responder (parece mais humano).
• Ativo — liga/desliga.
• Chave BYOK opcional — chave OpenAI/Anthropic dedicada so para este agente.

IA vs automacoes — quando usar o que

Situacao	Use
Alguem comenta "ebook" no post e voce quer enviar o link	Automacao
Cliente pede informacoes sobre o seu servico em DM	Agente de IA
Capturar email/telefone antes de liberar link	Automacao com coleta de lead
Responder perguntas variadas sobre produto, politica, horario, precos	Agente de IA
Fazer upsell em conversa	Agente de IA

Ambos convivem — uma automacao de comentario pode iniciar uma DM, e a partir dai o agente IA continua a conversa.

Como funciona cada resposta

Quando uma DM chega, o UltronChat:

1. Recebe o webhook no Cloudflare Worker.
2. Enfileira no QStash e dispara a Edge Function ai-responder.
3. Checa se a conversa esta em uma sessao de coleta de lead — se sim, delega para lead-collector.
4. Checa se a conversa esta pausada (is_paused) — se sim, salva a mensagem mas nao responde.
5. Detecta loops (IA respondendo IA) e pausa se necessario.
6. Busca historico das ultimas 10 mensagens, informacoes do usuario (nome, username) e eventuais documentos RAG (em breve).
7. Monta o prompt usando: system_instruction + contexto do usuario + historico + mensagem atual (inclui imagem/audio processados).
8. Chama o LLM usando sua chave BYOK (especifica do agente OU global).
9. Aguarda o delay configurado e envia a resposta pelo adapter da plataforma (Instagram, Messenger ou WhatsApp).
10. Publica o evento no canal Realtime da conversa (usado pelo Live Chat).

Se a chave BYOK nao estiver configurada, ou o provider retornar erro 401 (chave invalida), o agente e automaticamente pausado e voce recebe um erro em agents.api_key_last_error. Solucao em BYOK chave global.

Tipos de mensagem suportados

• Texto — processamento normal.
• Imagem — a imagem e passada ao modelo (vision). Exige modelo com vision, como gpt-4o ou claude-3.5-sonnet.
• Audio — o UltronChat transcreve o audio (Whisper via OpenAI) e envia o texto como contexto.

Se voce quer que a IA entenda imagens e audios, escolha modelo com vision e deixe a chave BYOK com acesso ao Whisper.

Proximos passos

• Escrever system instruction
• Escolher modelo e parametros
• Cadastrar chave BYOK global