Assistentes¶
Um assistente é a entidade principal com a qual você interage pela API Nodexa. Ao fazer uma request para POST /v1/responses, você especifica um assistente pelo UUID no campo model. O assistente determina quais Agentes Especialistas vão tratar a request, quais tools estarão disponíveis e como a memória e o contexto do usuário serão aplicados.
O Campo model¶
Na Responses API da OpenAI, model geralmente se refere ao nome de um modelo LLM (por exemplo, "gpt-4o"). Na Nodexa, model é o UUID de um Assistente Nodexa:
O UUID do assistente é um identificador opaco. Ele não codifica informações sobre os LLMs por trás — esses detalhes são configurados no painel de administração da Nodexa e podem mudar sem aviso.
Onde encontrar seu ID de assistente
O administrador da plataforma Nodexa configura os assistentes e fornece seus UUIDs. Você também pode encontrá-los no painel de administração da Nodexa, na seção de Assistentes.
O que um Assistente Encapsula¶
Um assistente é uma unidade configurada que inclui:
| Componente | Descrição |
|---|---|
| Agentes Especialistas | Um ou mais agentes baseados em LLM, cada um com um papel específico, prompt de sistema e capacidades |
| Configuração de roteamento | Regras e um roteador LLM que decide qual Agente Especialista trata cada request |
| Tools | Integrações de API REST, conexões com servidores MCP, recuperação de base de conhecimento e busca na web |
| Configurações de memória | Se a memória por usuário está habilitada e como ela é aplicada |
| Estilo de resposta | Preferências de tom, idioma e formatação |
Capacidades¶
Roteamento Multi-Agente¶
Um único assistente pode ter múltiplos Agentes Especialistas associados. Quando você envia uma mensagem, o mecanismo de roteamento da plataforma seleciona o Agente Especialista mais adequado com base no conteúdo da mensagem, no contexto do usuário e nas regras de roteamento. Isso é transparente para quem chama a API — você sempre usa o mesmo UUID de assistente e recebe a melhor resposta do Agente Especialista correto.
Confira Agentes Especialistas para mais detalhes.
Tools Integradas¶
Os administradores configuram tools no nível do assistente. Elas podem incluir:
- Recuperação de base de conhecimento — busca semântica em documentos
- Integrações de API REST — chamadas a APIs externas
- Servidores MCP (Model Context Protocol) — descoberta dinâmica de tools
- Busca na web — busca em tempo real via OpenAI, Claude ou Gemini
Você pode complementar ou substituir essas tools na hora da request usando o campo tools. Confira Precedência de Tools.
Memória por Usuário¶
Quando você inclui x-user-id na sua request, o assistente carrega itens de memória relevantes para aquele usuário e os injeta no contexto. Após a conversa, novas memórias podem ser armazenadas automaticamente. Isso permite que o assistente lembre das preferências do usuário, interações passadas e contexto relevante entre sessões.
Dados do Usuário (Claims)¶
Os claims fornecem contexto estruturado sobre o usuário (por exemplo, plano de assinatura, função, idioma preferido). Os claims são injetados automaticamente no contexto do assistente quando x-user-id é fornecido. O assistente pode usar esses claims nas suas respostas.
Assistente vs. Modelo LLM¶
| Aspecto | Assistente Nodexa | Modelo LLM |
|---|---|---|
| Identificado por | UUID (asst_...) |
Nome do modelo (gpt-4o, claude-3-5-sonnet, etc.) |
| Roteamento | Mecanismo de roteamento multi-agente | Modelo único |
| Tools | Configuradas no painel admin + substituíveis por request | Devem ser fornecidas por request |
| Memória | Memória por usuário integrada | Precisa ser implementada por você |
| Prompt de sistema | Configurado por Agente Especialista | Deve ser fornecido por request |
| Provedor | Abstraído — pode ser OpenAI, Anthropic, Google ou outros | Provedor fixo |
Múltiplos Assistentes¶
Sua instância Nodexa pode ter múltiplos assistentes, cada um configurado para um caso de uso diferente. Por exemplo:
- Um assistente de suporte ao cliente
- Um assistente de documentação técnica
- Um assistente de base de conhecimento interna
Cada um tem seu próprio UUID. Você pode integrar múltiplos assistentes na mesma aplicação alternando o valor de model.
Handover entre Agentes Especialistas¶
Quando o Agente Especialista ativo determina que outro Agente Especialista é mais adequado para a conversa atual, ele pode transferir o controle (handover). Isso gera um evento handover no stream SSE (ou um item handover no array de saída para requests sem streaming).
O handover é transparente para o UUID do assistente — você continua usando o mesmo valor de model. O mecanismo de roteamento gerencia qual Agente Especialista está ativo.
Confira Agentes Especialistas e Eventos SSE — handover para mais detalhes.