Dando ao Seu Assistente de IA Onyx Acesso à Web com a Bright Data

Neste tutorial, você aprenderá:

• O que é a plataforma de IA Onyx e o que ela oferece como assistente de pesquisa e IA.
• Por que estender o Onyx com recursos de descoberta web, extração de dados e capacidades de integração eleva seus agentes de IA ao próximo nível.
• Como conectar a Bright Data ao Onyx para esse fim, seja via MCP ou especificações OpenAPI.

Vamos começar!

Onyx: O Que É e Quais Recursos Oferece

Onyx é uma plataforma de busca empresarial e assistente de IA que se conecta aos documentos internos de uma empresa, aplicativos (como Slack, Drive, GitHub, etc.) e equipes para fornecer respostas instantâneas e contextuais. Tem uma natureza open-source (com mais de 18 mil estrelas no GitHub) e foi criado para ser auto-hospedável e totalmente transparente.

O Onyx se integra aos seus documentos, aplicativos e membros da equipe, oferecendo controle total sobre implantação, privacidade de dados e personalização. Ele se concentra em confiabilidade, segurança e extensibilidade, ajudando você a criar agentes de IA personalizados que realizam pesquisas aprofundadas, automatizam tarefas e acessam informações atualizadas. Tudo isso em uma única interface baseada na web.

Os principais recursos oferecidos pela plataforma incluem:

• Agentes personalizados: Crie agentes de IA com instruções, conhecimentos e ações exclusivas adaptadas aos seus fluxos de trabalho.
• Busca web e interna: Recupere informações atualizadas da web ou da base de conhecimento da sua organização usando busca híbrida, RAG e grafos de conhecimento gerados por IA.
• Conectores: Integre-se com mais de 40 aplicativos para extrair documentos, metadados e informações com controle de acesso.
• Pesquisa aprofundada: Realize buscas agênticas em múltiplas etapas para entregar respostas e insights detalhados.
• Ações e suporte a MCP: Permita que agentes interajam com sistemas externos e automatizem fluxos de trabalho.
• Interpretador de código: Execute scripts, analise dados, renderize gráficos e crie arquivos diretamente no chat.
• Geração de imagens: Crie imagens a partir de prompts do usuário dentro da plataforma.
• Ferramentas de colaboração: Compartilhe chats, colete feedback, acompanhe o uso e gerencie funções de usuários.
• Suporte flexível a LLM: Funciona com muitos LLMs, incluindo OpenAI, Anthropic, Gemini e modelos auto-hospedados como vLLM ou Ollama.
• Opções de implantação: Implante no Docker, Kubernetes, Terraform, provedores de nuvem ou ambientes totalmente isolados para segurança empresarial.

Descubra mais na documentação oficial.

Estendendo a Plataforma de IA Onyx com Recuperação de Dados Web, Busca e Capacidades de Interação

O Onyx é, sem dúvida, uma poderosa plataforma de IA. Ao mesmo tempo, como todos os sistemas baseados em LLM, seu conhecimento é fixo no momento em que o modelo foi treinado. Isso pode levar a respostas desatualizadas, alucinações ou lacunas quando seus agentes de IA precisam lidar com tarefas atuais do mundo real.

Os LLMs também não conseguem navegar nativamente na web ou interagir com sistemas externos, o que limita sua eficácia em fluxos de trabalho dinâmicos. Para superar isso, o Onyx suporta integrações com serviços externos por meio de servidores MCP, ações e ferramentas.

É aqui que a Bright Data entra em cena! Ao conectar o Onyx à Bright Data, seus agentes de IA ganham acesso a informações em tempo real, resultados de busca e dados estruturados de praticamente qualquer site.

Os principais produtos da Bright Data que você pode ativar para agentes Onyx incluem:

• API SERP: Colete resultados de motores de busca do Google, Bing e outros para embasar respostas informadas.
• API Web Unlocker: Acesse conteúdo HTML bruto ou Markdown de qualquer site, contornando CAPTCHAs e medidas anti-bot.
• APIs de Scraping de dados: Extraia dados estruturados de plataformas como Amazon, LinkedIn e Instagram.
• API de Crawl: Converta sites inteiros em conjuntos de dados estruturados para fluxos de trabalho de IA.
• API de Navegador: Controle programaticamente um navegador remoto para interação automatizada e desbloqueada em qualquer site.

O que diferencia esses serviços é a infraestrutura de scraping de nível empresarial da Bright Data. Construída sobre uma rede global de proxies com mais de 400 milhões de IPs em 195 países, ela suporta escalabilidade ilimitada mantendo 99,99% de uptime e 99,95% de taxa de sucesso.

Com essas integrações, os agentes Onyx não ficam mais limitados ao conhecimento estático. Eles podem explorar, recuperar e raciocinar com dados web ao vivo, além de interagir com sites para fornecer respostas precisas, contextuais e acionáveis.

Como Integrar a Bright Data ao Onyx

O Onyx suporta vários métodos de integração com provedores terceiros. Quando se trata da Bright Data, as opções são:

1. MCP: Conecte o Onyx ao servidor Web MCP da Bright Data (remotamente, pois o Onyx não suporta conexões MCP locais).
2. OpenAPI: Crie ações personalizadas no Onyx usando uma especificação OpenAPI 3.0 ou 3.1 dos produtos de API da Bright Data.

O método OpenAPI envolve mais configuração, mas oferece acesso direto aos serviços da Bright Data. Por outro lado, a abordagem Web MCP é mais simples para começar, fornecendo acesso a mais de 60 ferramentas com apenas uma configuração.

Nos capítulos dedicados passo a passo abaixo, você verá como implementar ambas as abordagens! Mas primeiro, vamos instalar e configurar o Onyx em sua máquina local.

Etapas Comuns: Primeiros Passos com o Onyx

Independentemente de você querer integrar a Bright Data ao Onyx via MCP ou OpenAPI, primeiro é necessário ter a solução instalada e em execução na sua máquina. Você também precisa ter uma conta de administrador.

Estas são as etapas preliminares que abordaremos nesta seção!

Pré-requisitos

Certifique-se de atender aos seguintes requisitos antes de seguir as instruções abaixo:

• Um sistema operacional Linux/macOS, ou Windows com Bash instalado (até o Git Bash é suficiente).
• Docker e Docker Compose instalados localmente, com o daemon do Docker em execução.
• Uma chave de API de um provedor de LLM suportado (aqui, usaremos uma chave de API da OpenAI).

Sua máquina também precisará atender aos requisitos de hardware para uma experiência tranquila:

• CPU: Pelo menos 4 vCPUs (recomendado: 8+ vCPUs).
• RAM: Pelo menos 10 GB (recomendado: 16+ GB).
• Armazenamento: Pelo menos 32 GB + ~2,5× espaço livre para dados indexados (ou 500 GB para organizações com menos de 5.000 usuários).

Etapa #1: Instalar o Onyx

Certifique-se de que o daemon do Docker está em execução. Em seguida, execute o seguinte comando no Bash para iniciar o script de instalação oficial do Onyx:

curl -fsSL https://raw.githubusercontent.com/onyx-dot-app/onyx/main/deployment/docker_compose/install.sh > install.sh && chmod +x install.sh && ./install.sh

Você deverá ver uma mensagem como esta:

Pressione Enter para continuar. O script de instalação do Onyx verificará se sua máquina atende aos pré-requisitos e guiará você pelo processo de instalação em 10 etapas.

Na Etapa 4, você será perguntado qual versão do Onyx deseja instalar:

Para a integração com a Bright Data, a versão Lite é suficiente. Portanto, digite 1 ou simplesmente pressione Enter (pois a opção padrão é 1). Continue com as opções padrão até que as imagens Docker sejam baixadas, configuradas e inicializadas.

Se tudo funcionou conforme esperado, você deverá ver:

Fantástico! O Onyx foi instalado localmente e está acessível em http://localhost na sua máquina.

Etapa #2: Criar uma Conta de Administrador

Para administrar o Onyx, você deve criar uma conta de administrador. Para isso, acesse http://localhost no seu navegador. Você deverá ver o seguinte formulário:

Crie uma conta e faça login. Você chegará ao painel do Onyx:

Aqui, você tem acesso a todos os recursos do Onyx. Em particular, no Painel de Administração, você pode configurar a integração com a Bright Data, seja via MCP ou Ferramentas OpenAPI.

Tenha em mente que a configuração inicial ainda não está completa, pois você ainda precisa conectar o Onyx ao LLM escolhido. É o que você fará na próxima etapa!

Etapa #3: Concluir a Configuração Conectando a um LLM

Para concluir a configuração, pressione o botão “Let’s Go”:

Você será solicitado a inserir seu nome. Digite-o e clique em “Next”. Em seguida, será solicitado que configure a integração com o LLM.

Observação: Abaixo, você verá como configurar um modelo OpenAI. Se planeja usar outro LLM suportado, pressione o cartão do provedor e siga o assistente.

Neste caso, selecione a opção “GPT” no cartão da OpenAI:

Cole sua chave de API da OpenAI e configure o modelo (ex.: gpt-5-mini):

Pressione “Connect”, e você deverá ver que o Onyx se conectou com sucesso ao provedor de LLM selecionado:

Por fim, prossiga com a última etapa da configuração e clique em “Finish Setup”:

Incrível! Agora você pode começar a conversar e interagir com o modelo LLM configurado no Onyx. Antes de começar, prossiga com a configuração da integração com a Bright Data!

Abordagem #1: Conectar a Bright Data ao Onyx via Web MCP

As etapas a seguir guiarão você pelo processo de integração da Bright Data ao Onyx por meio de seu servidor Web MCP remoto.

Pré-requisitos

Para seguir esta seção, você precisa de:

• Uma conta Bright Data com uma chave de API configurada.
• Familiaridade com como o MCP funciona.
• Conhecimento das ferramentas expostas pelo servidor Web MCP da Bright Data.

Siga os links acima para mais orientações e instruções.

Etapa #4: Adicionar o Servidor Web MCP

Para conectar o Web MCP da Bright Data ao Onyx, navegue até a página “MCP Actions” no Painel de Administração:

Clique em “Add MCP Server” para criar uma nova integração. Um modal de configuração aparecerá. Configure-o da seguinte forma:

• Server Name: Bright Data Web MCP
• Description: O Web MCP da Bright Data oferece aos seus agentes de IA acesso em tempo real e confiável a dados públicos da web por meio de ferramentas de scraping e busca, além de habilitar interações web em navegadores remotos.
• MCP Server URL: https://mcp.brightdata.com/mcp?token=<SEU_TOKEN_DE_API_BRIGHT_DATA>&pro=1

Tenha em mente que o Onyx suporta apenas servidores MCP remotos. Neste caso, você está configurando o Web MCP da Bright Data via protocolo SSE.

Para autenticar solicitações à sua conta Bright Data, você deve incluir sua chave de API no parâmetro de consulta token da URL. O parâmetro &pro=1 é opcional e ativa o modo Pro. Isso fornece acesso a todas as ferramentas Web MCP, incluindo ferramentas de interação web e feeds de dados diretos de muitos domínios suportados.

Se preferir usar o nível gratuito (modo Rapid), que inclui apenas scrape_as_markdown e search_engine (e suas versões em lote), defina esta URL em vez disso:

https://mcp.brightdata.com/mcp?token=<SEU_TOKEN_DE_API_BRIGHT_DATA>

Agora clique em “Save Changes” para continuar. Você verá então o modal de configurações de autenticação.

Como a autenticação é tratada via chave de API na URL, defina o campo “Authentication Method” como “None” e clique em “Connect”:

Na entrada “Bright Data Web MCP”, você notará uma mensagem “Fetching tools…”. Logo após, as ferramentas disponíveis (60+ no modo Pro, ou 4 no modo Rapid) aparecerão:

Isso confirma que o Onyx se conectou com sucesso ao servidor Web MCP remoto e pode acessar suas ferramentas. Nesta interface, você também pode escolher quais ferramentas ativar ou desativar.

Missão cumprida! A Bright Data agora está expondo suas capacidades de busca web, recuperação de dados e interação à sua instância do Onyx via MCP.

Etapa #5: Ativar a Integração Web MCP

Por padrão, os servidores MCP configurados ficam desabilitados no chat do Onyx. Para ativá-los e dar ao LLM subjacente acesso às ferramentas da Bright Data, vá à página “Chat Preferences” no Painel de Administração.

Role para baixo até a seção “Actions & Tools” e certifique-se de ativar a entrada “Bright Data Web MCP”:

Ótimo! O LLM configurado no Onyx (gpt-5-mini, neste caso) agora pode utilizar as ferramentas da Bright Data disponíveis via Web MCP.

Etapa #6: Testar a Integração

De volta à interface de chat do Onyx, tente executar um prompt como este:

Retrieve company information from the following Crunchbase page:
"https://www.crunchbase.com/organization/browser-use"

Next, search for recent news and opinions about the company. Select the 3–4 most relevant sources, including news articles and Reddit discussions, to capture both updates and public sentiment.

Generate a structured report including:
1. Company overview and key details (from Crunchbase)
2. Summary of recent news
3. Analysis of public sentiment and opinions from online sources

Isso é algo que um LLM comum não consegue fazer por padrão, pois requer acesso a ferramentas de scraping de dados e busca. Em particular, o comportamento esperado é que o LLM:

1. Chame as ferramentas de scraping do Crunchbase disponíveis no modo Pro (ou scrape_as_markdown no modo Rapid).
2. Use a ferramenta search_engine (ou sua variante em lote) para recuperar resultados de busca do Google.
3. Extraia o conteúdo das páginas relevantes via scrape_as_markdown (ou sua variante em lote).
4. Agregue todos os dados coletados em um relatório estruturado.

Execute o prompt e você deverá obter:

O GIF acima está acelerado, mas mostra exatamente o processo descrito anteriormente. Isso confirma que a integração da Bright Data no Onyx está funcionando corretamente!

Para explorar mais, expanda o dropdown do plano para ver todas as etapas realizadas pelo agente:

Ao percorrer o plano, você pode observar que o agente:

1. Chamou a ferramenta web_data_crunchbase_company (disponível no modo Pro) para recuperar dados JSON estruturados da URL do Crunchbase.
2. Executa consultas de busca relevantes em paralelo usando a ferramenta search_engine_batch (a versão em lote de search_engine).
3. Seleciona os resultados mais relevantes e extrai seu conteúdo via scrape_batch (a versão em lote de scrape_as_markdown).

Confira um trecho do relatório gerado:

O resultado contém insights de alta qualidade baseados em dados, possibilitando uma avaliação verdadeiramente profissional da empresa.

E este é apenas um exemplo. Muitos outros casos de uso são suportados pela Bright Data por meio de seu servidor Web MCP!

Abordagem #2: Conectar Ferramentas Bright Data ao Onyx via Especificações OpenAPI

Como método alternativo de integração ao visto anteriormente, conecte as ferramentas da Bright Data no Onyx por meio de ações personalizadas definidas usando especificações OpenAPI.

Observação: As etapas abaixo focam na integração do Web Unlocker e da API SERP da Bright Data, mas podem ser facilmente adaptadas a outras soluções da Bright Data baseadas em API.

Pré-requisitos

Antes de seguir as instruções abaixo, você deve ter uma conta Bright Data com as zonas Web Unlocker e API SERP configuradas, além de uma chave de API. Uma compreensão básica de especificações OpenAPI também é útil.

Para configurar as zonas Bright Data necessárias, siga as instruções abaixo. Alternativamente, para orientações mais detalhadas, consulte estas páginas de documentação:

• Como Começar com a API SERP
• Guia de Início Rápido para a API Web Unlocker da Bright Data

Se você não tem uma conta Bright Data, crie uma nova. Se já tiver, basta fazer login. Acesse seu painel de controle, navegue até a página “Proxies & Scraping” e explore a tabela “My Zones”:

Se a tabela já inclui uma zona Web Unlocker API (ex.: web_unlocker) e uma zona API SERP (ex.: serp_api), você está pronto. Essas duas zonas serão usadas para conectar ao Web Unlocker e aos serviços de API SERP via ferramentas OpenAPI personalizadas.

Se alguma zona estiver faltando, crie-a. Role até os cartões “Unblocker API” e “SERP API”, depois pressione “Create zone”. Siga o assistente para adicionar a zona:

Certifique-se de anotar os nomes que você atribui a ambas as zonas, pois você precisará deles nas próximas etapas. Por fim, gere sua chave de API da Bright Data e guarde-a em um local seguro.

Etapa #4: Adicionar a Ação OpenAPI do Web Unlocker

Para adicionar uma nova ação, abra o Painel de Administração e navegue até a página “OpenAPI Actions”. Em seguida, clique no botão “Add OpenAPI Action”:

Você será solicitado a fornecer a definição do esquema OpenAPI. Você pode copiar a versão JSON do esquema do Web Unlocker do artigo de especificações OpenAPI da Bright Data.

Importante: A única alteração que você precisa fazer na especificação JSON é definir um valor padrão para o campo zone. Este valor deve corresponder ao nome da zona Web Unlocker API que você definiu anteriormente. Em detalhes, essa seção deve ficar assim:

{
  // ...
  "properties": {
    "zone": {
      "type": "string",
      "description": "Your Web Unlocker zone name.",
      "default": "<NOME_DA_SUA_ZONA_WEB_UNLOCKER_BRIGHT_DATA> // ex., "web_unlocker"
    }
  }
  // ...
}

Isso é necessário porque o Onyx não fornece um mecanismo para definir valores padrão para campos do corpo da solicitação em tempo de execução. Portanto, você deve especificar um valor padrão para os campos obrigatórios.

Clique em “Add Action”, e você será solicitado a configurar o método de autenticação. Selecione “Custom Authentication Header” e defina-o da seguinte forma:

• Header: Authorization
• Value: Bearer <SUA_CHAVE_DE_API_BRIGHT_DATA>

Observação: Bearer <SUA_CHAVE_DE_API_BRIGHT_DATA> é o formato usado pela API da Bright Data para autenticação via chave de API.

Clique em “Connect” para confirmar. A API Web Unlocker da Bright Data agora estará autenticada para sua conta e disponível como ferramenta no Onyx. Muito bem!

Etapa #5: Adicionar a Ação OpenAPI da API SERP

Repita a etapa anterior, mas adapte-a à especificação JSON da API SERP. Certifique-se de definir o valor padrão do campo zone no corpo da solicitação com o nome da sua zona API SERP na conta Bright Data.

Uma vez adicionada, a seção OpenAPI Actions deverá exibir ambas as ferramentas:

Excelente! As ferramentas Web Unlocker e API SERP da Bright Data agora estão disponíveis no Onyx.

Etapa #6: Ativar as Ferramentas OpenAPI

Por padrão, as ferramentas OpenAPI ficam desabilitadas no chat do Onyx. Para ativá-las, vá à página “Chat Preferences” no Painel de Administração e ative as ferramentas OpenAPI:

Ótimo! As ferramentas OpenAPI alimentadas pela Bright Data agora podem ser chamadas pelo LLM no Onyx.

Etapa #7: Testar a Integração

Para verificar se o LLM no Onyx consegue chamar automaticamente as ferramentas da Bright Data, tente um prompt como este:

Search for the latest stock market news on Google. Select the top 3 most relevant articles, extract their content in Markdown, and generate a concise summary report highlighting the key insights for today.

Isso representa um típico padrão de busca e extração que um agente pode usar para buscar informações contextuais, atualizadas e verificáveis da web. Um LLM comum não consegue fazer isso por padrão, pois requer tanto capacidades de busca web quanto de scraping de dados.

O comportamento esperado é que o LLM:

1. Chame a API SERP para buscar notícias do mercado financeiro.
2. Extraia os principais resultados usando a API Web Unlocker.

Execute o prompt e você deverá ver algo assim:

Se tudo funcionar corretamente, você notará que o LLM chamou a ferramenta API SERP, selecionou os principais artigos de notícias e extraiu seu conteúdo com a API Web Unlocker conforme previsto.

Et voilà! Isso confirma que a integração está funcionando. A Bright Data agora está totalmente disponível no Onyx, possibilitando uma experiência de chat turbinada.

Conclusão

Neste artigo, você aprendeu o que é o Onyx e o que ele oferece como plataforma de busca e assistente de IA. Você também viu suas limitações devido à sua natureza baseada em LLM e como abordá-las usando integrações da Bright Data.

Como destacado, a Bright Data permite que os agentes acessem dados web ao vivo para respostas mais precisas e contextuais. No Onyx, isso pode ser feito via Web MCP ou por meio de especificações OpenAPI para integrar diretamente os produtos da Bright Data.

Para estender ainda mais as funcionalidades, conecte os agentes Onyx ao conjunto completo de serviços da Bright Data para IA.

Crie uma conta Bright Data gratuitamente hoje e comece a integrar nossas soluções de dados web!