How to Build AI Agents with the Claude Agent SDK and Firecrawl
Quick Summary
Claude Agent SDK와 Firecrawl MCP를 결합해 Python 의존성을 병렬 조사하고, 스키마로 검증된 위험 보고서를 만드는 방법을 설명한 튜토리얼이다.
🖼️ 인포그래픽

🖼️ 4컷 인포그래픽

💡 한 줄 요약
Claude Agent SDK와 Firecrawl MCP를 결합해 Python 의존성을 병렬 조사하고, 스키마로 검증된 위험 보고서를 만드는 방법을 설명한 튜토리얼이다.
📌 핵심 요약
- Claude Agent SDK는 Claude Code의 도구·에이전트 루프·컨텍스트 관리를 Python과 TypeScript 애플리케이션에 제공한다. 2025년 6월 Claude Code SDK로 처음 출시됐고, 2025년 9월 29일 현재 이름으로 변경됐다.
- 예제는 requirements.txt의 패키지를 병렬 서브에이전트에 배정해 PyPI와 GitHub에서 조사하고 위험 보고서를 만든다. 연구자는 자료 수집에 집중하고, 조정 에이전트가 유지보수 상태와 위험 수준을 분류한다.
- Pydantic 모델의 JSON Schema를 output_format에 전달하면 ResultMessage.structured_output으로 구조화된 결과를 받을 수 있다. 스키마 출력 재시도 실패에 대한 오류 처리가 필요하며, 필드 주석에 적은 분류값은 엄격하게 강제되지 않을 수 있다.
- Firecrawl MCP는 mcp_servers로 연결되며 검색·스크래핑 등의 도구와 정제된 Markdown을 제공한다. 로컬 서버는 npx로 실행하고, 원격 HTTP 서버는 Search·Scrape·Parse에 키 없이 접근할 수 있으며 다른 도구에는 API 키를 bearer token으로 전달한다.
- Python 예제에는 Python 3.10+와 Node.js가 필요하고, SDK 패키지는 Claude Code 바이너리를 포함한다. 원문에 따르면 Python 패키지는 2026년 11월 9일 버전 0.2.180에서도 Alpha로 표시되므로 버전 고정이 권장된다.
🧩 주요 포인트
- 실행 방식에 따라 선택이 달라진다 → Claude Agent SDK는 자체 애플리케이션에 에이전트 루프를 내장하고, Claude Code CLI는 대화형 작업을 지원하며, Claude API는 도구 루프를 직접 구현할 수 있게 한다.
- 병렬 서브에이전트의 자료 수집과 조정 에이전트의 분류를 분리한다 → 패키지별 조사에 집중하면서 전체 조사 결과를 모아 유지보수 상태와 위험 수준을 판단할 수 있다.
- JSON Schema와 Firecrawl MCP는 결과 형식과 웹 자료 처리를 지원한다 → 구조화된 보고서 생성이 쉬워지지만, 분류값 검증·출력 오류 처리·도구별 인증 조건은 별도로 다뤄야 한다.
🧠 상세 정리
1. Claude Code의 에이전트 루프를 애플리케이션으로 옮기기
원문은 터미널에서 대화형으로 사용하는 Claude Code와, 사람이 붙어 있지 않아도 일정이나 파이프라인에 따라 실행되는 에이전트의 차이에서 출발한다. Claude Agent SDK는 Claude Code의 에이전트를 Python 또는 TypeScript 애플리케이션 안에서 실행하게 하며, 같은 내장 도구와 권한·세션·훅·서브에이전트 기능을 제공한다. Anthropic은 2025년 2월 Claude Code를 명령줄 도구로 소개했고, Python SDK는 2025년 6월 claude-code-sdk라는 이름으로 처음 출시했다. 이후 2025년 9월 29일 Claude Agent SDK로 이름을 바꿨는데, 원문은 같은 실행 기반을 코딩뿐 아니라 금융·고객 지원·심층 조사에도 사용할 수 있다는 점을 이유로 설명한다. 사용자는 허용할 동작과 외부 도구를 설정하고, 에이전트가 파일 작업·명령 실행·정보 검색·하위 작업 조정을 수행하도록 구성한다.
2. Agent SDK·Claude Code CLI·Claude API의 선택 기준
원문은 세 가지 접근법을 모델의 성능보다 실행 환경과 도구 루프의 책임에 따라 구분한다. Claude Agent SDK는 사용자가 운영하는 프로세스에서 Claude Code 바이너리를 실행하는 라이브러리이며, Claude Code CLI는 터미널에서 대화형 작업이나 일회성 작업을 수행하는 인터페이스다. Claude API의 Client SDK는 모델에 직접 접근하게 하므로 도구 루프를 직접 작성하거나 베타 도구 실행기를 사용해야 한다. Agent SDK에는 파일 읽기·쓰기·수정, 명령 실행, 웹 검색 외에도 생명주기 훅, MCP 연결, 권한 제어, 세션 재개와 분기, 스킬·명령·메모리 및 플러그인 지원이 포함된다. 원문은 SDK 기반 애플리케이션이 Anthropic의 승인을 받은 경우를 제외하면 claude.ai 로그인 대신 API 키로 인증해야 하며, 사용량은 Claude API를 통해 과금된다는 문서상의 조건도 덧붙인다.
3. 의존성 감사 예제와 실행 준비
튜토리얼의 예제는 requirements.txt를 읽고 각 패키지의 위험 보고서를 만드는 의존성 감사기다. 저자는 pip-audit 같은 도구가 이미 존재한다는 점을 인정하면서, 예제의 목적은 감사 기능 자체보다 서브에이전트·구조화된 출력·MCP 통합의 사용법을 보여주는 데 있다고 설명한다. Python 3.10+와 Node.js가 필요하고, claude-agent-sdk·pydantic·rich·python-dotenv를 설치하며, SDK에 Claude Code 바이너리가 포함되므로 별도 설치는 필요하지 않다. .env에는 ANTHROPIC_API_KEY와 FIRECRAWL_API_KEY를 두고, 전자는 SDK가 환경에서 자동으로 읽으며 후자는 python-dotenv로 불러와 MCP 서버 설정에 전달한다. 전체 실행에는 별도 전체 스크립트의 입력 파싱·Rich 표 렌더링·Markdown 보고서 저장 함수도 필요하고, 이전 SDK 기준의 전체 스크립트와 본문 코드가 다르면 본문을 따르라고 안내한다. 또한 원문은 Python 패키지가 2026년 11월 9일 버전 0.2.180에서도 Alpha로 표시된다고 밝히며 버전 고정을 권장한다.
4. Pydantic과 JSON Schema로 보고서 형식 정의
보고서 형식은 패키지 하나를 표현하는 PackageReport와 전체 패키지 목록을 감싸는 AuditResult라는 두 Pydantic 모델로 정의한다. PackageReport에는 이름, 고정 버전, 최신 버전, 최근 출시일, 최근 커밋, 유지보수 상태, 위험 수준, 요약, 대체 패키지 필드가 있으며, 여러 필드에 빈 문자열 기본값을 둔다. 기본적으로 에이전트는 일반 텍스트를 반환하지만, AuditResult.model_json_schema()를 output_format에 전달하면 스키마에 맞는 JSON을 생성하고 이를 Python 객체로 검증할 수 있다. 다만 재시도 후에도 스키마를 만족하지 못하면 단발성 query()가 error_max_structured_output_retries 하위 유형의 오류 결과를 내보낸 뒤 예외를 발생시키므로, structured_output을 사용하기 전에 오류 처리가 필요하다. 초기 실험에서는 stale 대신 outdated가 반환되기도 했는데, 필드 주석만으로 허용값이 강제되지는 않으므로 엄격한 분류값이 필요하면 Pydantic 검증기나 후처리를 추가해야 한다.
5. 시스템 프롬프트로 유지보수 상태와 위험 분류
조정 에이전트의 시스템 프롬프트는 각 패키지를 조사할 연구자를 배정하고, 결과가 모두 돌아오면 유지보수 상태와 위험 수준을 분류하도록 지시한다. 유지보수 상태는 최근 6개월 이내 출시를 active, 6~18개월을 slowing down, 18개월~2년을 stale, 2년 이상 출시가 없거나 저장소가 보관 처리된 경우를 abandoned로 정한다. 위험 수준은 활발히 유지되고 알려진 문제가 없으면 low, 개발 속도가 느려지거나 사소한 우려가 있으면 medium, 오래됐거나 방치됐거나 보안 위험이 있거나 유지보수되는 대안이 없으면 high로 제시한다. 프롬프트는 stale 또는 abandoned인 패키지에 대체재를 제안하고, 요약은 한 문장으로 작성하도록 요구한다. 한편 앞선 모델 설명에서는 replacement 필드가 abandoned 패키지에만 적용된다고 설명하므로, 대체재 제안 범위에는 본문 설명과 실제 프롬프트 사이의 차이가 있다.
6. 병렬 연구자와 조정 에이전트의 역할 분리
원문은 모든 패키지의 연구자를 한꺼번에 배정하라는 문구가 병렬 실행에 중요하다고 강조하며, 이 지시가 없으면 패키지를 순차적으로 조사해 여덟 개 의존성을 처리하는 데 훨씬 오래 걸린다고 설명한다. 조정 에이전트는 Agent 도구로 패키지별 연구자를 호출하고, 각 연구자는 Firecrawl로 PyPI의 최신 버전과 출시일, GitHub 저장소의 최근 커밋과 활동을 확인한다. 연구자에게는 분류 기준이나 위험 수준을 알려주지 않고 자료 수집과 상세한 텍스트 보고에 집중시키도록 프롬프트를 좁힌다. 이 분리로 연구자는 한 패키지의 정확한 정보 확보에 집중하고, 조정 에이전트는 여덟 패키지의 결과를 모두 본 뒤 평가할 수 있다는 것이 원문의 설명이다. 도입부는 AgentDefinition으로 서브에이전트를 선언한다고 소개하지만, 제공된 본문에는 그 선언과 호출을 완성하는 후속 코드가 포함되어 있지 않다.
7. 로컬 Firecrawl MCP 연결과 도구 등록
외부 웹 도구는 mcp_servers 설정에 Firecrawl 서버를 추가하는 방식으로 연결하며, 예제는 npx에 -y와 firecrawl-mcp 인수를 넘겨 로컬 프로세스를 실행한다. FIRECRAWL_API_KEY는 서버 환경 변수로 전달하고, SDK가 서버를 시작한 뒤 사용 가능한 도구를 발견해 기존 내장 도구와 함께 등록한다. 원문이 열거하는 도구에는 search·scrape·crawl·interact·agent 등이 있으며, 에이전트에는 mcp__firecrawl__ 접두사가 붙은 이름으로 노출된다. 예를 들어 스크래핑 도구는 mcp__firecrawl__firecrawl_scrape로 표시되며, 첫 실행에서는 npx가 패키지를 내려받고 이후에는 캐시된 버전을 사용한다고 설명한다. 저자는 Firecrawl이 페이지를 정제된 Markdown으로 바꾸고 JavaScript 렌더링을 처리하므로 PyPI와 GitHub 조사에서 HTML 잡음을 줄여준다고 주장하며, 같은 설정 사전에 여러 MCP 서버를 추가할 수도 있다고 안내한다.
8. 원격 MCP와 다른 연결 방식, 제공 자료의 범위
로컬 프로세스를 실행하고 싶지 않다면 https://mcp.firecrawl.dev/v2/mcp의 호스팅 서버를 사용할 수 있으며, 같은 설정 사전에 type을 http로 지정하고 url을 넣는 방식으로 연결한다. 원문에 따르면 이 엔드포인트의 Firecrawl Search·Scrape·Parse는 API 키 없이 사용할 수 있고, 다른 도구에는 API 키를 bearer token으로 전달한다. 같은 Firecrawl 도구는 Python·Node SDK, REST API, Firecrawl CLI와 노코드 통합으로도 제공되므로 조사 단계가 이 Python 예제에만 묶이지 않는다고 설명한다. 튜토리얼은 MCP 대신 Firecrawl CLI를 스킬로 사용하는 별도 예제도 소개하며, 해당 경로에서는 firecrawl-cli를 전역 설치하고 초기화해 스킬로 등록하도록 안내한다. 제공된 source_body는 이 설명 다음의 미완성 소제목에서 끊기므로, 이후 실행 코드나 감사 결과를 확인할 수는 없으며 실제 완성된 보고서의 품질도 이 자료만으로 판단할 수 없다.
🧾 핵심 주장 / 시사점
- 이 예제의 핵심은 의존성 감사 도구의 대체가 아니라, 자료 수집·병렬 작업·중앙 분류·구조화된 반환을 하나의 에이전트 실행에 연결하는 방법이다.
- JSON Schema에 맞는 출력과 분류 의미의 정확성은 별도로 확인해야 한다. 원문의 stale 대신 outdated가 나온 사례는 필드 주석만으로 분류값을 강제하기 어렵다는 점을 보여준다.
- Firecrawl의 정제된 웹 자료와 연구자 역할 분리는 조사 작업을 지원하지만, 제공된 본문에는 완성된 실행 결과가 없어 감사 정확도나 실제 처리 시간의 개선 폭은 확인되지 않는다.
✅ 액션 아이템
- Claude Agent SDK의 Alpha 상태를 고려해 Python 패키지 버전 고정을 적용한다.
- JSON Schema 기반 출력에 분류값 검증과 출력 재시도 실패에 대한 오류 처리를 추가한다.
- 병렬 서브에이전트의 자료 수집과 조정 에이전트의 유지보수 상태·위험 수준 분류를 분리해 구성한다.
❓ 열린 질문
- 자체 애플리케이션의 실행 요구에는 Claude Agent SDK, Claude Code CLI, Claude API 중 어느 방식이 적합한가?
- 구조화된 위험 보고서의 분류값 검증과 출력 오류 처리는 어느 수준까지 필요한가?
- Firecrawl MCP의 Search·Scrape·Parse 외 도구도 필요해 API 키 인증을 구성해야 하는가?