> ## Documentation Index
> Fetch the complete documentation index at: https://docs.evolutionfoundation.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Integração com Knowledge Nexus

A partir do `v1.0.0-rc3`, agentes de IA podem consultar **Knowledge Nexus spaces** diretamente do prompt, usando a tool nativa `knowledge_nexus_search`. Isso permite responder com base em documentação interna, FAQs e bases de conhecimento mantidas no Nexus, sem configurar tool customizada.

> Para a base de conhecimento embutida do CRM (PDFs, arquivos colados manualmente), continue usando o módulo [Base de Conhecimento](/user-guides/agents/knowledge-base). Nexus é complementar — útil quando sua organização já mantém uma base de conhecimento separada e quer reaproveitá-la no agente.

***

## Pré-requisitos

* Instalação do **Evo Nexus** acessível pela rede do CRM.
* Pelo menos um **space** criado no Nexus com documentos indexados.
* Permissão no seu papel para editar agentes (`agents.manage`).

A conexão entre CRM e Nexus é configurada pelo operador da instalação (ver documentação do Evo Nexus). Como usuário do CRM, você consome a integração sem configurar credencial.

***

## Vinculando um Space ao Agente

1. Abra o detalhe de um agente em `Agentes → [nome do agente]`.
2. Vá até a seção **Integrações** → **Knowledge Nexus**.
3. Clique no seletor de spaces. O CRM consulta a API do Nexus (via proxy do core-service) e lista os spaces disponíveis.
4. Marque os spaces que esse agente deve poder consultar.
5. Salve.

Você pode vincular múltiplos spaces a um mesmo agente — o agente decide qual consultar em cada momento, com base no contexto da pergunta.

***

## Como o agente usa o Nexus

O agente recebe automaticamente uma tool chamada `knowledge_nexus_search` no seu vocabulário. Quando o usuário faz uma pergunta cuja resposta plausivelmente está na base, o LLM chama essa tool:

```
knowledge_nexus_search(query="política de troca após 30 dias", space="suporte")
```

A tool retorna os trechos mais relevantes indexados no space. O agente usa esses trechos para compor a resposta, citando o contexto quando apropriado.

### Comportamento esperado

* **Resposta com base na fonte:** se o trecho encontrado responde diretamente, o agente cita a informação textualmente.
* **Resposta com lacuna:** se a base não cobre o caso, o agente informa que não encontrou informação específica e pede mais contexto, em vez de inventar (com prompt bem calibrado).
* **Resposta de retorno vazio:** se a busca não retorna nada, o agente continua a conversa sem citar a base.

***

## Quando usar Nexus vs Base de Conhecimento do CRM

| Use **Nexus** quando | Use **KB do CRM** quando |
| - | - |
| Sua organização já mantém base centralizada | Você quer uma KB exclusiva por agente |
| Conteúdo evolui frequentemente (wiki, docs vivos) | Conteúdo estático (PDFs, manuais fixos) |
| Múltiplos times consomem a mesma base | Conteúdo é específico de um único caso de uso |
| Você quer separar gestão de conhecimento do CRM | Você quer manter tudo dentro do CRM |

Não é exclusivo — você pode usar os dois ao mesmo tempo no mesmo agente.

***

## Diagnóstico

Se o agente não está usando o Nexus apesar de estar vinculado:

1. **Confirme a vinculação.** Reabra o detalhe do agente; o space deve aparecer marcado.
2. **Cheque permissões.** O agente precisa ter `agents.read` sobre os recursos vinculados.
3. **Veja se o space tem documentos indexados.** Se o space está vazio ou ainda processando documentos, a tool retorna vazio.
4. **Reveja o prompt.** Se o system prompt do agente é muito rígido (ex.: "responda apenas com base no que sabe"), ele pode não chamar a tool. Ajuste o prompt para deixar explícito quando consultar a base externa.
5. **Logs do processor.** O serviço `evo-ai-processor-community` registra as chamadas a tools — útil quando você precisa confirmar se a tool foi de fato invocada.

***

## Considerações Finais

A integração com Knowledge Nexus desacopla a gestão de conhecimento da gestão do CRM. Mantenha as bases atualizadas no lugar onde elas naturalmente vivem, e deixe o agente fazer a ponte na hora da conversa.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.