plugsuits: Vercel AI SDK로 만드는 가벼운 에이전트 하네스

에반게리온에서 플러그슈트는 파일럿과 에반게리온을 연결하는 신경 인터페이스다. 꽉 끼는 슈트, 최소한의 필수 장비. 없으면 동기화가 안 된다.

plugsuits는 AI 에이전트에 같은 접근을 적용한다. LLM과 코드 편집, 파일 조작, 쉘 실행 도구를 연결하는 가벼운 TypeScript 하네스. 필요한 것만, 불필요한 건 없다.

왜 plugsuits인가?

프레임워크 과부하 없이

많은 AI 에이전트 프레임워크가 있다. 하지만:

추상화가 너무 많다
오버헤드가 크다
“프레임워크 세금”을 낸다

plugsuits는 다르다:

No framework overhead. No abstraction tax. Just the interface between model and tools.

Vercel AI SDK 기반

Vercel AI SDK의 통합 프로바이더 생태계를 활용한다. 어떤 모델이든, 어떤 프로바이더든 드롭인 가능하다.

기본은 FriendliAI지만, OpenAI, Anthropic, Google 등 원하는 대로 교체할 수 있다.

핵심 기능

1. Hashline Edit Engine

파일 편집의 가장 큰 문제는 “어디를 수정할지” 찾는 것이다. 줄 번호는 변한다. 정규식은 불안정하다.

plugsuits는 hashline 방식을 쓴다:

해시로 검증된 라인 앵커
결정론적 편집
자동 수정 (autocorrect)

// 예: 특정 라인을 해시로 찾아서 수정
edit_file({
  path: "src/index.ts",
  anchor: "// hash: a1b2c3d",
  newContent: "const x = 42;"
})

2. 인터랙티브 TUI

풀 터미널 UI:

스트리밍 출력
문법 하이라이팅
런타임 모델 전환

$ pnpm dev

Chat with AI (model: LGAI-EXAONE/K-EXAONE-236B-A23B)
Use '/help' for commands, 'ctrl-c' to quit

You: what files are in the src directory?
tool: read_file({"path":"src"})
AI: Here's what's in the src directory...

3. 헤드리스 모드

CI/CD, 벤치마크, 자동화를 위한 JSONL 스트리밍:

pnpm run headless -- "Fix the type error in src/index.ts"

구조화된 이벤트 출력 (user, tool_call, tool_result, assistant, error).

4. 도구 하네스

배터리 포함:

도구	설명
`read_file`	파일/디렉토리 읽기
`edit_file`	Hashline 기반 편집
`write_file`	새 파일 생성
`delete_file`	파일 삭제
`glob`	패턴 매칭 파일 검색
`grep`	내용 검색
`shell_execute`	쉘 명령 실행
`shell_interact`	대화형 쉘

5. Repair Escalation

약한 모델을 위한 점진적 에러 복구:

validate → 기본 검증
auto-repair → 자동 수정 시도
lenient fallback → 관대한 폴백

모델이 실수해도 복구할 수 있다.

아키텍처

Monorepo 구조

plugsuits/
├── packages/
│   ├── harness/     # 재사용 가능한 에이전트 하네스
│   │   └── src/     # 코어 루프, 메시지 히스토리, 도구 관리
│   │
│   └── cea/         # 코드 편집 에이전트 구현
│       ├── src/
│       │   ├── entrypoints/   # CLI + headless 런타임
│       │   ├── tools/         # modify / explore / execute
│       │   └── interaction/   # TUI 렌더러, 스트리밍
│       └── benchmark/         # terminal-bench 어댑터
│
└── scripts/         # 벤치마크 및 테스트 자동화

패키지 분리

패키지	설명
`@ai-sdk-tool/harness`	모델 독립적 루프, 도구 관리, 메시지 히스토리
`@ai-sdk-tool/cea`	TUI, 도구, FriendliAI 통합 완제품

이 분리 덕분에 하네스를 가져다가 자신만의 에이전트를 만들 수 있다.

시작하기

요구사항

Node.js >= 22
pnpm >= 10
FriendliAI 토큰 (또는 다른 Vercel AI SDK 호환 프로바이더)

빠른 시작

export FRIENDLI_TOKEN=your_token_here
pnpm dlx plugsuits

소스에서 실행

git clone https://github.com/minpeter/plugsuits.git
cd plugsuits
pnpm install
pnpm dev

명령어

명령	설명
`/help`	도움말
`/clear`	대화 초기화
`/model`	모델 전환
`/reasoning`	추론 모드 토글
`/translate`	번역 모드 토글
`/quit`	종료

개발

pnpm install      # 의존성 설치
pnpm dev          # 인터랙티브 TUI
pnpm run headless # 헤드리스 모드
pnpm test         # 테스트
pnpm run typecheck # 타입 체크
pnpm run lint     # 린트
pnpm run build    # 빌드

기술 스택

Vercel AI SDK — 모델 프로바이더 추상화
FriendliAI — 기본 모델 프로바이더
pnpm — 워크스페이스 매니저
Turborepo — 태스크 오케스트레이션
TypeScript — strict 모드

언제 쓸까?

자신만의 에이전트 만들기

@ai-sdk-tool/harness를 가져다가:

커스텀 도구 추가
특정 워크플로우 최적화
자체 UI 붙이기

벤치마크 및 테스트

헤드리스 모드로:

모델 성능 비교
자동화 테스트 파이프라인
CI/CD 통합

학습과 실험

깔끔한 아키텍처로:

AI 에이전트 구조 학습
새로운 접근 실험
프로토타이핑

마치며: 최소한의 인터페이스

plugsuits는 화려한 프레임워크가 아니다. 하네스다. 모델과 도구 사이의 인터페이스.

에반게리온의 플러그슈트처럼:

꽉 맞는다 — 필요한 것만
최소하다 — 필수 장비만
필수적이다 — 없으면 동기화가 안 된다

“Plug and go, native like a suit” — 이 한마디가 전부다.

🔗 관련 정보

GitHub: https://github.com/minpeter/plugsuits
Vercel AI SDK: https://sdk.vercel.ai
FriendliAI: https://friendli.ai
작성자: minpeter
라이선스: MIT