Conectando a Agentes

Criar ou preencher uma base não a conecta automaticamente a um Agente IA. O vínculo é feito no editor do agente, na seção Conhecimento. Ao selecionar ao menos uma base, o SquadOS ativa internamente a busca search_knowledge_base; você não precisa adicionar essa busca em Ferramentas.

Antes de conectar

• O agente e a base precisam pertencer à organização ativa.
• Sua função precisa permitir editar o agente (agents.write) e editar bases (bases.write). A primeira permissão abre o editor; a segunda também é exigida para salvar o vínculo.
• Espere os itens necessários ficarem Processados. O número de itens buscáveis mostrado no editor soma todos os itens selecionados, inclusive os que ainda estão processando ou terminaram com erro; ele não comprova sozinho que o conteúdo já pode ser recuperado.

Se você ainda precisa adicionar conteúdo, consulte Upload de Documentos.

Selecionando as bases

1. Abra Admin → Agentes e escolha Editar no agente.
2. Na barra lateral do editor, abra Conhecimento.
3. Em Bases de conhecimento, marque uma ou mais bases.
4. Confira o nome, a descrição e a quantidade de itens mostrada em cada base.
5. Se aparecer um aviso de base sem descrição, selecione Gerenciar e descreva na própria base o assunto que ela cobre. O agente recebe esse catálogo para decidir se a busca se aplica à pergunta.
6. Selecione Salvar.

Descartar restaura o último estado salvo. Se você tentar trocar de seção com alterações pendentes, o editor pede confirmação antes de abandoná-las.

Caution

Se você consegue marcar bases, mas recebe Não consegui salvar o conhecimento deste agente, peça a um administrador para conferir bases.write, além de agents.write. Hoje a interface mostra os controles antes de validar essa segunda permissão.

Entendendo a instrução de busca

Expanda Instrução que o agente recebe para conferir a orientação montada pelo SquadOS. Ela reúne, nesta ordem:

1. a regra geral para consultar o material da organização antes de responder de memória;
2. o nome e a descrição de cada base selecionada;
3. a Regra só para este agente, quando preenchida.

A regra específica é opcional, aceita até 500 caracteres e aparece por último, com precedência explícita sobre a orientação geral. Use-a para restringir ou priorizar a busca daquele agente, sem repetir o catálogo das bases. Por exemplo:

Consulte estas bases somente para dúvidas sobre planos, políticas e configuração.

Se uma base não tem descrição, o agente recebe apenas o nome dela. Corrigir a descrição deixa mais claro quando a busca se aplica para todos os agentes que a utilizam.

Mais de uma base

Selecione várias bases quando o agente precisa consultar domínios diferentes, como suporte técnico, políticas comerciais e catálogo de produtos. A busca fica restrita às bases marcadas e pode combinar trechos relevantes de mais de uma fonte.

Evite manter versões contraditórias ou conteúdo muito repetido em bases selecionadas para o mesmo agente. A conexão define onde pesquisar, mas não garante que uma pergunta recuperará o trecho correto. Qualidade de conteúdo, processamento e relevância da busca precisam ser validados separadamente.

AutoLearn

Depois que ao menos uma base é marcada, aparece a área AutoLearn. Ative Registrar perguntas sem resposta para disponibilizar ao agente o registro de lacunas. O runtime o orienta a registrar uma oportunidade quando a busca retorna exatamente que não encontrou informação relevante, ou quando os trechos são claramente de outro assunto — apenas para perguntas dentro do escopo do agente.

O registro é uma ferramenta acionada pelo modelo; portanto, não trate cada resposta incompleta como garantia de que uma oportunidade foi criada. A área mostra lacunas recentes daquele agente e Ver oportunidades abre a fila de revisão. Veja Oportunidades de Aprendizado (AutoLearn) para revisar, aprovar ou ignorar os registros.

Ao desmarcar a última base e salvar, o SquadOS desativa a busca e o AutoLearn para esse agente.

Bases e blocos de contexto não são a mesma coisa

Na mesma seção, Blocos de contexto aparece ao lado das bases. Uma base é consultada sob demanda; um bloco ativo é carregado por inteiro em todas as respostas do agente. Use Blocos de Contexto Reutilizáveis para escolher o mecanismo correto e entender o impacto em tokens.

Caution

O botão Salvar grava bases e blocos da seção. Se você alterar os dois grupos ao mesmo tempo e receber um erro, confira novamente ambos antes de repetir: as operações atuais não são atômicas e parte da configuração pode já ter sido persistida.

Validando a conexão

Depois de salvar, use o painel de teste do editor com um conjunto pequeno e controlado:

• uma pergunta cuja resposta está em um item Processado;
• uma paráfrase que não repete literalmente o documento;
• uma pergunta que exige combinar informações de duas bases selecionadas;
• uma pergunta sobre uma base não selecionada;
• uma pergunta fora do escopo do agente.

Confira a resposta e os detalhes da execução para verificar se a busca foi chamada e quais fontes chegaram ao modelo. Uma chamada bem-sucedida prova que a configuração foi executada; não prova, sozinha, que o conteúdo recuperado era suficiente ou correto.