Busca de IA: a primitiva de busca para seus agentes

Todo agente precisa de busca: Agentes de codificação buscam milhões de arquivos em repositórios, ou agentes de suporte buscam tickets de clientes e documentos internos. Os casos de uso são diferentes, mas o problema subjacente é o mesmo: obter a informação certa para o modelo no momento certo.

Se você está construindo a busca por conta própria, precisa de um índice vetorial, um pipeline de indexação que analisa e divide seus documentos, e algo para manter o índice atualizado quando seus dados mudam. Se você também precisa de busca por palavras-chave, isso é um índice separado e lógica de fusão em cima. E se cada um de seus agentes precisa de seu próprio contexto pesquisável, você está configurando tudo isso por agente.

AI Search (anteriormente AutoRAG) é a primitiva de busca plug-and-play que você precisa. Você pode criar instâncias dinamicamente, fornecer seus dados e buscar — a partir de um Worker, do Agents SDK ou do Wrangler CLI. Aqui está o que estamos lançando:

• Busca híbrida. Habilite tanto correspondência semântica quanto por palavras-chave na mesma consulta. A busca vetorial e BM25 funcionam em paralelo e os resultados são fundidos. (A busca em nosso blog agora é alimentada pelo AI Search. Tente o ícone de lupa no canto superior direito.)

• Armazenamento e índice integrados. Novas instâncias vêm com seu próprio armazenamento e índice vetorial. Faça upload de arquivos diretamente para uma instância via API e eles serão indexados. Sem buckets R2 para configurar, sem fontes de dados externas para conectar primeiro. O novo ai_search_namespaces permite que você crie e exclua instâncias em tempo de execução a partir do seu Worker, para que você possa criar uma por agente, por cliente ou por idioma sem necessidade de reimplantação.

Agora, você também pode anexar metadados a documentos e usá-los para aumentar classificações no momento da consulta, e consultar várias instâncias em uma única chamada.

Agora, vamos ver o que isso significa na prática.

Vamos percorrer um agente de suporte que busca dois tipos de conhecimento: documentos de produtos compartilhados e histórico por cliente, como resoluções passadas. Os documentos do produto são grandes demais para caber em uma janela de contexto, e o histórico de cada cliente cresce a cada problema resolvido, então o agente precisa de recuperação para encontrar o que é relevante.

Veja como isso se parece com o AI Search e o Agents SDK. Comece criando um projeto:

npm create cloudflare@latest -- --template cloudflare/agents-starter

Primeiro, vincule um namespace do AI Search ao seu Worker:

// wrangler.jsonc 
{
  "ai_search_namespaces": [
    { "binding": "SUPPORT_KB", "namespace": "support" }
  ],
  "ai": { "binding": "AI" },
  "durable_objects": {
    "bindings": [
      { "name": "SupportAgent", "class_name": "SupportAgent" }
    ]
  }
}

Vamos supor que sua documentação de produto compartilhada esteja em um bucket R2 chamado product-doc. Você pode criar uma instância única do AI Search (chamada product-knowledge) apoiada pelo bucket no Painel do Cloudflare dentro do namespace support:

Essa é sua base de conhecimento compartilhada, os documentos que todos os agentes podem consultar.

Quando um cliente retorna com um novo problema, saber o que já foi tentado economiza tempo para todos. Você pode acompanhar isso criando uma instância do AI Search por cliente. Após cada problema resolvido, o agente salva um resumo do que deu errado e como foi corrigido. Com o tempo, isso constrói um registro pesquisável de resoluções passadas. Você pode criar instâncias dinamicamente usando a vinculação de namespace:

// crie uma instância por cliente quando eles aparecerem pela primeira vez 
await env.SUPPORT_KB.create({
  id: `customer-${customerId}`,
  index_method:{ keyword: true, vector: true }
});

Cada instância recebe seu próprio armazenamento integrado e índice vetorial — alimentados por R2 e Vectorize. A instância começa vazia e acumula contexto ao longo do tempo. Na próxima vez que o cliente voltar, tudo isso será pesquisável.

Veja como o namespace se parece após alguns clientes:

namespace: "support"
├── product-knowledge     (R2 como fonte, compartilhado entre todos os agentes)
├── customer-abc123       (armazenamento gerenciado, por cliente)
├── customer-def456       (armazenamento gerenciado, por cliente)
└── customer-ghi789       (armazenamento gerenciado, por cliente)

Agora o agente em si. Ele estende AIChatAgent do Agents SDK e define duas ferramentas. Estamos usando Kimi K2.5 como o LLM via Workers AI. O modelo decide quando chamar as ferramentas com base na conversa:

import { AIChatAgent, type OnChatMessageOptions } from "@cloudflare/ai-chat";
import { createWorkersAI } from "workers-ai-provider";
import { streamText, convertToModelMessages, tool, stepCountIs } from "ai";
import { routeAgentRequest } from "agents";
import { z } from "zod";

export class SupportAgent extends AIChatAgent<Env> {
  async onChatMessage(_onFinish: unknown, options?: OnChatMessageOptions) {
    // o cliente passa customerId no corpo da requisição
    // via sendMessage({ body: { customerId } }) do Agent SDK
    const customerId = options?.body?.customerId;

    // crie uma instância por cliente quando eles aparecerem pela primeira vez.
    // cada instância recebe seu próprio armazenamento e índice vetorial.
    if (customerId) {
      try {
        await this.env.SUPPORT_KB.create({
          id: `customer-${customerId}`,
          index_method: { keyword: true, vector: true }
        });
      } catch {
        // instância já existe
      }
    }

    const workersai = createWorkersAI({ binding: this.env.AI });

    const result = streamText({
      model: workersai("@cf/moonshotai/kimi-k2.5"),
      system: `Você é um agente de suporte. Use search_knowledge_base
        para encontrar documentos relevantes antes de responder. Os resultados da busca
        incluem tanto documentos de produtos quanto as resoluções passadas deste cliente — use-os para evitar repetir correções falhas
        e reconhecer problemas recorrentes. Quando o problema for resolvido, chame save_resolution antes de responder.`,
      // this.messages é todo o histórico da conversa, automaticamente
      // persistido pelo AIChatAgent em reconexões
      messages: await convertToModelMessages(this.messages),
      tools: {
        // ferramenta 1: buscar em documentos de produtos compartilhados E neste
        // histórico de resoluções passadas do cliente em uma única chamada
        search_knowledge_base: tool({
          description: "Buscar documentos de produtos e histórico do cliente",
          inputSchema: z.object({
            query: z.string().describe("A consulta de busca"),
          }),
          execute: async ({ query }) => {
            // sempre busque documentos de produtos;
            // inclua o histórico do cliente se disponível
            const instances = ["product-knowledge"];
            if (customerId) {
              instances.push(`customer-${customerId}`);
            }
            return await this.env.SUPPORT_KB.search({
              query: query,
              ai_search_options: {
                // priorizar documentos recentes sobre os mais antigos
                boost_