LLM에 HTML을 입력하며 컨텍스트를 낭비하고 있었기에, 에이전트를 위한 Markdown 변환기를 만들었습니다

AI 에이전트(AI agents), 스크래퍼(scrapers), 또는 RAG 파이프라인(RAG pipelines)을 구축하고 있다면, 다음과 같은 문제에 직면했을 것입니다. 모델에 가공되지 않은 HTML을 입력하는 것은 대부분 낭비입니다. <div>, class="...", 네비게이션(nav), 쿠키 배너 등은 당신이 원하는 콘텐츠가 아니며, 이 모든 것이 토큰(tokens) 비용을 발생시킵니다.

저는 이것이 비효율적이라는 것을 알고 있었습니다. 하지만 직접 측정해 보기 전까지는 얼마나 비효율적인지 체감하지 못했습니다. 다음은 GitHub 문서의 단일 페이지를 대상으로 수행한 감사(audit) 결과입니다:

           HTML            Markdown        Savings
───────────────────────────────────────────────────
Tokens     138,550         9,364           -93.2%
...

의미의 손실 없이 토큰의 93%가 사라졌습니다. 직관은 간단합니다. <h2>About Us</h2>는 ## About Us와 동일한 정보를 전달하지만, 읽는 데 몇 배 더 많은 비용이 듭니다. 이를 실제 페이지 전체로 확장하면, 불필요한 코드(boilerplate)가 페이로드(payload)의 대부분을 차지하게 됩니다. 스크래핑(scraping) 또는 RAG 워크로드(workload) 전반에 걸쳐, 이는 작동 가능한 비용 모델과 그렇지 않은 모델 사이의 차이를 만듭니다.

이미 존재하던 것들

무언가를 작성하기 전에, 저는 선택지들을 살펴보았습니다.

무거운 스크래퍼(Heavy scrapers). HTML을 제거하기 위해 Puppeteer나 Cheerio를 실행하는 것은 작동하지만, 둘 다 원하지 않을 수도 있는 프로젝트에 헤드리스 브라우저(headless browser)와 수많은 의존성(dependencies)을 끌어들입니다.

Cloudflare의 Markdown for Agents. Cloudflare는 에지(edge)에서 정확히 이러한 변환을 제공하며, 진정으로 훌륭합니다. 또한 그들의 유료 플랜에서는 무료이므로, 만약 당신의 사이트가 이미 Cloudflare 뒤에 있다면 다른 것은 필요하지 않을 수도 있습니다. 문제는 요구 사항 자체에 있습니다. 트래픽이 Cloudflare를 통해 흐를 때만 도움이 된다는 점입니다. 저는 제 자신의 코드 내에 존재하고, 어디서나 실행되며, 특정 네트워크가 앞에 있다고 가정하지 않는 무언가를 원했습니다. 이 라이브러리는 Cloudflare의 작업에서 영감을 얻었다고 명시하고 있는데, 그 아이디어가 거기서 나왔기 때문입니다.

제가 실제로 원했던 것은 에이전트가 요청할 때마다 다른 부수적인 것 없이 Markdown을 제공할 수 있는, 작고 프레임워크에 구애받지 않는(framework-agnostic) 방식이었습니다.

markdown-for-agents

이 메커니즘은 콘텐츠 협상 (Content Negotiation)입니다. 지루한 HTTP 기능이지만, 이 용도에는 정확히 들어맞는 기능임이 밝혀졌습니다. 일반적인 브라우저는 사이트를 방문하여 HTML을 가져옵니다. 에이전트는 Accept: text/markdown 헤더를 가지고 방문하며, 미들웨어 (Middleware)가 이 요청을 가로채서 불필요한 코드 (Boilerplate)를 제거하고 동일한 URL에서 깨끗한 마크다운 (Markdown)을 반환합니다. 별도의 엔드포인트도, 별도의 빌드도, 라우팅 (Routing)의 분기점도 필요 없습니다.

import { convert } from 'markdown-for-agents';

const { markdown, tokenEstimate } = convert(html, { extract: true });

설계 목표는 다음과 같습니다 (순서대로):

단 하나의 의존성 (One dependency). 핵심 기능은 단 하나의 HTML 파서 (Parser)에만 의존하며 그 외에는 아무것도 필요하지 않습니다. 헤드리스 브라우저 (Headless browser)나 DOM도 필요 없습니다.

어디서나 실행 가능 (Runs anywhere). Node, Bun, Deno, Cloudflare Workers, Vercel Edge, 브라우저 등 어디서든 작동합니다. 웹 표준 (Web Standards)을 따른다면 작동합니다.

Python에서도 동일한 아이디어 적용. TypeScript 패키지와 함께 의존성이 없는 Python 패키지도 제공되며, FastAPI, Flask, Django를 위한 미들웨어가 포함되어 있습니다. RAG 및 스크래핑 (Scraping) 세계의 절반은 Python 기반이며, 이를 제외하고 싶지 않았습니다.

즉시 사용 가능한 미들웨어 (Drop-in middleware). Express, Fastify, Hono, Next.js 및 모든 웹 표준 서버에서 사용할 수 있습니다. 미들웨어는 Accept 헤더를 읽고, 일반 브라우저 트래픽은 건드리지 않고 그대로 통과시키며, 에이전트가 요청할 때만 변환을 수행합니다.

설치 없이 체험해보기

감사 (Audit) 도구를 아무 URL에나 지정하여 얼마나 절약할 수 있는지 확인해 보세요:

npx @markdown-for-agents/audit https://docs.github.com/en/copilot/get-started/quickstart

또는 URL이나 원시 HTML을 플레이그라운드 (Playground)에 붙여넣어 실시간 변환 과정을 지켜보세요:

https://markdown-for-agents.vercel.app/playground

오픈 소스로 공개한 이유

제 자신의 웹사이트들이 에이전트 친화적(agent-friendly)으로 준비되기를 원했고, HTML만 제공하는 웹사이트들 때문에 제 자신의 사용량 제한 (Usage limits)이 소진되는 것을 보았기 때문에 만들었습니다. 만약 웹 콘텐츠로 인한 컨텍스트 제한 (Context limits)이나 토큰 비용 (Token costs) 문제를 겪고 있다면, 이 도구가 여러분에게도 동일한 도움을 줄 수 있을 것입니다.

코드는 여기에 있습니다: [https://github.com/KKonstantinov/markdown-for-agents](https://github.com/KKonstantinov/markdown-for-agents)