Agent-Friendly Websites는 AI 에이전트가 웹사이트를 안정적으로 읽고 조작할 수 있게 만드는 설계 접근이다. 핵심은 사람에게 예쁜 화면을 보여주는 것에 그치지 않고, 스크린샷·HTML·접근성 트리·상호작용 상태가 모두 일관된 신호를 제공하게 하는 것이다.
에이전트는 사이트를 어떻게 보나
웹 에이전트는 보통 여러 채널을 함께 사용한다.
| 채널 | 에이전트가 얻는 정보 |
|---|---|
| 스크린샷 | 시각적 배치, 버튼 위치, 모달·오버레이 상태 |
| HTML | DOM 구조, 링크, 폼, 데이터 속성 |
| 접근성 트리 | 버튼 이름, 입력 라벨, 역할(role), 상태 |
| 브라우저 자동화 API | 클릭, 입력, 스크롤, 네비게이션 결과 |
사람에게는 보이지만 HTML이나 접근성 트리에는 이름이 없는 버튼, 클릭해야만 의미가 드러나는 커스텀 UI, 상태가 URL에 반영되지 않는 화면은 에이전트에게 어려운 사이트다.
설계 원칙
- 의미 있는 HTML을 쓴다: 버튼은
button, 링크는a, 폼 입력은label과 연결한다. - 접근성 이름을 정확히 제공한다: 아이콘 버튼도
aria-label이나 보이는 텍스트로 목적을 알 수 있어야 한다. - 상태를 명확히 드러낸다: 선택됨, 비활성화됨, 로딩 중, 오류 상태를 DOM과 시각 표현 모두에 반영한다.
- URL과 제목을 안정적으로 유지한다: 에이전트가 현재 위치와 작업 맥락을 추론할 수 있어야 한다.
- 중요한 데이터는 이미지 안에만 두지 않는다: 표, 가격, 정책, 오류 메시지는 텍스트로도 제공한다.
사람에게도 좋은 UX다
에이전트 친화적 설계는 별도의 “봇 전용 페이지”를 만들라는 뜻이 아니다. 접근성 좋은 웹사이트, 예측 가능한 폼, 명확한 오류 메시지, 안정적인 링크 구조는 사람에게도 좋은 UX다. 차이는 AI 에이전트가 이 품질 문제를 더 자주, 더 크게 드러낸다는 점이다.
체크리스트
- 주요 CTA가 접근성 트리에서 이름과 역할을 갖는가?
- 로그인, 결제, 삭제 같은 위험 작업에는 명확한 확인 단계가 있는가?
- 검색 결과, 필터, 정렬 상태가 URL이나 DOM 상태로 추적 가능한가?
- 오류 메시지가 텍스트로 노출되고 해결 방법을 포함하는가?
- 스크립트 로딩 실패 시에도 핵심 콘텐츠를 읽을 수 있는가?
관련 문서
- browser-harness — 브라우저 자동화를 위한 자기치유 하네스
- chrome-devtools-mcp — Chrome 브라우저 제어·디버깅 MCP 서버
- kimi-webbridge-tutorial-browser-extension — 실제 브라우저와 AI 에이전트를 연결하는 방식
- agent-harness — 에이전트 도구 사용과 검증 루프 설계
참고 자료
- Build agent-friendly websites — web.dev (2026-05-19)