이 튜토리얼에서 배울 내용:
- Onyx AI 플랫폼이 무엇이며 검색 및 AI 어시스턴트로서 어떤 기능을 제공하는지.
- 웹 검색, 데이터 추출 및 통합 기능으로 Onyx를 확장하면 AI 에이전트가 한 단계 더 발전하는 이유.
- MCP 또는 OpenAPI 사양을 통해 Bright Data를 Onyx에 연결하는 방법.
시작해봅시다!
Onyx: 정의와 제공 기능
Onyx는 회사의 내부 문서, 앱(Slack, Drive, GitHub 등), 직원들과 연결되어 즉각적이고 맥락에 맞는 답변을 제공하는 엔터프라이즈 검색 및 AI 어시스턴트 플랫폼입니다. 오픈 소스(GitHub 별 18k+)로, 자체 호스팅과 완전한 투명성을 갖추도록 설계되었습니다.

Onyx는 문서, 앱, 팀원과 통합되며 배포, 데이터 프라이버시, 커스터마이징에 대한 완전한 제어권을 제공합니다. 신뢰성, 보안, 확장성에 초점을 맞춰 심층 리서치, 작업 자동화, 최신 정보 접근이 가능한 맞춤형 AI 에이전트를 만들 수 있습니다. 이 모든 것이 단일 웹 기반 인터페이스에서 가능합니다.
플랫폼의 주요 기능은 다음과 같습니다:
- 커스텀 에이전트: 워크플로에 맞는 고유한 지침, 지식, 액션을 갖춘 AI 에이전트를 구축합니다.
- 웹 및 내부 검색: 하이브리드 검색, RAG, AI 생성 지식 그래프를 사용하여 웹이나 조직의 지식 베이스에서 최신 정보를 검색합니다.
- 커넥터: 40개 이상의 앱과 통합하여 문서, 메타데이터, 접근 제어 정보를 가져옵니다.
- 심층 리서치: 다단계 에이전트 검색을 수행하여 심층적인 답변과 인사이트를 제공합니다.
- 액션 및 MCP 지원: 에이전트가 외부 시스템과 상호작용하고 워크플로를 자동화할 수 있습니다.
- 코드 인터프리터: 채팅에서 직접 스크립트 실행, 데이터 분석, 그래프 렌더링, 파일 생성이 가능합니다.
- 이미지 생성: 플랫폼 내에서 사용자 프롬프트로 이미지를 생성합니다.
- 협업 도구: 채팅 공유, 피드백 수집, 사용량 추적, 사용자 역할 관리가 가능합니다.
- 유연한 LLM 지원: OpenAI, Anthropic, Gemini, vLLM 또는 Ollama 같은 자체 호스팅 모델을 포함한 다양한 LLM과 함께 작동합니다.
- 배포 옵션: Docker, Kubernetes, Terraform, 클라우드 제공업체, 또는 엔터프라이즈 보안을 위한 완전 에어갭 환경에 배포할 수 있습니다.
공식 문서에서 더 자세히 알아보세요.
웹 데이터 검색, 탐색 및 상호작용 기능으로 Onyx AI 플랫폼 확장하기
Onyx는 의심할 여지 없이 강력한 AI 플랫폼입니다. 동시에 모든 LLM 기반 시스템과 마찬가지로, 모델 학습 시점에 지식이 고정됩니다. 이로 인해 AI 에이전트가 현재의 실제 작업을 처리할 때 오래된 응답, 환각, 또는 공백이 발생할 수 있습니다.
LLM은 기본적으로 웹을 탐색하거나 외부 시스템과 상호작용할 수 없어 동적 워크플로에서의 효과가 제한됩니다. 이를 극복하기 위해 Onyx는 MCP 서버, 액션, 도구를 통해 외부 서비스와의 통합을 지원합니다.
바로 여기서 Bright Data가 등장합니다! Onyx를 Bright Data에 연결하면 AI 에이전트가 거의 모든 웹사이트에서 실시간 정보, 검색 결과, 구조화된 데이터에 접근할 수 있습니다.
Onyx 에이전트에 활성화할 수 있는 주요 Bright Data 제품은 다음과 같습니다:
- SERP API: Google, Bing 등의 검색 엔진 결과를 수집하여 정보에 기반한 응답을 제공합니다.
- Web Unlocker API: CAPTCHA 및 안티봇 조치를 우회하여 모든 사이트에서 원시 HTML 또는 Markdown 콘텐츠에 접근합니다.
- 웹 스크래핑 API: Amazon, LinkedIn, Instagram 같은 플랫폼에서 구조화된 데이터를 추출합니다.
- Crawl API: 전체 웹사이트를 다운스트림 AI 워크플로를 위한 구조화된 데이터셋으로 변환합니다.
- Browser API: 모든 웹사이트에서 자동화된 잠금 해제 상호작용을 위해 원격 브라우저를 프로그래밍 방식으로 제어합니다.
이 서비스들의 차별점은 Bright Data의 엔터프라이즈급 인프라입니다. 195개국에 걸쳐 4억 개 이상의 IP로 구성된 글로벌 프록시 네트워크를 기반으로 99.99% 가동 시간과 99.95% 성공률을 유지하면서 무제한 확장성을 지원합니다.
이러한 통합을 통해 Onyx 에이전트는 더 이상 정적 지식에 국한되지 않습니다. 실시간 웹 데이터를 탐색, 검색, 추론하고 웹사이트와 상호작용하여 정확하고 맥락에 맞는 실행 가능한 응답을 제공할 수 있습니다.
Bright Data를 Onyx에 통합하는 방법
Onyx는 서드파티 제공업체와의 여러 통합 방법을 지원합니다. Bright Data의 경우 옵션은 다음과 같습니다:
- MCP: Onyx를 Bright Data Web MCP 서버에 연결합니다(Onyx는 로컬 MCP 연결을 지원하지 않으므로 원격으로 연결).
- OpenAPI: Bright Data API 제품의 OpenAPI 3.0 또는 3.1 사양을 사용하여 Onyx에서 커스텀 액션을 생성합니다.
OpenAPI 방법은 더 많은 구성이 필요하지만 Bright Data 서비스에 직접 액세스할 수 있습니다. 반면 Web MCP 방식은 단일 설정으로 60개 이상의 도구에 액세스할 수 있어 시작하기가 더 간단합니다.
아래의 단계별 챕터에서 두 가지 접근 방식을 모두 구현하는 방법을 확인할 수 있습니다! 하지만 먼저 로컬 머신에 Onyx를 설치하고 설정해봅시다.
공통 단계: Onyx 시작하기
MCP나 OpenAPI를 통해 Bright Data를 Onyx에 통합하려면 먼저 솔루션을 머신에 설치하고 실행해야 합니다. 관리자 계정도 필요합니다.
이 섹션에서 다룰 사전 준비 단계입니다!
사전 요구 사항
아래 지침을 따르기 전에 다음 요구 사항을 충족하는지 확인하세요:
- Linux/macOS 운영 체제, 또는 Bash가 설치된 Windows(Git Bash도 충분합니다).
- 로컬에 Docker 및 Docker Compose가 설치되어 있고 Docker 데몬이 실행 중이어야 합니다.
- 지원되는 LLM 제공업체의 API 키(여기서는 OpenAI API 키를 사용합니다).
원활한 경험을 위해 머신이 다음 하드웨어 요구 사항을 충족해야 합니다:
- CPU: 최소 4 vCPU(권장: 8+ vCPU).
- RAM: 최소 10GB(권장: 16+GB).
- 스토리지: 최소 32GB + 인덱싱된 데이터의 약 2.5배 여유 공간(또는 사용자 5,000명 미만의 조직의 경우 500GB).
1단계: Onyx 설치
Docker 데몬이 실행 중인지 확인하세요. 그런 다음 Bash에서 다음 명령을 실행하여 공식 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
다음과 같은 메시지가 표시됩니다:

Enter를 눌러 계속합니다. Onyx 설치 스크립트는 머신이 사전 요구 사항을 충족하는지 확인하고 10단계로 설치 과정을 안내합니다.
4단계에서 설치할 Onyx 버전을 선택하라는 메시지가 표시됩니다:

Bright Data 통합에는 Lite 버전으로 충분합니다. 따라서 1을 입력하거나 그냥 Enter를 누르세요(기본 옵션이 1입니다). Docker 이미지가 다운로드, 구성, 실행될 때까지 기본 옵션으로 계속 진행합니다.
모든 것이 정상적으로 작동했다면 다음이 표시됩니다:

훌륭합니다! Onyx가 이제 로컬에 설치되었으며 머신의 http://localhost에서 접근할 수 있습니다.
2단계: 관리자 계정 만들기
Onyx를 관리하려면 관리자 계정을 만들어야 합니다. 브라우저에서 http://localhost을 방문하세요. 다음 양식이 표시됩니다:

계정을 만들고 로그인합니다. 그러면 Onyx 대시보드에 도달합니다:

여기서 모든 Onyx 기능에 액세스할 수 있습니다. 특히 관리자 패널에서 MCP 또는 OpenAPI 도구를 통해 Bright Data 통합을 설정할 수 있습니다.
선택한 LLM에 Onyx를 연결해야 하므로 초기 구성이 아직 완료되지 않았다는 점을 기억하세요. 다음 단계에서 이 작업을 수행합니다!
3단계: LLM 연결로 설정 완료하기
구성을 완료하려면 “시작하기” 버튼을 누르세요:

이름을 입력하라는 메시지가 표시됩니다. 이름을 입력하고 “다음”을 클릭합니다. 그러면 LLM 통합 구성을 요청받습니다.
참고: 아래에서는 OpenAI 모델을 구성하는 방법을 보여드립니다. 다른 지원 LLM을 사용하려면 제공업체 카드를 누르고 마법사를 따르세요.
이 경우 OpenAI 카드에서 “GPT” 옵션을 선택합니다:

OpenAI API 키를 붙여넣고 모델을 구성합니다(예: gpt-5-mini):

“연결”을 누르면 Onyx가 선택한 LLM 제공업체에 성공적으로 연결되었음을 확인할 수 있습니다:

마지막으로 구성의 마지막 단계를 진행하고 “설정 완료”를 클릭합니다:

훌륭합니다! 이제 Onyx에서 구성된 LLM 모델과 채팅하고 상호작용을 시작할 수 있습니다. 시작하기 전에 Bright Data 통합 설정을 진행하세요!
접근 방식 #1: Web MCP를 통해 Bright Data를 Onyx에 연결하기
다음 단계는 원격 Web MCP 서버를 통해 Bright Data를 Onyx에 통합하는 과정을 안내합니다.
사전 요구 사항
이 섹션을 따르려면 다음이 필요합니다:
- API 키가 구성된 Bright Data 계정.
- MCP 작동 방식에 대한 이해.
- Bright Data Web MCP 서버가 노출하는 도구에 대한 지식.
더 많은 안내와 지침은 위의 링크를 따르세요.
4단계: Web MCP 서버 추가하기
Bright Data의 Web MCP를 Onyx에 연결하려면 관리자 패널의 “MCP 액션” 페이지로 이동하세요:

“MCP 서버 추가”를 클릭하여 새 통합을 만듭니다. 구성 모달이 나타납니다. 다음과 같이 구성하세요:
- 서버 이름:
Bright Data Web MCP - 설명:
Bright Data의 Web MCP는 스크래핑 도구와 검색을 통해 AI 에이전트에게 공개 웹 데이터에 대한 실시간 신뢰할 수 있는 액세스를 제공하며, 원격 브라우저에서 웹 상호작용도 가능하게 합니다. - MCP 서버 URL:
https://mcp.brightdata.com/mcp?token=<YOUR_BRIGHT_DATA_API_TOKEN>&pro=1

Onyx는 원격 MCP 서버만 지원한다는 점을 기억하세요. 이 경우 SSE 프로토콜을 통해 Bright Data Web MCP를 구성하는 것입니다.
Bright Data 계정에 대한 요청을 인증하려면 URL의 token 쿼리 매개변수에 API 키를 포함해야 합니다. &pro=1 매개변수는 선택 사항이며 Pro 모드를 활성화합니다. 이는 웹 상호작용 도구와 많은 지원 도메인의 직접 데이터 피드를 포함한 모든 Web MCP 도구에 대한 액세스를 제공합니다.
scrape_as_markdown 및 search_engine(및 배치 버전)만 포함하는 무료 티어(Rapid 모드)를 사용하려면 대신 이 URL을 설정하세요:
https://mcp.brightdata.com/mcp?token=<YOUR_BRIGHT_DATA_API_TOKEN>
이제 “변경 사항 저장”을 클릭하여 계속합니다. 그러면 인증 설정 모달이 표시됩니다.
URL의 API 키를 통해 인증이 처리되므로 “인증 방법” 필드를 “없음”으로 설정하고 “연결”을 클릭합니다:

“Bright Data Web MCP” 항목에서 “도구 가져오는 중…” 메시지가 표시됩니다. 잠시 후 사용 가능한 도구(Pro 모드에서 60개 이상, Rapid 모드에서 4개)가 나타납니다:

이는 Onyx가 원격 Web MCP 서버에 성공적으로 연결되었으며 해당 도구에 액세스할 수 있음을 확인합니다. 이 인터페이스에서 활성화하거나 비활성화할 도구를 선택할 수도 있습니다.
임무 완료! Bright Data가 이제 MCP를 통해 Onyx 인스턴스에 웹 검색, 데이터 검색 및 상호작용 기능을 노출하고 있습니다.
5단계: Web MCP 통합 활성화하기
기본적으로 구성된 MCP 서버는 Onyx 채팅에서 비활성화되어 있습니다. 이를 활성화하고 기본 LLM이 Bright Data 도구에 액세스할 수 있도록 하려면 관리자 패널의 “채팅 기본 설정” 페이지로 이동합니다.
“액션 및 도구” 섹션으로 스크롤하여 “Bright Data Web MCP” 항목을 토글하여 활성화하세요:

훌륭합니다! Onyx에 구성된 LLM(gpt-5-mini)이 이제 Web MCP를 통해 사용 가능한 Bright Data 도구를 활용할 수 있습니다.
6단계: 통합 테스트하기
Onyx 채팅 인터페이스로 돌아가 다음과 같은 프롬프트를 실행해 보세요:
다음 Crunchbase 페이지에서 회사 정보를 검색하세요:
"https://www.crunchbase.com/organization/browser-use"
다음으로 회사에 대한 최근 뉴스와 의견을 검색하세요. 최신 업데이트와 대중 감정을 모두 파악하기 위해 뉴스 기사와 Reddit 토론을 포함한 3~4개의 가장 관련성 높은 출처를 선택하세요.
다음을 포함한 구조화된 보고서를 생성하세요:
1. 회사 개요 및 주요 세부 정보 (Crunchbase에서)
2. 최근 뉴스 요약
3. 온라인 출처의 대중 감정 및 의견 분석
이는 웹 스크래핑 및 검색 도구에 대한 액세스가 필요하므로 일반 LLM이 기본적으로 수행할 수 없는 작업입니다. 특히 LLM의 예상 동작은 다음과 같습니다:
- Pro 모드에서 사용 가능한 Crunchbase 스크래핑 도구(또는 Rapid 모드에서
scrape_as_markdown)를 호출합니다. search_engine도구(또는 배치 변형)를 사용하여 Google 검색 결과를 검색합니다.scrape_as_markdown(또는 배치 변형)을 통해 관련 페이지의 콘텐츠를 스크래핑합니다.- 수집된 모든 데이터를 구조화된 보고서로 집계합니다.
프롬프트를 실행하면 다음과 같은 결과가 표시됩니다:

위의 GIF는 빠르게 재생되지만 앞서 설명한 프로세스를 정확히 보여줍니다. 이는 Onyx에서 Bright Data 통합이 올바르게 작동하고 있음을 확인합니다!
더 탐색하려면 플랜 드롭다운을 펼쳐 에이전트가 수행한 모든 단계를 확인하세요:

스크롤하면 에이전트가 다음을 수행했음을 확인할 수 있습니다:
- Crunchbase URL에서 구조화된 JSON 데이터를 검색하기 위해
web_data_crunchbase_company도구(Pro 모드에서 사용 가능)를 호출했습니다. search_engine_batch도구(search_engine의 배치 버전)를 사용하여 관련 검색 쿼리를 병렬로 수행합니다.- 가장 관련성 높은 결과를 선택하고
scrape_batch(scrape_as_markdown의 배치 버전)를 통해 콘텐츠를 추출합니다.
생성된 보고서의 스니펫을 살펴보세요:

출력에는 고품질의 데이터 기반 인사이트가 포함되어 있어 회사에 대한 진정한 전문적 평가가 가능합니다.
이것은 단지 하나의 예시에 불과합니다. Bright Data는 Web MCP 서버를 통해 다양한 사용 사례를 지원합니다!
접근 방식 #2: OpenAPI 사양을 통해 Bright Data 도구를 Onyx에 연결하기
앞서 살펴본 통합 방법의 대안으로, OpenAPI 사양을 사용하여 정의된 커스텀 액션을 통해 Onyx에서 Bright Data 도구를 연결합니다.
참고: 아래 단계는 Bright Data의 Web Unlocker와 SERP API 통합에 초점을 맞추지만, 다른 API 기반 Bright Data 솔루션에도 쉽게 적용할 수 있습니다.
사전 요구 사항
아래 지침을 따르기 전에 Web Unlocker 및 SERP API 존이 설정된 Bright Data 계정과 API 키가 있어야 합니다. OpenAPI 사양에 대한 기본적인 이해도 도움이 됩니다.
필요한 Bright Data 존을 설정하려면 아래 지침을 따르세요. 더 자세한 안내는 다음 문서 페이지를 참조하세요:
Bright Data 계정이 없다면 새 계정을 만드세요. 이미 있다면 로그인하세요. 제어판으로 이동하여 “프록시 및 스크래핑” 페이지로 이동하고 “내 존” 테이블을 탐색합니다:

테이블에 이미 Web Unlocker API 존(예: web_unlocker)과 SERP API 존(예: serp_api)이 포함되어 있다면 준비가 된 것입니다. 이 두 존은 커스텀 OpenAPI 도구를 통해 Web Unlocker 및 SERP API 서비스에 연결하는 데 사용됩니다.
존이 없다면 만드세요. “Unblocker API” 및 “SERP API” 카드로 스크롤하여 “존 만들기”를 누르세요. 마법사를 따라 존을 추가합니다:

다음 단계에서 필요하므로 두 존에 지정한 이름을 반드시 기록해 두세요. 마지막으로 Bright Data API 키를 생성하여 안전한 곳에 보관하세요.
4단계: Web Unlocker OpenAPI 액션 추가하기
새 액션을 추가하려면 관리자 패널을 열고 “OpenAPI 액션” 페이지로 이동합니다. 그런 다음 “OpenAPI 액션 추가” 버튼을 클릭합니다:

OpenAPI 스키마 정의를 제공하라는 메시지가 표시됩니다. Bright Data OpenAPI 사양 문서에서 Web Unlocker 스키마의 JSON 버전을 복사할 수 있습니다.
중요: JSON 사양에서 해야 할 유일한 변경은 zone 필드의 기본값을 설정하는 것입니다. 이 값은 앞서 정의한 Web Unlocker API 존 이름과 일치해야 합니다. 자세히 말하면, 해당 섹션은 다음과 같아야 합니다:
{
// ...
"properties": {
"zone": {
"type": "string",
"description": "Web Unlocker 존 이름.",
"default": "<YOUR_BRIGHT_DATA_WEB_UNLOCKER_API_ZONE_NAME> // 예: "web_unlocker"
}
}
// ...
}
Onyx는 런타임에 요청 본문 필드의 기본값을 설정하는 메커니즘을 제공하지 않기 때문에 이 작업이 필요합니다. 따라서 필수 필드의 기본값을 지정해야 합니다.

“액션 추가”를 클릭하면 인증 방법을 구성하라는 메시지가 표시됩니다. “커스텀 인증 헤더”를 선택하고 다음과 같이 정의합니다:
- 헤더:
Authorization - 값:
Bearer <YOUR_BRIGHT_DATA_API_KEY>

참고: Bearer <YOUR_BRIGHT_DATA_API_KEY>는 Bright Data API가 API 키를 통한 인증에 사용하는 형식입니다.
“연결”을 클릭하여 확인합니다. Bright Data Web Unlocker API가 이제 계정에 대해 인증되었으며 Onyx에서 도구로 사용할 수 있습니다. 잘 하셨습니다!
5단계: SERP API OpenAPI 액션 추가하기
이전 단계를 반복하되 SERP API의 JSON 사양에 맞게 조정합니다. Bright Data 계정의 SERP API 존 이름으로 요청 본문의 zone 필드 기본값을 설정해야 합니다.
추가되면 OpenAPI 액션 섹션에 두 도구가 모두 표시됩니다:

훌륭합니다! Bright Data Web Unlocker와 SERP API 도구가 이제 Onyx에서 사용 가능합니다.
6단계: OpenAPI 도구 활성화하기
기본적으로 OpenAPI 도구는 Onyx 채팅에서 비활성화되어 있습니다. 이를 활성화하려면 관리자 패널의 “채팅 기본 설정” 페이지로 이동하여 OpenAPI 도구를 켜세요:

좋습니다! Bright Data 기반 OpenAPI 도구를 이제 Onyx의 LLM이 호출할 수 있습니다.
7단계: 통합 테스트하기
Onyx의 LLM이 Bright Data 도구를 자동으로 호출할 수 있는지 확인하려면 다음과 같은 프롬프트를 사용해 보세요:
Google에서 최신 주식 시장 뉴스를 검색하세요. 가장 관련성 높은 상위 3개 기사를 선택하고 Markdown으로 콘텐츠를 추출하여 오늘의 주요 인사이트를 강조하는 간결한 요약 보고서를 생성하세요.
이는 에이전트가 웹에서 맥락에 맞고 신선하며 검증 가능한 정보를 가져오기 위해 사용할 수 있는 일반적인 검색-추출 패턴을 나타냅니다. 일반 LLM은 웹 검색과 스크래핑 기능이 모두 필요하므로 기본적으로 이를 수행할 수 없습니다.
예상 동작은 LLM이 다음을 수행하는 것입니다:
- SERP API를 호출하여 주식 시장 뉴스를 검색합니다.
- Web Unlocker API를 사용하여 상위 결과를 추출합니다.
프롬프트를 실행하면 다음과 같은 결과가 표시됩니다:

모든 것이 올바르게 작동하면 LLM이 SERP API 도구를 호출하고, 상위 뉴스 기사를 선택하고, 의도한 대로 Web Unlocker API로 콘텐츠를 스크래핑했음을 확인할 수 있습니다.
완성! 이는 통합이 작동하고 있음을 확인합니다. Bright Data가 이제 Onyx에서 완전히 사용 가능하여 강화된 채팅 경험을 제공합니다.
결론
이 문서에서 Onyx가 무엇인지, AI 검색 및 어시스턴트 플랫폼으로서 무엇을 제공하는지 배웠습니다. 또한 LLM 기반 특성으로 인한 한계와 Bright Data 통합을 사용하여 이를 해결하는 방법도 살펴보았습니다.
강조된 바와 같이 Bright Data는 에이전트가 실시간 웹 데이터에 액세스하여 더 정확하고 맥락에 맞는 응답을 제공할 수 있게 합니다. Onyx에서는 Web MCP를 통하거나 Bright Data 제품을 직접 통합하는 OpenAPI 사양을 통해 이 작업을 수행할 수 있습니다.
기능을 더욱 확장하려면 Onyx 에이전트를 AI를 위한 Bright Data 서비스 전체 제품군과 연결하세요.
오늘 무료로 Bright Data 계정을 만들고 웹 데이터 솔루션 통합을 시작하세요!