우리는 WebCMD 패러다임을 활용하여 웹 탐색 지연 시간을 95% 단축하고, LLM 토큰 소비를 90% 줄이며, 결정론적이고 스키마 검증이 가능한 명령줄 인터페이스(CLI)를 구축했습니다.

1. AI 에이전트를 위한 웹 탐색의 딜레마

현재의 AI 기반 자동화 환경에서 소프트웨어 에이전트는 정보를 수집하거나, 토론을 모니터링하거나, 시스템과 상호작용하기 위해 웹 플랫폼을 탐색하는 작업을 빈번하게 수행합니다. 전통적으로 이는 헤드리스 브라우저 (Headless Browsers, 예: Puppeteer, Playwright 또는 Selenium)를 사용하여 수행됩니다.

헤드리스 브라우저는 매우 유연하지만, 다음과 같은 상당한 숨겨진 비용이 발생합니다:

• 높은 시작 및 렌더링 지연 시간 (High Startup and Rendering Latency): Chromium 인스턴스를 초기화하고, DNS 확인을 수행하며, CSS/JS 자산을 로드하고, DOM을 렌더링하는 데 요청당 3~5초가 소요됩니다.
• 막대한 리소스 점유 (Massive Resource Footprint): 여러 개의 헤드리스 Chrome 프로세스를 병렬로 실행하면 CPU 및 메모리 사용량이 급증하여 확장성 병목 현상을 일으킵니다.
• 토큰 인플레이션 (Token Inflation): 가공되지 않은 HTML이나 마크다운으로 변환된 DOM 표현을 대규모 언어 모델 (LLMs)에 보내면 수천 개의 토큰을 소비합니다. 단순한 스토리 목록만으로도 단일 웹 페이지 표현이 쉽게 20KB~50KB (5,000개 이상의 토큰에 해당)에 달할 수 있습니다.
• 취약한 UI 선택자 (Brittle UI Selectors): 웹 스크래핑은 플랫폼의 레이아웃이 변경될 때마다 깨지는 CSS 선택자 또는 XPath 쿼리에 의존하므로, 에이전트 파이프라인이 조용히 실패하거나 환각 (Hallucination)을 일으키는 원인이 됩니다.

이러한 비효율성을 해결하기 위해, 우리는 WebCMD 레지스트리를 활용하여 Hacker News를 위한 고성능 명령줄 어댑터인 **HN CLI (hn-cli)**를 구축했습니다. 웹 상호작용을 브라우저 렌더링으로부터 분리함으로써, AI 에이전트를 위한 구조화되고 빠르며 토큰 효율적인 브릿지를 제공합니다.

2. WebCMD 패러다임 소개

WebCMD는 개발자가 웹 플랫폼을 위한 커맨드 라인 어댑터 (command-line adapters)를 정의할 수 있게 해주는 프레임워크입니다. 일반적으로 WebCMD는 헤드리스 브라우저 (headless browser)를 실행하고 대상 페이지에서 스크립트를 실행하여 명령을 수행합니다. 하지만 WebCMD는 browser: false 설정과 함께 **Strategy.PUBLIC**이라 불리는 보조 실행 전략을 지원합니다.

이렇게 구성할 경우:

1. 어댑터가 로컬 Node.js 환경에서 직접 실행됩니다.
2. WebCMD가 Chromium 실행을 완전히 건너뛰므로, 렌더링 및 시작 오버헤드 (startup overhead)가 제거됩니다.
3. 어댑터가 공개 REST 엔드포인트 (public REST endpoints)를 통해 대상 사이트와 상호작용하여, **200ms 미만의 지연 시간 (latency)**을 구현합니다.
4. 출력값은 기본적으로 구조화된 JSON 형식으로 포맷팅되어, LLM 에이전트가 즉시 읽을 수 있습니다.

graph TD
    subgraph Execution flow with WebCMD
        Agent[AI Agent or Developer] -->|webcmd hn top| Registry[WebCMD Registry]
...

3. Hacker News 어댑터의 아키텍처

hn-cli 리포지토리는 CLI 명령 정의, 핵심 유틸리티 로직, 테스트 및 구성 스크립트를 분리하여 깔끔한 모듈형 구조로 구성되어 있습니다:

• adapters/: 명령 정의를 포함합니다. 각 파일은 서브커맨드 (subcommand)를 등록합니다.
  • top.js: 인기 게시글 (top stories)을 가져옵니다.
  • newest.js: 새로 제출된 게시글을 가져옵니다.
  • ask.js: "Ask HN" 게시물을 검색합니다.
  • jobs.js: 채용 공고 상세 정보를 가져옵니다.
  • item.js: 단일 게시물에 대한 상세 정보(self-text 포함)를 확인합니다.
  • search.js: Algolia 검색 API와 인터페이스합니다.
  • utils.js: 핵심 헬퍼 함수 (네트워크 재시도, 스키마 검증, HTML 엔티티 정화 (sanitization)).
• tests/: 오프라인 테스트 실행을 위한 완전한 모킹 (mocked) 기반의 Vitest 스위트입니다.
• scripts/: 어댑터 등록, 서브프로세스 실행 검증 및 린팅 (linting)을 수행합니다.

최적의 API 활용

news.ycombinator.com을 스크래핑하는 대신, 이 CLI는 두 개의 공식 엔드포인트와 직접 통신합니다:

1. Firebase Hacker News REST API: top/new/ask 스토리의 실시간 ID 및 아이템 상세 정보를 가져오는 데 이상적입니다.
2. Algolia Hacker News Search API: 텍스트 관련성 또는 날짜별로 기사를 쿼리하는 데 완벽합니다.

4. hn-cli의 주요 엔지니어링 패턴

이 CLI가 자율 에이전트(autonomous agent) 실행에 적합하도록, 코드베이스는 세 가지 핵심 패턴인 동시성 (Concurrency), 회복 탄력성 (Resiliency), 그리고 **결정론 (Determinism)**을 구현합니다.

A. Promise.all을 이용한 동시성 (Concurrency)

Hacker News Firebase API는 개별 아이템 엔드포인트의 집합으로 구성되어 있습니다. 상위 30개의 스토리를 가져오려면 다음 과정을 거쳐야 합니다:

1. 상위 500개 스토리 ID 목록을 가져옵니다 (HTTP 호출 1회).
2. 처음 30개 ID에 대한 메타데이터를 가져옵니다 (개별 HTTP 호출 30회).

이를 순차적으로 수행하면 심각한 지연 시간(30 × 100ms = 3초)이 발생합니다. 대신, hn-cli는 Promise.all을 사용하여 이를 동시에 가져옵니다:

const storyIds = await fetchJson('https://hacker-news.firebaseio.com/v0/topstories.json');
const idsToFetch = storyIds.slice(0, limit);
const fetchedItems = await Promise.all(
...

B. 지수 백오프 (Exponential Backoff)를 통한 회복 탄력성 (Resiliency)

AI 에이전트 실행은 비용이 많이 듭니다. 단 하나의 네트워크 패킷이 유실되거나 API 제한에 걸리더라도 에이전트가 실패해서는 안 됩니다. 우리는 fetchWithRetry 내부에 지수 백오프 (exponential backoff)를 적용한 견고한 재시도 루프를 구축했습니다:

export async function fetchWithRetry(url, options = {}, retries = 3, backoff = 1000) {
  const timeoutMs = options.timeout || 10000;
  for (let i = 0; i < retries; i++) {
...

C. JSON Schema 검증을 통한 결정론 (Determinism)

AI 에이전트는 특정 구조의 데이터를 기대합니다. 만약 API가 누락된 필드를 반환하면, 에이전트는 정의되지 않은 동작(undefined behavior)을 겪거나 환각 (hallucination)을 일으킬 수 있습니다. hn-cli는 데이터를 stdout으로 보내기 전에 validateSchema()를 사용하여 엄격한 스키마 검사를 강제합니다:

export function validateSchema(data, schema) {
  const items = Array.isArray(data) ? data : [data];
  for (const item of items) {
...

5. 구현 코드 상세 분석

WebCMD 어댑터가 어떻게 등록되는지 살펴보겠습니다. 아래는 메타데이터와 실행 루틴(execution routine)을 정의하는 방법을 보여주는 top.js의 간소화된 구현 예시입니다.

명령어 정의 (Defining the Command)

import { cli, Strategy } from '@agentrhq/webcmd/registry';
import { fetchJson, getRelativeTime, handleOutput, validateSchema, validatePositiveInt } from './utils.js';

...

6. 벤치마크: Headless Browser vs. WebCMD

우리는 news.ycombinator.com을 로드하고 스크래핑하는 Headless Chrome 스크래퍼 (Puppeteer)와 WebCMD CLI (hn-cli)의 성능을 비교하는 벤치마크를 수행했습니다.

지연 시간(Latency) 및 실행 속도

토큰 소비 (컨텍스트 효율성)

에이전트가 웹 콘텐츠를 읽을 때, 모든 문자는 LLM API 비용으로 직결됩니다.

[!TIP]
HTML 태그, 스크립트, 레이아웃 지시어 및 UI 크롬 (UI chrome)을 제거함으로써, LLM에 구조화된 키(structured keys)만 제공하여 컨텍스트 윈도우 (context window) 가용성을 극대화하고 추론 속도를 높일 수 있습니다.

7. CLI 확장하기: 커스텀 명령어 추가

hn-cli의 강점 중 하나는 간단한 확장성입니다. Hacker News에서 "최고(best)"의 스토리(별도의 엔드포인트)를 가져오는 명령어를 추가하려면 다음과 같이 합니다.

1. adapters/best.js 파일 생성:

   import { cli, Strategy } from '@agentrhq/webcmd/registry';
   import { fetchJson, getRelativeTime, handleOutput, validateSchema, validatePositiveInt } from './utils.js';

...

1. scripts/install-adapters.js에서 **업데이트 등록 (Update registration)**을 수행하여 새 파일이 WebCMD의 활성 어댑터 디렉토리(active adapter directory)로 복사되도록 합니다:

   const FILES_TO_COPY = ['top.js', 'newest.js', 'ask.js', 'jobs.js', 'item.js', 'search.js', 'best.js', 'utils.js'];

1. 업데이트 배포 (Deploy the update):

   npm run register

이제 webcmd hn best --limit 10 명령어를 통해 전역적으로 사용할 수 있습니다.

8. 결론 (Conclusion)

AI 에이전트(AI agents)가 소프트웨어 엔지니어링과 자동화의 핵심적인 부분이 됨에 따라, 우리는 오직 인간의 눈만을 위해 설계된 웹사이트를 구축하는 것에서 벗어나 **에이전트 친화적인 API 인터페이스 (agent-friendly API interfaces)**를 노출하는 방식으로 전환해야 합니다.

WebCMD 패러다임을 활용하여 hn-cli를 구축함으로써, 우리는 헤드리스 브라우저 (headless browsers)의 성능 및 리소스 비용(tax)을 완전히 우회하는 것이 가능하다는 것을 입증했습니다. 네이티브 노드 어댑터 (native node adapters), 동시 API 페칭 (concurrent API fetching), 강력한 스키마 검사 (robust schema checking), 그리고 구조화된 JSON 결과물을 사용하여 인터페이스를 구축하면 다음과 같은 이점을 얻을 수 있습니다:

• 매우 빠른 실행 속도 (200ms 미만)
• 무시할 수 있는 수준의 리소스 사용량
• LLM을 위한 막대한 토큰 절약
• 시각적 레이아웃 업데이트에도 절대 깨지지 않는 결정론적 결과 (Deterministic results)

AI 에이전트를 위한 웹 상호작용의 미래는 인간의 커서 클릭을 모방하는 것이 아니라, 개발자 친화적인 커맨드 라인 어댑터 (command-line adapters)를 표준화하는 데 있습니다.

Antigravity Agent 개발. 소스 코드는 다음 저장소에서 MIT 라이선스 하에 사용할 수 있습니다: https://github.com/scha54/hn-cli