Configuração Pós-Instalação

Configure conectores, ontologia, Knowledge, Skills e o MCP Server após a instalação da plataforma. Tempo estimado: 2–4 horas para um setup inicial funcional.

A plataforma funciona em camadas que se constroem uma sobre a outra. O setup segue esta sequência:

1. Workspace Git    → versionar configurações
       ↓
2. Conectores       → trazer dados para dentro
       ↓
3. Ontologia        → definir quais entidades rastrear
       ↓
4. Knowledge        → carregar documentos e políticas
       ↓
5. Skills + MCP     → conectar os agentes ao contexto
       ↓
6. Verificação      → confirmar que tudo está saudável

Você pode executar cada passo em dias diferentes. A plataforma começa a gerar valor assim que o primeiro conector e a ontologia estiverem configurados.

---

Passo 1 — Workspace Git

O que é o Workspace Git

O Workspace Git é o repositório Git que armazena todas as configurações da plataforma do cliente. Todos os arquivos de configuração — ontologias, transformations, templates de contexto, skills — ficam versionados nesse repositório.

Por que versionar em Git:

• Histórico completo de alterações de configuração
• Possibilidade de rollback para qualquer versão anterior
• Revisão de mudanças via Pull Request antes de aplicar
• Rastreabilidade de quem alterou o quê e quando

O que fica no Workspace Git:

• config/memory/graph_mapping.yaml — ontologia do grafo de entidades
• config/connectors/ — configurações dos conectores (tabelas, modos de sync)
• skills/scripts/ — scripts de Skills executáveis pelos agentes
• skills/secrets/ — referências a segredos (nunca valores em plaintext)
• knowledge/source_types/ — configurações das fontes operacionais do Knowledge

Como configurar

1. Acesse Settings no Console

   No menu lateral, clique em Settings → Workspace Git.

2. Conecte o repositório

   Informe a URL do repositório Git (pode ser GitHub, GitLab ou Bitbucket) e o token de acesso com permissão de leitura e escrita.

3. Defina a branch principal

   Configure a branch que a plataforma deve acompanhar (geralmente main ou production).

4. Confirme a sincronização

   Após salvar, a plataforma sincroniza o Workspace. O status deve mudar para Conectado.

---

Passo 2 — Conectores

O que são conectores

Conectores são as ligações entre a plataforma e suas fontes de dados. Sem pelo menos um conector ativo, o Memory não tem dados para processar e os pipelines não têm origem.

Quais conectores adicionar primeiro

Objetivo	Conectores prioritários
Rastrear clientes e contratos (Memory)	CRM (HubSpot, Salesforce), banco principal (PostgreSQL)
Base de conhecimento para agentes (Knowledge)	Notion, Confluence, Google Drive
Contexto de comunicação e atendimento	Slack, Zendesk

Para o mínimo funcional: 1 banco de dados ou CRM para o Memory + 1 fonte de documentos para o Knowledge.

Como adicionar um conector

1. Acesse Connections

   No Console, clique em Connections na sidebar esquerda.

2. Clique em Nova Conexão

   Selecione o tipo de conector (banco de dados, API, documentos).

3. Preencha as credenciais

   Cada conector tem campos específicos. Consulte o guia de conectores para instruções detalhadas por tipo de fonte.

4. Teste e ative

   Clique em Testar Conexão antes de salvar. Após salvar, o conector inicia a primeira sincronização automaticamente.

Verificando o status

Após configurar, aguarde até 5 minutos e verifique:

• Status Conectado (verde) — funcionando normalmente
• Status Sincronizando (azul) — primeira carga em progresso
• Status Erro (vermelho) — clique em ··· → “Ver logs” para o erro específico

---

Passo 3 — Ontologia do Memory

O que é a ontologia

A ontologia define quais tipos de entidades o Memory deve extrair, consolidar e rastrear. Sem ela, o Memory não sabe o que procurar nas fontes de dados.

Uma entidade pode ser um cliente, um associado, um contrato, uma oportunidade — qualquer objeto de negócio relevante para o seu contexto.

Como configurar

1. Acesse Memory → Configuration

   No Console, clique em Memory na sidebar, depois em Configuration.

2. Selecione um perfil base

   Escolha o perfil mais próximo da sua operação para começar com sugestões pré-configuradas:

   SaaS B2B / Customer Success

   Tipos sugeridos: Cliente, Contrato, Oportunidade, Usuário

   Atributos consolidados por Cliente: MRR/ARR, plano contratado, data de renovação, NPS histórico, contatos principais, features solicitadas, histórico de incidentes, responsável de CS.

   Fintech / Crédito

   Tipos sugeridos: Tomador, Operação, Garantia, Cobrança

   Atributos consolidados por Tomador: CPF/CNPJ, score de crédito, operações ativas, histórico de pagamentos, contatos, alertas de cobrança, renegociações.

   Cooperativa de Crédito

   Tipos sugeridos: Associado, Produto, Sinistro, Defesa de Crédito

   Atributos consolidados por Associado: histórico de produtos contratados, comportamento de pagamento, sinistros em análise, documentos de crédito.

3. Ajuste conforme necessário

   Adicione tipos customizados ou ajuste os atributos de cada tipo para o contexto específico da sua empresa.

4. Configure o confidence threshold

   Define o nível de confiança mínimo para aprovação automática de extração:

   Configuração	Threshold	Quando usar
   Conservador	0.90+	Dados críticos (crédito, compliance)
   Balanceado	0.80+	Recomendado para começar
   Agressivo	0.70+	Quando velocidade importa mais que precisão

   Recomendação: comece com Balanceado (0.80). Após 2 semanas, avalie o volume da fila de revisão e ajuste.

Revisão de entidades extraídas

Após configurar a ontologia, acesse Memory → Review Queue para aprovar as primeiras entidades extraídas:

• Aprovar — entidade vai para o grafo principal
• Editar e aprovar — corrige atributos antes de incluir
• Rejeitar — não entra no grafo; o modelo aprende com a rejeição

Nos primeiros dias espere uma fila maior — o modelo ainda está aprendendo os padrões das suas fontes. Com o tempo, a taxa de aprovação automática aumenta.

---

Passo 4 — Knowledge

O que adicionar ao Knowledge

Conteúdo de alto valor:

• Políticas internas (crédito, cobrança, atendimento, compliance)
• Manuais de produto e ERP
• Runbooks operacionais (onboarding, sinistros, renovações)
• FAQs e bases de artigos de suporte
• Regimentos e normativas internas

Importante: documentos NÃO são carregados automaticamente. É necessário selecionar manualmente quais arquivos ou pastas serão indexados. A opção de carregar documento de uma fonte (Notion, Google Drive, etc.) só aparece se o conector respectivo estiver configurado no Passo 2.

Como adicionar fontes de documentos

1. Acesse Knowledge no Console

   Clique em Knowledge na sidebar.

2. Adicione uma fonte

   Clique em + Adicionar e escolha o tipo:

   • Conectar fonte — usa um conector já configurado (Notion, Google Drive, Confluence). Selecione as pastas ou páginas específicas que deseja indexar.
   • Upload — envie arquivos PDF, DOCX, TXT ou Markdown diretamente. Limite: 50MB por arquivo.
   • URL — indexa páginas web públicas com re-indexação periódica.
3. Organize em Collections

   Agrupe documentos em Collections por tema (ex: “Crédito”, “Atendimento”, “RH”). Isso permite que agentes consultem apenas o subconjunto relevante para cada tarefa.

4. Verifique a qualidade da indexação

   Após a ingestão, clique em Ver chunks em qualquer documento e teste com perguntas reais no campo de busca semântica. Todos os chunks devem ter status verde.

---

Passo 5 — Skills e MCP

Como o agente consome o contexto

A orquestração de contexto roda nos agentes do próprio cliente. O agente consulta Memory e Knowledge pelo MCP Server e executa Skills — scripts versionados no Workspace Git — para cruzar fontes, gerar relatórios e rodar automações. Você conecta os dois nesta etapa: expõe as ferramentas via MCP e disponibiliza as primeiras Skills.

Conectar um agente via MCP

O MCP Server expõe as ferramentas search_entity, get_entity_context e search_knowledge para qualquer cliente MCP (Claude Code, Cursor, Microsoft Copilot).

1. Escolha o transporte

   Use stdio para clientes locais (Claude Code, Cursor) ou sse para agentes remotos (Microsoft Copilot, porta 8005). Ver MCP Server para a configuração de cada cliente.

2. Aponte para as APIs internas

   Configure MEMORY_API_URL (http://localhost:8002) e KNOWLEDGE_API_URL (http://localhost:8003) no cliente MCP. Para o modo sse, defina também MCP_API_KEY.

3. Valide a conexão

   No agente conectado, peça o contexto de uma entidade conhecida. O agente deve chamar search_entity seguido de get_entity_context e retornar o perfil consolidado em Markdown.

Disponibilizar a primeira Skill

1. Escreva a skill no Workspace Git

   Cada skill é um par de arquivos em /workspace/skills/scripts/ — um .yaml de metadados e o script (.py ou .js). Ver Skills para a estrutura completa.

2. Commite e faça push

   Após o push, a plataforma sincroniza o Workspace Git e a skill aparece em Skills no Console.

3. Execute e acompanhe o log

   Abra Skills no Console, localize a skill, preencha os parâmetros e clique em Executar. Acompanhe o log de execução em tempo real.

---

Passo 6 — Verificação Final

Antes de conectar um agente à plataforma, verifique:

Conectores:

• Pelo menos 1 conector com status “Conectado” (verde)
• Nenhum conector com status “Erro” sem explicação
• Última sincronização dentro do intervalo esperado

Memory:

• Pelo menos 1 tipo de entidade configurado na ontologia
• Pelo menos 1 entidade listada em Memory → Entities
• Fila de revisão com volume gerenciável

Knowledge:

• Pelo menos 1 documento com embedding completo (status verde)
• Busca semântica retornando resultados relevantes para perguntas de teste

Skills e MCP:

• MCP Server conectado a pelo menos 1 agente
• Agente consegue chamar get_entity_context e receber o perfil consolidado
• Pelo menos 1 Skill sincronizada do Workspace Git e visível em Skills
• Última execução de Skill concluída com sucesso

Dashboard:

• Nenhum item crítico no painel “Requer Atenção”

---

Próximos passos

Com a configuração inicial completa, conecte seus agentes:

MCP Server

Conecte Claude Code, ChatGPT ou Microsoft Copilot à plataforma.

Skills

Configure automações e análises executadas por agentes.