Pular para o conteúdo
Guida

Mecanismos de pesquisa

O Guida oferece duas integrações de pesquisa distintas. Para indexação local com escopo de espaço de trabalho e configuração zero, use o índice Lucene.NET integrado. Para escala massiva e integração externa, conecte-se diretamente a clusters Elasticsearch.

Índice de pesquisa local (Lucene)

Seção intitulada “Índice de pesquisa local (Lucene)”

g.search.* fornece um índice de pesquisa de texto completo com escopo de espaço de trabalho, baseado em Lucene.NET. Ele não exige configuração, roda inteiramente localmente e persiste dados dentro da pasta do espaço de trabalho (.guida/search-index/).

Casos de uso:

  • Indexar texto extraído de centenas de páginas para recuperação rápida.
  • Construir bases de conhecimento locais para Retrieval-Augmented Generation (RAG) com LLM.
  • Encontrar itens de fila ou documentos armazenados por correspondência aproximada.

Exemplo

Seção intitulada “Exemplo”
async function main() {
  // Indexar um documento
  g.search.index({
    _key: "article-123",
    _collection: "articles",
    title: "Entendendo automação de navegador",
    body: "Guida é um navegador orientado por agentes...",
    url: "https://example.com/article"
  });


  // Consultar com sintaxe Lucene padrão
  // Suporta wildcards, correspondência fuzzy (~) e consultas por campo
  const results = g.search.query("title:Browser* OR body:automation~");


  g.log(`Encontradas ${results.length} correspondências:`);
  for (const r of results) {
    g.log(`- ${r.fields.title} (Score: ${r.score})`);
  }
}

6 métodos no total — veja a Referência da API para a lista completa.

Elasticsearch

Seção intitulada “Elasticsearch”

g.elasticsearch.* conecta-se a clusters Elasticsearch para ingestão de alto volume, gerenciamento de índices e pesquisas Query DSL brutas.

Diferentemente do índice Lucene local, o Elasticsearch exige um cluster externo, rodando localmente, via Docker ou no Elastic Cloud.

Formato da string de conexão (JSON):

As conexões são configuradas com segurança no painel Secrets pelo diálogo “Add Elasticsearch”. Internamente, isso armazena uma configuração JSON:

{
  "url": "http://localhost:9200",
  "username": "elastic",
  "password": "password"
}

Casos de uso:

  • Extrair conjuntos de dados massivos e ingeri-los com operações em lote de alta vazão.
  • Criar e gerenciar índices por código.
  • Pesquisar datasets grandes usando Elasticsearch Query DSL bruto.

Exemplo

Seção intitulada “Exemplo”
async function main() {
  const conn = "my-elastic"; // Nome da credencial de conexão


  // Verificar conexão
  const isUp = await g.elasticsearch.ping(conn);
  if (!isUp) return g.log("Conexão falhou");


  // Indexar documentos em lote com divisão automática
  const docs = [{ id: 1, title: "Laptop" }, { id: 2, title: "Mouse" }];
  const bulkRes = await g.elasticsearch.bulk(conn, "products", docs, 1000);
  g.log(`Indexados ${bulkRes.successful} de ${bulkRes.total}`);


  // Pesquisa Query DSL
  const searchRes = await g.elasticsearch.search(conn, "products", {
    query: { match_all: {} }
  });
  g.log(`Total de hits: ${searchRes.hits.total.value}`);
}

8 métodos no total — veja a Referência da API para a lista completa.

Segurança

Seção intitulada “Segurança”

Conexões com clusters Elasticsearch externos seguem o mesmo modelo de segurança das credenciais:

  • Scripts originados por MCP são bloqueados. Quando um agente de IA executa um script via MCP, todas as chamadas g.elasticsearch.* retornam erro. Isso impede a IA de acessar bancos externos por automação com scripts. Observação: o índice Lucene local g.search.* é acessível ao MCP.
  • Processos de trabalho herdam a origem de quem os iniciou. Se o MCP inicia um grupo de processos, esses processos também são bloqueados de acessar Elasticsearch externo.
  • Scripts iniciados pelo usuário têm acesso completo. Scripts executados via F5, gatilhos de eventos e processadores de fila podem usar todos os métodos.

Credenciais de conexão nunca são expostas por ferramentas MCP: a IA vê apenas o nome da credencial, não usuário nem senha.

Próximos passos

Seção intitulada “Próximos passos”