Agentes

Um agente é a entidade que responde às mensagens em uma sessão. A Antonnia suporta dois tipos de agente: agentes de IA (automatizados) e agentes humanos (suporte ao vivo).

Tipos de agente

Agente de IA

Agentes de IA usam o motor de assistentes da Antonnia para responder automaticamente às mensagens. Quando você chama POST /sessions/{id}/reply, o agente de IA processa a conversa e gera uma resposta.

{
  "id": "agent_abc",
  "name": "Support Bot",
  "type": "ai",
  "assistant_id": "asst_123",
  "organization_id": "org_xyz",
  "created_at": "2025-01-15T10:30:00Z"
}

Agente humano

Agentes humanos representam operadores de suporte ao vivo. Sessões atribuídas a agentes humanos não respondem automaticamente — o humano responde através de uma interface separada.

{
  "id": "agent_def",
  "name": "João Silva",
  "type": "human",
  "profile_id": "profile_456",
  "organization_id": "org_xyz",
  "created_at": "2025-01-15T10:30:00Z"
}

Atribuição de agente

Toda sessão tem um campo agent (que pode ser null). O agente é definido quando:

1. Criação da sessão — passe agent_id em POST /sessions
2. Transferência — mude o agente com POST /sessions/{id}/transfer

Fluxo de resposta da IA

Apenas sessões com um agente de IA respondem ao POST /sessions/{id}/reply. O fluxo:

1. Sua integração chama /reply com um debounce_time opcional (padrão: 3 segundos)
2. O debounce agrupa mensagens sequenciais rápidas em um único turno da IA
3. O agente de IA gera uma resposta
4. A Antonnia dispara um webhook message.created com role: "assistant"
5. Sua integração entrega a mensagem através do canal

Padrões de transferência

Cenários comuns de transferência:

• IA → Humano: Escalação quando a IA não consegue resolver o problema
• Humano → IA: Devolver para a IA após o humano resolver uma subtarefa
• IA → null: Remover agente para pausar respostas automáticas (ex.: durante uma pesquisa de satisfação)

// Transfer to a human agent
POST /sessions/{id}/transfer
{ "agent_id": "agent_human_123" }

// Remove agent (pause auto-replies)
POST /sessions/{id}/transfer
{ "agent_id": null }