Funcionários de IA via MCP

Dois jeitos de usar os seus funcionários de IA a partir de um agente externo: conversar com um num sandbox, ou rodar as ações nativas dele direto num contato real.

Conversar com um funcionário de IA

agents_chat_start → agents_chat_send (repete) → agents_chat_end. Exige o escopo agents:run (só admin).

A conversa roda o fluxo real do agente num sandbox descartável: um contato e uma conversa temporários, marcados como dados de teste. As ações de CRM que o agente toma (etiquetas, etapa, campos do contato) caem nesse contato-sandbox; os efeitos externos — envio no canal, e-mails, webhooks, créditos — são simulados e reportados como tal. Nada chega aos seus contatos reais.

// agents_chat_start
{ "agent_id": "…", "lead_simulation": { "name": "Ana", "company": "Acme", "phone": "+5511999990000" } }
// → { "session_id": "…", "agent": { "id", "name", "channel" }, "status": "active", "expires_at": "…" }

// agents_chat_send
{ "session_id": "…", "message": "Quero saber o preço do plano anual" }
// →
{
  "session_id": "…",
  "turn": 1,
  "replies": ["Claro! O plano anual…"],
  "status": "paused",                 // running | paused | completed | transferred | failed | blocked
  "waiting_for": "lead_reply",        // lead_reply | timer | null
  "can_skip_wait": false,
  "executed_nodes": ["trigger_1", "ai_step_2"],
  "side_effects": [
    { "tool": "add_tag", "args": { "tags": ["decisor"] }, "result": { "added": 1 }, "simulated": false, "scope": "sandbox" },
    { "tool": "send_email", "simulated": true, "scope": "sandbox" }
  ],
  "blocked_reason": null,
  "error": null,
  "expires_at": "…"
}

• event no lugar de message simula o que o canal mandaria: chat_started, invite_accepted, invite_ignored, no_response, wait_skipped (adianta um relógio quando can_skip_wait é true).
• O agente precisa de um canal ativo do tipo dele (um número de WhatsApp conectado para um agente de WhatsApp, e assim por diante); senão NO_ACTIVE_CHANNEL com details.channel_type. É a mesma regra do Modo Teste do app.
• Sessões expiram com 30 minutos paradas (SESSION_EXPIRED) e o sandbox é apagado. No máximo 5 sessões ativas por chave (LIMIT_REACHED). Sempre chame agents_chat_end ao terminar.
• lead_simulation.tag_ids já aplica etiquetas ao lead simulado, para exercitar filtros de gatilho e condições.

Rodar ações nativas direto

Estas tools executam as mesmas ações que um funcionário de IA faria, num contato real, sem fluxo. Escopo agent_tools:execute (só admin), exceto knowledge_search (knowledge:read) e agent_transfer_to_human (conversations:write).

Tool	Exige	O que acontece
knowledge_search	agent_id, query	Busca semântica nas bibliotecas de conhecimento do agente (FAQs, objeções, documentos, cases)
agent_register_lead_source	contact_id, source	Define a origem do lead e a atribuição (campanha, adset, criativo)
agent_send_email	contact_id, subject, body	Envia um e-mail transacional real ao contato
agent_transfer_to_human	agent_id, conversation_id	Encaminha uma conversa real ao setor/usuário configurado no agente
agent_schedule_meeting	agent_id, conversation_id	Manda o link de agendamento do agente como mensagem na conversa
agent_check_availability	agent_id	Horários livres do vendedor com quem o agente agendaria. Segura cada slot por 10 min, por isso é tool de escrita (aceita idempotency_key; dry_run ainda consulta ao vivo)
agent_book_meeting	agent_id, contact_id, slot_id	Agenda um dos slot_id devolvidos por agent_check_availability

• contact_id, agent_id e conversation_id precisam ser da sua conta; contato de sandbox é recusado.
• dry_run: true roda a ação em modo teste (nada é gravado, simulated: true), exceto knowledge_search (leitura) e agent_check_availability (as reservas de horário acontecem mesmo em modo teste, por desenho da tool do agente).
• agents_chat_end é idempotente: encerrar uma sessão já encerrada devolve already_ended: true.
• Sem conversation_id, agent_check_availability não persiste a trava de vendedor, então um agent_book_meeting depois pode cair em outro vendedor em setores com rodízio. Passe a conversa quando tiver uma.
• As demais tools nativas (add_tag, remove_tag, move_stage, create_opportunity, set_contact_field, lookup_contact_field) são a implementação por trás de contacts_add_tags, contacts_remove_tags, opportunities_move_stage, opportunities_create, contacts_update e contacts_get. O catálogo completo com JSON Schema é o resource getraze://tool-catalog.