AI 에이전트에게 헛소리를 주지 마세요: MOJ 변환기에 API 도입
Source: Dev.to
🤖 The “Unstructured” Problem
우리는 AI 에이전트의 황금기에 살고 있습니다. 에이전트에게 항공편 예약, 인프라 관리, 서드파티 서비스와의 상호작용을 시키고 싶지만, 큰 병목 현상이 있습니다: 컨텍스트.
LLM 기반 AI 에이전트는 굉장히 똑똑하지만 인간과 마찬가지로 정보 과부하에 취약합니다.
표준 API 문서 페이지(예: Swagger UI 또는 Postman Documenter)를 에이전트에게 가리키면, 에이전트에게 다음을 요구하게 됩니다:
- HTML 레이아웃 파싱
- 네비게이션 바, 푸터, CSS 무시
- 어떤 엔드포인트가 관련 있는지 파악
- 흩어져 있는 파라미터와 스키마를 조합
비효율적이고 토큰을 많이 소모합니다. 그리고 종종 에이전트가 길을 잃게 됩니다.
💡 Agents Crave Structure
블로그 포스트나 전자상거래 사이트처럼 콘텐츠 자체가 가치인 경우와 달리, API 문서는 데이터 구조가 핵심입니다. 에이전트는 “우리 API는 얼마나 쉬운가” 같은 마케팅 문구가 필요하지 않습니다. 그들이 필요로 하는 것은:
- Path:
/v1/users - Method:
POST - Params:
{ "name": "string" }
에이전트는 구조화된 데이터(JSON)를 본능적으로 이해합니다. 그렇다면 왜 HTML을 먹여야 할까요?
🛠 Solving It: API Doc to JSON
에이전트를 신뢰할 수 있게 만들고 싶다면, 인간이 읽는 문서와 기계가 이해하는 사이에 번역 레이어가 필요하다는 것을 깨달았습니다.
그래서 @antigravity와 함께 API to MOJ Converter 를 만들었습니다.
What is MOJ?
Machine‑Optimized JSON. 인간 가독성보다 구조적 예측 가능성을 우선시하는, 토큰 효율적인 경량 포맷입니다.
Key Features
- ⚡️ Universal Ingestion: Swagger/OpenAPI(v2, v3)와 공개 Postman Collections을 지원합니다.
- 🔍 Deep Scraping: 숨겨진
swagger-config.json이나 중첩된 Postman API 호출 등 기본 설정을 찾아내어 복잡성을 대신 처리합니다. - 🛡 Type Safety: 복잡한 중첩 스키마를 평탄하고 예측 가능한 타입 정의로 단순화해 LLM이 쉽게 생성할 수 있게 합니다.
- 🎨 Developer Experience: VS Code의 엔진인 Monaco Editor를 사용한 세련된 다크 모드 UI로 실시간 검증을 제공합니다.
🏗 The Stack
Next.js 14, TailwindCSS, TypeScript 로 구축되었습니다.
가장 흥미로운 기술적 도전 중 하나는 Ingestion Engine이었습니다. Swagger UI는 종종 동적으로 렌더링되는 싱글 페이지 앱(SPA)입니다. 우리는 다음 과정을 수행하는 견고한 스크래퍼를 만들었습니다:
- HTML을 가져옴
swagger-initializer.js같은 식별 스크립트를 파싱- 실제 OpenAPI 스펙을 찾을 때까지 구성 URL을 재귀적으로 해결
Postman의 경우, 공개 문서 페이지 구조를 역공학하여 게이트웨이 API에서 바로 원시 컬렉션 JSON을 가져오도록 했습니다. 이를 통해 무거운 클라이언트‑사이드 렌더링을 우회했습니다.
🚀 What’s Next?
현재는 웹 도구이며, 비전은 더 큽니다.
우리는 Converter API를 구축 중입니다. 문서 URL을 POST 요청으로 보내면 깨끗한 MOJ JSON을 즉시 반환받을 수 있습니다. 이를 LangChain이나 AutoGPT 파이프라인에 바로 연결해 에이전트가 실시간으로 API를 “학습”하도록 할 수 있습니다.
👋 Try It Out
도구는 라이브이며 무료로 사용할 수 있습니다:
👉 https://apidoctojson.vercel.app
가장 좋아하는 문서 링크로 한 번 시도해보고, 에이전트가 더 똑똑하게 일하도록 도움이 되는지 알려 주세요!