Agentes Especialistas¶

Um Agente Especialista é um agente baseado em LLM dentro de um assistente. Cada Agente Especialista tem um papel específico, prompt de sistema, conjunto de tools e área de especialização. Quando você chama um assistente, o mecanismo de roteamento seleciona o Agente Especialista adequado para tratar a request.

O que é um Agente Especialista?¶

Pense em um assistente como uma equipe de especialistas. Cada especialista (Agente Especialista) cuida de um domínio específico:

Um Agente Especialista em Faturamento responde perguntas sobre faturas, pagamentos e assinaturas
Um Agente Especialista em Suporte Técnico ajuda com configuração de produtos e troubleshooting
Um Agente Assistente Geral cuida de saudações, conversa casual e roteamento

Quando um usuário envia uma mensagem, o mecanismo de roteamento analisa a mensagem e o contexto da conversa e direciona para o Agente Especialista mais preparado para responder.

Roteamento¶

O processo de roteamento acontece automaticamente e é transparente para quem chama a API. Você sempre usa o mesmo UUID de assistente — a plataforma seleciona e invoca o Agente Especialista correto internamente.

O mecanismo de roteamento usa uma combinação de:

Etapa A: Correspondência por palavras-chave e padrões (rápida, baixo custo)
Etapa B: Similaridade semântica baseada em embeddings (precisa, com cache)
Etapa C: Decisão de roteamento via LLM (alta confiança para casos ambíguos)

A decisão de roteamento se baseia no conteúdo da mensagem atual, no histórico da conversa e em quaisquer instructions fornecidas na request.

Handover de Agente Especialista¶

Quando o Agente Especialista ativo determina que não é o melhor para a request atual — seja porque o tópico mudou ou porque a necessidade do usuário está fora do seu domínio — ele pode realizar um handover para um Agente Especialista mais adequado.

Handover em Respostas com Streaming¶

Um evento de handover aparece no stream SSE como um evento response.output_item.added com type: "handover":

{
  "type": "response.output_item.added",
  "item": {
    "type": "handover",
    "from_specialist": "Assistente Geral",
    "to_specialist": "Especialista em Faturamento",
    "reason": "O usuário está perguntando sobre uma fatura do mês passado"
  }
}

Handover em Respostas sem Streaming¶

Em respostas sem streaming, os itens de handover aparecem no array output:

{
  "id": "resp_01234567-89ab-cdef-0123-456789abcdef",
  "status": "completed",
  "output": [
    {
      "type": "handover",
      "from_specialist": "Assistente Geral",
      "to_specialist": "Especialista em Faturamento",
      "reason": "O usuário está perguntando sobre uma fatura do mês passado"
    },
    {
      "type": "message",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "Conectei você ao nosso Especialista em Faturamento, que pode ajudá-lo com sua fatura."
        }
      ]
    }
  ]
}

Campos do Handover¶

Campo	Tipo	Descrição
`type`	`"handover"`	Identifica este item de saída como uma notificação de handover
`from_specialist`	`string`	Nome de exibição do Agente Especialista que estava ativo
`to_specialist`	`string`	Nome de exibição do Agente Especialista que assumiu o controle
`reason`	`string`	Explicação legível do motivo do handover

Tratando Handovers na sua Interface¶

Eventos de handover são informativos — você não precisa tomar nenhuma ação. Porém, pode ser útil exibi-los para os usuários ou usá-los para analytics:

for await (const event of stream) {
  if (event.type === 'response.output_item.added') {
    if (event.item.type === 'handover') {
      // Opcional: exibir uma mensagem de status na interface
      console.log(
        `Transferindo para ${event.item.to_specialist}: ${event.item.reason}`
      );
    }
  }

  if (event.type === 'response.output_text.delta') {
    process.stdout.write(event.delta);
  }
}

Handover Direto por Nome¶

Se sua aplicação precisa direcionar uma request para um Agente Especialista específico — ignorando o mecanismo de roteamento — você pode especificar o Agente Especialista pelo nome no campo instructions:

{
  "model": "SEU_ID_DE_ASSISTENTE",
  "input": "Preciso de ajuda com minha fatura #FAT-2024-001",
  "instructions": "Direcione esta requisição diretamente ao Especialista em Faturamento."
}

Disponibilidade depende da configuração

O handover direto por nome funciona quando o mecanismo de roteamento da plataforma está configurado para respeitar roteamento baseado em instruções. Fale com seu administrador Nodexa para confirmar.

Contexto do Agente Especialista¶

Cada Agente Especialista tem seu próprio prompt de sistema e personalidade configurados no painel de administração da Nodexa. Porém, algum contexto é compartilhado entre todos os Agentes Especialistas de um assistente:

Memória do usuário — carregada no início de cada request e disponível para todos os Agentes Especialistas
Claims do usuário — disponíveis para todos os Agentes Especialistas
Histórico da conversa — o histórico completo está disponível independentemente de qual Agente Especialista tratou os turnos anteriores

Identificando o Agente Especialista Ativo¶

A resposta atualmente não expõe qual Agente Especialista tratou a request no objeto de resposta. Para rastrear qual Agente Especialista foi usado, monitore os eventos response.output_item.added no stream para itens de handover, ou confira os logs de conversas no painel de administração da Nodexa.