웹 검색

에이전트가 질문에 답하거나 과제를 완료하기 위해 정보를 찾아야 할 때 웹 검색을 사용해요.

출처: 문서

본문

예시: 화성이 왜 붉게 보이는지 설명하기

POST /v1/agents/sessions로 이 JSON 본문을 보내 세션을 만들고 답을 스트리밍해 보세요. 웹 검색을 live 모드로 활성화해요:

{
  "agent": {
    "model": "gpt-6-astra",
    "reasoning": { "effort": "low" },
    "tools": [{ "type": "web_search", "mode": "live" }]
  },
  "environment": { "type": "none" },
  "input": "Search NASA's website for why Mars looks red. Explain it in two sentences and include a source link.",
  "stream": true
}

결과 (Result)

2026년 9월 10일 테스트 실행에서 에이전트가 NASA 웹사이트를 검색하고 이 답을 스트리밍했어요:

화성이 붉게 보이는 이유는 토양 속 철 광물이 산화(녹슬어)되면서 표면이 붉은 색을 띠기 때문이에요. NASA의 화성 사실에 따르면 이렇게 녹슨 모습 때문에 "붉은 행성"이라고 불려요.

이건 기록된 예시예요. 여러분의 답은 다를 수 있어요.

agent.tools에서 web_search를 빼면 내장 웹 검색이 꺼져요. 프롬프트에서 검색을 요청해도 켜지지 않아요.

검색 모드 (Search mode)

  • live (기본값): 검색이 실시간 인터넷에 접근하도록 허용해요. web_search를 포함하고 mode를 빼면 이 모드를 사용해요.
  • cached: 실시간 인터넷에 접근하지 않고 저장된 웹 콘텐츠를 검색해요.
  • disabled: 도구를 아예 빼는 것처럼 내장 웹 검색을 꺼요.

선택 설정 (Optional settings)

같은 web_search 항목에 다음 필드를 추가하세요:

설정 하는 일 생략 시
context_size 모델이 검색에서 받는 정보의 양: low, medium, high. medium을 사용해요.
allowed_domains 검색에 포함할 웹사이트. 최대 100개 도메인 이름, 예: ["python.org", "docs.python.org"]. 도메인 필터가 적용되지 않아요.
location 결과를 지역에 맞게 조정하는 데 도움. country, region, city, timezone을 받아요. 검색에 위치가 제공되지 않아요. 위치 세부 정보가 없으면 지역 검색에서 관련성이 낮거나 유용한 결과가 없을 수 있어요.

더 알아보기 (Learn more)