OpenAI Agents SDK 웹 스크래핑
OpenAI Agents SDK 에이전트를 Spicrawl MCP 서버에 연결하세요. 그러면 에이전트가 웹 페이지를 Markdown으로 읽을 수 있습니다.
설정하기
openai-agents를 설치하세요.SPICRAWL_API_KEY와OPENAI_API_KEY를 설정하세요.URL과
params의Authorization헤더로MCPServerStreamableHttp를 여세요.모델이 볼 도구를 제한하려면
create_static_tool_filter를 사용하고, 서버를Agent에 전달하세요.
예시: 가격 페이지 읽기
import asyncio
import os
from agents import Agent, Runner
from agents.mcp import MCPServerStreamableHttp, create_static_tool_filter
async def main() -> None:
async with MCPServerStreamableHttp(
name="spicrawl",
params={
"url": "https://mcp.spicrawl.com/mcp",
"headers": {"Authorization": f"Bearer {os.environ['SPICRAWL_API_KEY']}"},
},
cache_tools_list=True,
tool_filter=create_static_tool_filter(
allowed_tool_names=["spicrawl_scrape", "spicrawl_batch_submit"]
),
) as server:
agent = Agent(
name="Page reader",
instructions="Use the Spicrawl tools to read web pages.",
mcp_servers=[server],
)
result = await Runner.run(
agent,
"Read https://example.com/pricing as markdown and list the plans.",
)
print(result.final_output)
asyncio.run(main())서버에는 OAuth가 없으므로 항상 키를 headers에 담아 보내세요. 401이 나오면 에이전트를 실행하는 프로세스에 SPICRAWL_API_KEY가 설정되어 있는지 확인하세요.
도구 목록을 짧게 유지하세요
도구 스키마 25개가 모델을 호출할 때마다 전송됩니다. spicrawl_scrape는 유지하고, 많은 URL에는 spicrawl_batch_submit, spicrawl_batch_status, spicrawl_batch_results를 추가하세요.
코드가 가져올 URL을 이미 알고 있다면 POST /v1/scrape를 호출하는 일반 함수가 더 간단합니다. 도구 스키마 토큰이 들지 않고 테스트하기도 쉽습니다.
할 수 있는 일
이 서버는 에이전트에게 spicrawl_* 도구 25개를 제공합니다. 각 호출은 API를 직접 호출할 때와 같은 한도와 크레딧으로 사용자의 API 키로 실행됩니다.
- 페이지 하나 읽기:
spicrawl_scrape는 Markdown(기본값), 텍스트, HTML, JSON 또는 PDF를 반환합니다. - 여러 페이지 읽기:
spicrawl_batch_submit는 최대 10,000개의 URL을 대기열에 넣습니다. 이어서spicrawl_batch_status와spicrawl_batch_results를 사용하세요. - 로그인이 필요한 페이지:
spicrawl_session_create는 호출 사이에 쿠키와 스토리지를 유지합니다. - 실패 디버깅:
spicrawl_requests_list와spicrawl_request_get. - 사용량 확인:
spicrawl_usage_summary및 기타 사용량 도구입니다. 이 도구에는read범위가 있는 키가 필요합니다. - 조회하기:
spicrawl_docs_search와spicrawl_docs_read로 Spicrawl 문서를 검색하고 읽습니다.
도구 하나, spicrawl_browser_connect_url는 목록에 있지만 곧 제공될 예정입니다. spicrawl_scrape에서 렌더링 인수는 API의 js_render가 아니라 render입니다.
알아 두세요
- 크롤링은 지원하지 않습니다. Spicrawl은 링크를 따라가거나 페이지를 찾지 않습니다. 에이전트에게 URL을 주세요.
- 요청당 크레딧. 일반 fetch는 1 크레딧, JavaScript 렌더링은 3, 전체 브라우저 렌더링은 8입니다.
- 실패는 무료입니다. 실패한 요청은 0 크레딧입니다.
- 캐시는 시간을 절약해 줄 뿐 크레딧을 절약해 주지는 않습니다. 캐시 적중 비용은 그 결과를 저장한 요청과 같습니다.
- 호출마다 상한을 두세요.
max_cost를 설정하면 더 많은 비용이 들 수 있는 요청은 실행 전에 거부됩니다. - 곧 제공 예정: 관리형 프록시, 스텔스 모드, 원격 브라우저, 일반 문장 프롬프트를 이용한 AI 추출. 현재는 직접 프록시를 사용할 수 있습니다.
자주 묻는 질문
어떤 패키지가 필요한가요?
openai-agents. 예제를 실행하기 전에 SPICRAWL_API_KEY와 OPENAI_API_KEY를 설정하세요.
모델이 보는 도구를 제한하려면 어떻게 하나요?
Pass tool_filter=create_static_tool_filter(allowed_tool_names=[...]). The example keeps spicrawl_scrape and spicrawl_batch_submit.
에이전트가 연결할 때 401이 나오는 이유는 무엇인가요?
헤더가 없거나 키가 잘못되었습니다. SPICRAWL_API_KEY로 코드에서 헤더를 만들고, 에이전트를 실행하는 프로세스에 변수가 설정되어 있는지 확인하세요.
도구 호출이 실패하면 어떻게 되나요?
오류는 API의 코드와 함께 MCP 도구 오류로 모델에 전달됩니다. 실패한 호출은 0 크레딧입니다.
페이지당 비용이 얼마인가요?
일반 fetch는 1 크레딧, JavaScript 렌더링은 3, 풀 브라우저 렌더링은 8입니다. 실패한 요청은 0 크레딧입니다. 캐시 적중은 그 결과를 저장한 fetch와 같은 비용이 듭니다. 에이전트가 예상보다 많이 쓰지 않도록 요청마다 max_cost를 설정하게 하세요.