OpenAI 딥 리서치 API 개발자 가이드

정보 과부하 시대에 빠르고 정확하며 포괄적인 조사를 수행하는 능력은 초능력과 같습니다. 개발자, 분석가, 전략가는 문서를 샅샅이 뒤지고, 출처를 확인하며, 조사 결과를 종합하는 데 수많은 시간을 보냅니다. 이 모든 워크플로를 자동화할 수 있다면 어떨까요? OpenAI의 Deep Research API는 이러한 방향으로 나아가는 중요한 단계이며, 높은 수준의 질문을 구조화되고 인용이 풍부한 보고서로 변환하는 강력한 도구를 제공합니다.

Deep Research API는 단순한 대규모 언어 모델이 아닙니다. 복잡한 연구 작업을 처리하도록 설계된 에이전트 시스템입니다. 쿼리를 자율적으로 분해하고, 웹 검색을 수행하며, 데이터를 분석하기 위해 코드를 실행하고, 결과를 일관성 있고 검증 가능한 보고서로 종합할 수 있습니다. 답변뿐만 아니라 그 뒤에 있는 증거까지 제공하여 깊이, 뉘앙스, 신뢰를 위해 구축되었습니다.

이 가이드는 Deep Research API에 대한 개발자 중심의 단계별 설명을 제공합니다. 첫 API 호출부터 고급 프롬프트 기술까지 모든 것을 다룰 것입니다. 주로 API를 통해 사용할 수 있는 두 가지 모델에 중점을 둘 것입니다.

o3-deep-research-2025-06-26: 최고 품질의 종합 및 심층 분석에 최적화된 플래그십 모델입니다.
o4-mini-deep-research-2025-06-26: 대기 시간에 민감한 애플리케이션에 완벽한 더 가볍고 빠른 모델입니다.

이 글을 마치면 이 강력한 연구 에이전트를 자신의 애플리케이션에 통합하는 방법에 대한 확실한 이해를 갖게 될 것입니다.

💡

아름다운 API 문서를 생성하는 훌륭한 API 테스트 도구를 원하십니까?

개발자 팀이 최대 생산성으로 함께 작업할 수 있는 통합된 올인원 플랫폼을 원하십니까?

Apidog는 모든 요구 사항을 충족하며, Postman을 훨씬 저렴한 가격으로 대체합니다!

button

OpenAI Deep Research API 가격, 사용량 제한

프로덕션 애플리케이션의 경우 올바른 모델을 선택하고 비용을 이해하는 것이 중요합니다.

모델 선택

o3-deep-research: 최고 수준의 추론 및 종합이 필요한 복잡한 작업에 적합합니다. 느리지만 우수한 품질을 제공합니다.
o4-mini-deep-research: 속도가 최우선일 때 이 모델을 사용하십시오. 간단한 연구 작업이나 낮은 대기 시간이 중요한 대화형 애플리케이션에 이상적입니다.

비용 이해

2024년 말 현재, 강력한 o3-deep-research 모델의 가격은 토큰 기반입니다:

입력: 100만 토큰당 $10.00
출력: 100만 토큰당 $40.00

출력 토큰에 대한 높은 비용은 모델이 수행하는 집중적인 종합 및 생성 작업을 반영합니다.

주요 사양 (`o3-deep-research`)

컨텍스트 창: 거대한 200,000 토큰.
최대 출력 토큰: 넉넉한 100,000 토큰으로 매우 긴 형식의 보고서가 가능합니다.
지식 마감일: 2024년 6월 1일. 모델의 내부 지식은 이 날짜까지 최신이지만, web_search_preview 도구는 실시간 정보에 접근할 수 있게 합니다.

첫 OpenAI Deep Research API 호출하기

바로 시작하겠습니다. API를 사용하려면 OpenAI Python SDK가 필요합니다.

설정

아직 설치하지 않았다면, 라이브러리의 최신 버전을 설치하십시오:

pip install --upgrade openai

다음으로 인증해야 합니다. OpenAI 클라이언트를 임포트하고 API 키로 초기화하십시오.

from openai import OpenAI
import os

# API 키에 환경 변수를 사용하는 것이 가장 좋은 방법입니다.
client = OpenAI(api_key=os.environ.get("OPENAI_API_KEY"))

요청하기

Deep Research 작업은 특히 복잡한 쿼리의 경우 완료하는 데 몇 분이 걸릴 수 있습니다. 시간 초과를 피하려면 백그라운드에서 요청을 실행하는 것이 강력히 권장됩니다. API는 이를 쉽게 만듭니다.

우리가 의료 금융 서비스 회사를 위한 도구를 구축하고 있다고 상상해 봅시다. 작업은 새로운 당뇨병 및 비만 치료제의 경제적 영향에 대한 보고서를 작성하는 것입니다. 다음은 요청을 구성하는 방법입니다:

system_message = """
당신은 글로벌 보건 경제 팀을 대신하여 구조화되고 데이터 기반의 보고서를 준비하는 전문 연구원입니다. 당신의 임무는 사용자가 제기하는 건강 질문을 분석하는 것입니다.

수행할 일:
- 데이터가 풍부한 통찰력에 집중하십시오: 특정 수치, 추세, 통계 및 측정 가능한 결과를 포함하십시오.
- 적절할 때, 차트나 표로 변환할 수 있는 방식으로 데이터를 요약하십시오.
- 신뢰할 수 있는 최신 출처를 우선시하십시오: 동료 검토 연구, 보건 기관 (예: WHO, CDC) 등.
- 인라인 인용을 포함하고 모든 출처 메타데이터를 반환하십시오.

분석적이어야 하며, 일반화를 피하고, 각 섹션이 데이터 기반 추론을 뒷받침하는지 확인하십시오.
"""

user_query = "세마글루타이드가 글로벌 의료 시스템에 미치는 경제적 영향을 조사하십시오."

response = client.responses.create(
  model="o3-deep-research", # 또는 "o3-deep-research-2025-06-26"
  input=[
    {
      "role": "developer",
      "content": [
        {
          "type": "input_text",
          "text": system_message,
        }
      ]
    },
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": user_query,
        }
      ]
    }
  ],
  reasoning={
    "summary": "auto"
  },
  tools=[
    {
      "type": "web_search_preview"
    },
    {
      "type": "code_interpreter"
    }
  ]
)

이 호출을 분석해 봅시다:

model: 고품질 보고서를 위해 o3-deep-research를 지정합니다.
input: 여기에 프롬프트를 제공합니다. system_message는 에이전트의 페르소나와 전반적인 목표를 설정합니다. user_query는 특정 연구 작업입니다.
reasoning: summary를 "auto"로 설정하면 모델이 보고서에 대한 최상의 요약을 생성할 수 있습니다. 더 자세한 보고서의 경우 "detailed"로 설정할 수 있습니다.
tools: 이 배열은 에이전트가 사용할 수 있는 도구를 알려줍니다. web_search_preview는 웹을 탐색하는 데 필요합니다. code_interpreter는 선택 사항이지만 에이전트가 데이터 분석 및 시각화를 위해 Python 코드를 실행할 수 있도록 합니다.

Deep Research API의 진정한 힘은 반환하는 구조화되고 상세한 응답 객체에 있습니다. 단순히 텍스트 블록이 아니라 연구 과정의 투명한 기록입니다.

최종 보고서

주요 출력은 물론 최종 보고서입니다. output 배열의 마지막 항목에서 액세스할 수 있습니다:

# 응답 객체에서 최종 보고서에 액세스
print(response.output[-1].content[0].text)

이렇게 하면 모델이 생성한 완전하고 종합적인 텍스트를 얻을 수 있습니다.

인용 및 출처

모든 진지한 연구에서 가장 중요한 기능 중 하나는 인용입니다. Deep Research API는 인용 메타데이터를 응답에 직접 포함합니다. 각 인용은 텍스트의 특정 부분에 연결되어 쉽게 확인할 수 있습니다.

다음은 인용을 추출하고 표시하는 방법입니다:

annotations = response.output[-1].content[0].annotations
for i, citation in enumerate(annotations):
    print(f"Citation {i+1}:")
    print(f"  Title: {citation.title}")
    print(f"  URL: {citation.url}")
    print(f"  Location: chars {citation.start_index}–{citation.end_index}")

이 구조는 높은 수준의 신뢰와 투명성이 요구되는 애플리케이션을 구축하는 데 매우 중요합니다. 이를 사용하여 클릭 가능한 각주를 만들거나, 참고 문헌을 구축하거나, 주장을 원래 출처로 프로그래밍 방식으로 추적할 수 있습니다.

내부 들여다보기: 중간 단계

API는 또한 에이전트의 전체 사고 과정을 노출합니다. response.output에는 최종 답변에 도달하기 위해 취한 모든 중간 단계의 로그가 포함되어 있습니다. 이는 디버깅, 분석 또는 단순히 에이전트가 어떻게 작동하는지 이해하는 데 매우 유용합니다.

추론 단계: 문제 해결을 위해 모델의 내부 계획 및 요약을 나타냅니다.

reasoning = next(item for item in response.output if item.type == "reasoning")
for s in reasoning.summary:
    print(s.text)

웹 검색 호출: 에이전트가 사용한 정확한 검색 쿼리를 볼 수 있습니다.

search = next(item for item in response.output if item.type == "web_search_call")
print("Query:", search.action["query"])

코드 실행: code_interpreter 도구가 사용된 경우, 실행된 코드와 결과 출력을 검사할 수 있습니다.

code_step = next((item for item in response.output if item.type == "code_interpreter_call"), None)
if code_step:
    print("Code Input:", code_step.input)
    print("Code Output:", code_step.output)

MCP 서버와 함께 OpenAI Deep Research 사용하기

MCP 서버를 사용한 고급 연구

웹 검색은 Deep Research 에이전트에게 방대한 공개 정보 저장소에 대한 접근 권한을 부여하지만, 자체 비공개 데이터에 연결할 때 진정한 힘이 발휘됩니다.

여기서 모델 컨텍스트 프로토콜(MCP)이 등장합니다. MCP를 사용하면 에이전트의 기능을 확장하는 사용자 정의 도구를 구축하여 내부 지식 기반, 데이터베이스 또는 기타 독점 서비스에 쿼리할 수 있습니다.

현재 인기 있는 MCP 서버 중 하나는 Apidog MCP 서버로, 커서 및 기타 AI 코딩 도구 내에서 API 문서에 연결할 수 있으며, 사실적인 API 사양에서 정보를 가져와 AI 환각을 크게 줄입니다.