HTML Scraping 탈피를 위한 Agent-native API 계층 설계

Why AI agents shouldn't scrape websites and what to do instead

Naxir2026년 4월 26일6분intermediate

AI 요약

Context

AI Agent가 HTML DOM을 파싱하며 발생하는 Presentation Logic 의존성 및 UI 변경에 따른 잦은 브레이크 현상 분석. 인간 중심의 HTML 추상화 모델이 Agent의 데이터 처리 효율과 시스템 안정성을 저해하는 구조적 한계 식별.

X-Agent-Request 헤더 기반의 Client 분기를 통한 HTML-JSON 응답 분리 구조 채택
/.well-known/agent-manifest.json을 통한 사이트 기능 및 JSON Schema의 Runtime Discovery 메커니즘 구현
단일 요청 처리용 Intents와 다단계 워크플로우 제어용 Flows의 이원화된 API 모델 설계
Server-orchestrated 모드를 통한 세션 상태 유지 및 단계별 전이(Transition) 강제 제어로 비즈니스 로직 무결성 보장
Client-orchestrated 모드를 통한 Stateless 엔드포인트 제공으로 Idempotent Read 작업의 효율성 최적화
FastAPI Mount 방식을 활용하여 기존 Legacy Route에 영향 없는 사이드카 형태의 Agent Layer 통합

실천 포인트

1. Agent 접근용 전용 Manifest 파일 정의 여부 검토

2. 복잡한 비즈니스 시퀀스를 Server-side State로 관리할지 Client-side Chaining으로 처리할지 결정

3. API 응답에 JSON Schema를 포함하여 Agent의 Runtime 적응성 확보

4. MCP(Model Context Protocol)와 외부 서비스 인터페이스의 역할 분담 설계

태그