마크다운과 HTTP로 에이전트용 앱을 구축하는 오픈소스 프레임워크 'Statespace'

실용적 조언

기존의 Python이나 Bash 스크립트를 Statespace에 등록하여 에이전트가 호출 가능한 도구로 즉시 전환 가능하다.
데이터베이스 쿼리 도구 등록 시 반드시 정규표현식 제약을 사용하여 읽기 전용 권한을 강제해야 한다.

섹션별 상세

에이전트 오케스트레이션의 병목이 모델의 지능에서 상호작용 대상인 도구의 가용성으로 이동했다는 점을 지적했다. 에이전트가 웹을 통해 발견하고 즉시 호출할 수 있는 실제 앱이 필요하며, 이를 위해 복잡한 SDK나 전용 프로토콜 대신 표준 HTTP와 마크다운을 사용하는 방식을 제안했다.

Statespace의 앱 구조는 도구(Tools), 컴포넌트(Components), 지침(Instructions) 세 가지 핵심 요소로 구성된다. 도구는 sqlite3, curl, grep 같은 CLI 명령어를 HTTP POST 요청으로 매핑하며, 컴포넌트는 페이지 로드 시 실시간 데이터를 렌더링하여 에이전트에게 최신 문맥을 제공한다.

markdown

---
tools:
  - [sqlite3, store.db, { regex: "^SELECT\\b.*" }]
  - [grep, -r, { }, logs/]
---
# Support Dashboard
Query the database or search the logs.
**customers** — id, name, email, city, country, joined
**orders** — id, customer_id, product_id, quantity, ordered_at

마크다운 프론트매터를 사용하여 에이전트가 호출할 수 있는 도구와 데이터베이스 스키마 정보를 정의하는 예시

보안을 위해 정규표현식(Regex) 기반의 입력 제약 시스템을 도입했다. 예를 들어 sqlite3 도구 사용 시 'SELECT'로 시작하는 쿼리만 허용하도록 설정하여 에이전트가 의도치 않게 데이터를 삭제하거나 시스템 명령어를 실행하는 위험을 원천적으로 차단했다.

프레임워크는 7MB 크기의 단일 Rust 바이너리로 제공되어 설치와 실행이 매우 간편하다. 작성된 마크다운 페이지는 URL 형태로 공유 가능하며, Claude Code나 Cursor 같은 기존 코딩 에이전트들이 해당 URL을 통해 앱의 기능을 파악하고 도구를 실행할 수 있다.

bash

statespace serve myapp/
# or
statespace deploy myapp/

Statespace CLI를 사용하여 작성한 마크다운 앱을 로컬에서 실행하거나 배포하는 명령어

용어 해설

오케스트레이션(Orchestration): — AI 에이전트가 복잡한 목표를 달성하기 위해 여러 도구를 선택하고 실행 순서를 계획하며 오류를 수정하는 전 과정을 관리하는 기술이다. 에이전트의 지능이 높아짐에 따라 이들을 효율적으로 제어하고 실제 환경과 연결하는 오케스트레이션 레이어의 중요성이 커졌다.
도구 호출(Tool Calling): — 대규모 언어 모델(LLM)이 텍스트 생성에 그치지 않고 외부 API나 함수를 실행하기 위해 필요한 인자를 생성하고 호출하는 능력이다. 에이전트가 데이터베이스 쿼리나 파일 검색과 같은 실질적인 작업을 수행할 수 있게 만드는 핵심 메커니즘이다.
프론트매터(Frontmatter): — 마크다운 파일의 최상단에 위치하며 YAML이나 JSON 형식으로 문서의 메타데이터를 정의하는 영역이다. Statespace에서는 이 영역을 활용해 에이전트가 호출할 수 있는 CLI 도구와 보안 제약 사항을 선언적으로 정의한다.
정규표현식 제약(Regex Constraint): — 사용자나 에이전트가 입력한 값이 특정 패턴을 따르는지 검사하여 허용된 형식만 실행되도록 제한하는 보안 기법이다. 에이전트가 임의의 쉘 명령어를 실행하는 것을 방지하고 데이터베이스 쿼리 범위를 제한하는 데 필수적이다.

언급된 도구

Statespace추천링크

마크다운 기반 에이전트 앱 구축 프레임워크

sqlite3중립

에이전트가 쿼리할 수 있는 데이터베이스 도구

curl중립

에이전트가 외부 API와 통신하기 위한 도구

언급된 리소스

GitHubStatespace GitHub Repository

문서Statespace Documentation