4,682
웹에서 답을 찾는 에이전트를 만들 때, 검색 결과를 얻는 일과 원문을 읽는 일은 구분해야 합니다. DeepSeek이 공개한 Search·Fetch API는 이 두 단계를 각각 구조화된 검색 결과와 Markdown 본문으로 제공합니다.[10]
이번 글은 2026년 10월 17일 공식 발표된 기능을 다룹니다.[7] 발표와 기술 문서를 기준으로 기능·활용·제약을 설명하되, 검색 품질에 관한 독립적인 성능 보장으로 확대하지 않습니다.
💡 💡 핵심: Search는 읽을 페이지를 고르고, Fetch는 선택한 페이지의 본문을 가져옵니다.[10] 설계 관점에서는 ‘검색됨’과 ‘근거를 읽음’을 서로 다른 상태로 관리하는 것이 중요합니다.
Search는 DeepSeek의 자체 검색 엔진을 사용해 질의에 맞는 페이지 목록을 반환하는 JSON API입니다.[10] 엔드포인트는 POST /v1/tools/search입니다.[11]
주요 입력은 검색어인 query, 결과 수인 count, 본문 포함 여부인 need_content입니다.[11] 검색어는 공백만으로 구성할 수 없는 1128자이고, 결과 수는 150개이며 기본값은 10개입니다.[11]
site:, lang:, after:, before: 같은 연산자로 사이트·언어·날짜 조건을 전달할 수 있습니다.[10] 다만 검색 필터를 적용했다는 사실만으로 개별 원문의 게시 날짜까지 검증됐다고 취급하지 않는 편이 좋습니다.
Fetch는 URL 하나를 받아 페이지의 title과 Markdown content를 반환합니다.[12] 엔드포인트는 POST /v1/tools/fetch이며, 입력 URL은 호스트가 있는 HTTP/HTTPS 주소여야 하고 사용자 이름이나 비밀번호를 포함할 수 없습니다.[12]
두 API는 DeepSeek API와 같은 Bearer 인증을 사용하는 원시 JSON API입니다.[10] 이 글은 검색 도구 계층에 관한 설명이지, 특정 모델의 추론 성능이나 전체 RAG 시스템의 품질을 검증한 글은 아닙니다.
Search 응답에는 UI 표시용 snippet, 모델이 읽는 용도의 더 긴 summary, 페이지 본문인 content가 구분되어 있습니다.[11] need_content의 기본값은 false이며, 이때 content는 빈 문자열입니다.[11]
need_content=true를 요청해도 본문을 구할 수 없으면 content가 비어 있을 수 있습니다.[11] 정상 검색에서 일치하는 결과가 없으면 results는 빈 배열입니다.[11]
💡 ⚠️ 주의: 검색 요약을 읽었다고 원문 전체를 읽은 것은 아닙니다. 본문이 비어 있다면 ‘검색 결과 발견’까지만 성공한 것으로 처리하고, 핵심 주장에 필요한 근거를 확보하지 못했음을 남기는 설계를 권합니다.
Search는 관련성·권위·최신성 신호를 조합한 rerank_score도 반환합니다.[11] 이는 검색 결과를 고르는 데 쓰는 신호로 해석해야 하며, 글의 모든 주장이 참임을 보증하는 사실성 점수로 사용하지 않는 것이 제 의견입니다.
응답의 date는 UTC 게시 시각이지만, 알 수 없으면 null입니다.[11] 따라서 날짜가 빠진 결과를 자동으로 ‘오늘 뉴스’에 포함하기보다는 원문의 날짜를 확인하거나 최신성 미확인으로 분리하는 편이 안전합니다.
아래는 설계 제안이며 직접 구축하거나 실행한 결과가 아닙니다.
content를 확인하고, 필요한 페이지를 Fetch로 읽습니다. 본문이 이미 충분하면 불필요한 추가 Fetch는 생략합니다.‘최근 프레임워크 업데이트가 우리 서비스에 주는 영향’을 조사한다고 가정해 보겠습니다. 공식 release note를 우선 검색하고, 후보에서 실제 변경 사항과 호환성 설명을 읽은 뒤, 팀의 코드에 대한 판단은 별도로 작성하는 방식입니다.
이때 원문에 적힌 지원 범위와 우리 서비스에 적용할 수 있다는 판단을 분리하는 것이 핵심입니다. 외부 페이지 본문은 근거 데이터로 다루고, 그 안의 문구가 도구 실행·인증정보 접근·외부 전송을 지시해도 승인으로 취급하지 않는 구조를 권합니다.
이 시나리오는 고객 도입 사례나 생산성 측정 결과가 아닙니다. 범위가 정해진 공식 문서 몇 개만 읽으면 충분한 업무라면, 새 검색 서비스를 추가하기보다 기존 HTTP 수집과 검토 절차를 유지하는 편이 더 단순할 수 있습니다.
DeepSeek은 DeepSeek API를 DeepSeek Harness·Claude Code·Codex를 통해 사용할 때 서버 측 Search·Fetch 도구 호출이 해당 API를 이용한다고 안내합니다.[10] 이는 각 제품의 모든 모델·검색 경로에 기본 적용된다는 뜻으로 확대하면 안 됩니다.
공식 발표는 이 서버 측 도구 호출에 한해 현재 무료이며, 2026년 10월 31일 16:00 UTC부터 과금한다고 명시합니다.[7] KST로는 2026년 11월 1일 01:00입니다. 독립 매체의 10월 18일 설명도 같은 가격·계정별 한도·서버 측 호출 유예를 소개하지만, 이 내용은 별도의 검색 성능 비교 실험이 아니라 문서 기반 설명입니다.[6]
공식 가이드는 검색 요청에 query, count, need_content를 전달하고, 결과에서 제목·URL·요약을 읽는 예제를 제공합니다.[10] Fetch 예제는 URL을 보내고 응답의 제목과 본문을 확인하는 방식입니다.[10]
이는 API 사용 형태를 보여주는 문서 예제입니다. 이 리서치에서는 유료 API 호출, 인증 설정, 실제 검색 품질·지연 시간 측정을 수행하지 않았으며 예제 응답을 실행 결과로 제시하지 않습니다.
Fetch는 대상 사이트의 가용성과 접근 정책에 영향을 받습니다.[10] 보안 정책 거절은 403, 사이트 차단·지원하지 않는 콘텐츠 유형·추출 가능한 본문 부재 등으로 사용할 수 있는 본문을 가져오지 못하면 404가 반환될 수 있습니다.[10]
따라서 ‘URL을 찾았으니 언제나 본문도 얻는다’는 전제로 workflow를 만들지 않는 편이 좋습니다. 접근 거절을 무한 재시도로 우회하려 하기보다, 허용된 다른 공식 출처로 전환하거나 근거 부족으로 종료하는 경로를 권합니다.
Search와 Fetch의 한도는 계정당 각각 5 QPS로 독립 적용됩니다.[10] API 키를 나누어도 계정별 계산은 유지되고, 모델 동시 실행 한도와도 별개이며, Fetch에는 도메인별 QPS 제한도 있습니다.[10]
공식 문서는 408, 429, 5xx에는 기다린 뒤 재시도하고, 402에는 잔액 충전이 선행되어야 하며, 다른 4xx는 요청 변경 없이 재시도하지 말라고 안내합니다.[10] 설계 시에는 재시도 횟수와 전체 작업 deadline을 함께 제한할 것을 권합니다.
문서상 Search와 Fetch는 각각 성공 요청 1,000건당 0.75달러입니다.[10] HTTP 200이면서 Search가 비어 있지 않은 결과를 반환하거나 Fetch가 본문을 반환해야 과금되며, 실패·빈 검색 결과·타임아웃은 과금되지 않습니다.[10]
count는 결과 개수만 바꾸며 요청당 가격을 바꾸지 않습니다.[10] 앞서 설명한 무료 기간은 공식 안내가 지정한 서버 측 도구 호출 범위이므로, 직접 JSON API도 모두 무료라고 가정해서는 안 됩니다.[7][10]
운영 비용을 판단할 때는 검색·Fetch 요청 기록뿐 아니라 읽은 본문을 후속 모델에 전달하는 별도 처리 비용도 함께 점검하는 것이 제안 사항입니다. 이 글에서는 그 후속 비용이나 경쟁 제품 대비 절감률을 계산·측정하지 않았습니다.
도입 검토 의견: 여러 웹 출처를 반복 조사하고, 검색과 본문 추출을 명시적인 도구 단계로 통일하려는 팀에 검토할 가치가 있습니다. 평가할 때는 한국어 질의, 실제 업무 도메인, 날짜 누락, 본문 추출 실패를 포함한 자체 테스트셋을 먼저 정하는 편이 좋습니다.
보류 의견: 검색 대상이 제한적이거나 기존 수집 방식으로 충분한 경우, 새 의존성을 추가할 이유부터 확인해야 합니다. 사내 비공개 정보가 검색어에 들어갈 수 있는 업무라면 데이터 전송 정책 검토가 API 연동보다 먼저입니다.
💡 📌 검증 범위: 2026년 10월 19일 KST에 공식 발표·가이드·Search/Fetch reference와 별도 매체 글의 본문을 읽었습니다. 기능·제약은 공식 문서 기준이며, 독립적인 성능 검증이나 직접 사용 경험을 주장하지 않습니다.
Search·Fetch의 핵심은 더 많은 URL을 얻는 데만 있지 않습니다. 후보를 찾는 단계와 근거를 읽는 단계를 분리하고, 본문 확보·최신성·실패·비용을 명시적으로 다루는 것이 이 글의 설계 제안입니다.
처음부터 복잡한 에이전트를 만들기보다, 질문 하나에서 ‘어떤 원문 구절을 실제로 읽었는가’를 추적할 수 있는 작은 흐름부터 검토해 보세요.
[6] https://dejan.ai/blog/deepseek-search-engine
[7] https://api-docs.deepseek.com/news/news261017
[10] https://api-docs.deepseek.com/guides/search