SaaS를 AI 에이전트용 '스킬'로 전환하기: Lessie AI 구축 사례

커뮤니티 반응

대체로 매우 긍정적이며, 특히 SKILL.md 개념과 stdout 분리 원칙에 대해 실무적이고 통찰력 있다는 평가가 많다.

주요 논점

01찬성다수

SaaS의 중심이 GUI에서 에이전트가 조작 가능한 실행 레이어로 이동할 것이며, 이를 위해 MCP와 CLI 최적화가 필수적이다.

합의점 vs 논쟁점

합의점

에이전트에게는 인간용 대시보드보다 명확한 데이터 인터페이스가 더 효율적이다.
에이전트의 오작동을 막기 위해 출력 형식의 엄격한 관리가 필요하다.

실용적 조언

에이전트용 CLI를 만들 때 JSON 출력 외의 모든 로그는 stderr로 출력하라.
에이전트가 참고할 수 있는 SKILL.md 파일을 작성하여 도구 사용의 우선순위와 주의사항을 명시하라.
비용이 드는 API 호출 전에는 반드시 사용자 확인 단계를 거치도록 에이전트에게 지시하라.

섹션별 상세

AI 에이전트의 안정적인 파싱을 위해 표준 출력(stdout)의 순수성을 유지해야 한다. 에이전트는 텍스트를 훑어보는 것이 아니라 엄격하게 파싱하므로, '서버 연결 중...'과 같은 상태 메시지가 데이터와 섞이면 JSON 파싱 오류가 발생한다. 실제 구현에서 모든 데이터는 stdout으로, 상태 및 에러 메시지는 stderr로 철저히 분리하여 에이전트의 오작동을 방지했다. 이러한 설계는 에이전트가 CLI 도구를 신뢰할 수 있는 데이터 소스로 인식하게 만드는 핵심 요소이다.

typescript

export function outputJSON(data: unknown): void {
  const json = prettyMode ? JSON.stringify(data, null, 2) : JSON.stringify(data);
  process.stdout.write(json + "
");
}

export function info(msg: string): void {
  process.stderr.write(msg + "
"); // status -> stderr
}

export function fatal(msg: string, hint?: string): never {
  process.stderr.write(`Error: ${msg}
`);
  if (hint) process.stderr.write(`  ${hint}
`);
  process.exit(1);
}

에이전트의 파싱 오류를 방지하기 위해 데이터는 stdout으로, 로그와 에러는 stderr로 분리하여 출력하는 로직

SKILL.md는 단순한 API 문서가 아니라 에이전트를 위한 '행동 계약서' 역할을 한다. 에이전트는 MCP 스키마를 통해 도구의 입출력은 이해하지만, 언제 어떤 도구를 써야 할지나 비용이 발생하는 작업을 실행하기 전 확인을 구해야 한다는 등의 운영적 판단력은 부족하다. SKILL.md에 모드 감지 로직, 크레딧 비용 고지 의무, 단계별 워크플로(SOP)를 명시함으로써 에이전트가 자율적이면서도 안전하게 작동하도록 제어한다. 이는 에이전트가 무분별하게 API를 호출하여 자원을 낭비하는 문제를 해결한다.

python

mcp = FastMCP("Lessie", auth=JWTVerifier(public_key=OAUTH_JWT_SECRET, algorithm="HS256"), 
              instructions=("Lessie is an AI-powered people search, qualification, "
                            "and enrichment agent."),)

MCP_CREDITS_FIND_PEOPLE = 20
MCP_CREDITS_PER_PERSON = 1

FastMCP를 사용하여 인증 및 크레딧 제한 기능이 포함된 MCP 서버를 구축하는 예시

검색 전 개체 모호성 해소(Disambiguation) 절차를 통해 불필요한 비용 소모를 줄인다. 사용자가 특정 회사 이름을 언급했을 때 에이전트가 임의로 판단하여 검색을 실행하면 잘못된 결과에 크레딧을 낭비하게 된다. SKILL.md에 '모호한 경우 반드시 사용자에게 확인하거나 가정을 밝힐 것'이라는 지침을 추가한 결과, 잘못된 검색으로 인한 자원 낭비가 거의 0에 수렴했다. 에이전트 시스템에서 모호성 해소는 단순한 UX 개선이 아니라 실질적인 리소스 최적화 전략이다.

에이전트용 도구 설계 시 실패에 대비한 탈출구(Escape Hatch) 마련이 필수적이다. 특정 단축 명령어가 서버 스키마와 일치하지 않아 에러가 발생할 경우, 에이전트가 동일한 명령을 반복하며 루프에 빠지는 현상이 발견됐다. 이를 해결하기 위해 단축 명령 실패 시 원시 도구를 직접 호출하는 'lessie call'과 같은 범용 명령어로 폴백(Fallback)하는 로직을 구축했다. 에이전트가 스스로 오류를 인지하고 전략을 수정할 수 있는 경로를 제공하는 것이 시스템의 회복탄력성을 결정한다.

용어 해설

모델 컨텍스트 프로토콜(Model Context Protocol (MCP)): — AI 모델이 외부 도구, 데이터셋 및 서비스와 안전하고 표준화된 방식으로 상호작용할 수 있도록 Anthropic에서 공개한 개방형 프로토콜이다. 클라이언트와 서버 간의 통신 규약을 정의하여 에이전트가 실시간으로 데이터를 조회하거나 기능을 실행할 수 있게 한다.
표준 출력 순수성(stdout Purity): — 프로그램의 표준 출력(stdout)에 기계가 읽을 수 있는 데이터(JSON 등)만 출력하고, 상태 메시지나 에러는 표준 에러(stderr)로 분리하는 설계 원칙이다. AI 에이전트가 출력을 파싱할 때 불필요한 텍스트로 인해 발생하는 오류를 방지하는 데 필수적이다.
스킬 정의 파일(SKILL.md): — AI 에이전트에게 특정 도구의 사용 방법, 워크플로 순서, 비용 관리 정책 등 운영상의 판단 기준을 전달하는 가이드 문서이다. 단순한 API 명세서를 넘어 에이전트가 상황에 맞게 도구를 조합하고 실행할 수 있도록 '행동 지침'을 제공한다.
개체 모호성 해소(Entity Disambiguation): — 이름이 비슷하거나 중복되는 여러 대상 중 사용자가 의도한 정확한 개체를 식별해내는 과정이다. 에이전트 환경에서는 잘못된 대상에 자원을 소모하는 것을 방지하기 위해 실행 전 사용자에게 확인을 구하는 등의 절차가 포함된다.

언급된 도구

FastMCP추천

Python 기반의 MCP 서버 구축 프레임워크

Claude Code추천

Anthropic의 AI 코딩 에이전트

Lessie AI추천

에이전트 기반 인물 검색 및 데이터 보강 플랫폼

언급된 리소스

GitHubLessie AI CLI (npm)

API DocsModel Context Protocol (MCP) SDK