swarma -- 에이전트 팀을 위한 성장 실험 루프

이 스킬을 사용해야 할 때

사용자가 다음과 같은 목표를 가질 때 스웜마를 사용하세요:

성장 실험 실행 (훅, 랜딩 페이지, 아웃리치, 가격, 활성화, 리텐션)
단순 실행이 아닌 A/B 테스트를 통해 학습하고 개선하는 에이전트 팀 구축
특정 잠재고객/제품에 실제로 효과가 있는 검증된 플레이북 확보
아이디어 대규모 테스트 (주 2-5회 대신 50회 이상)
"그거 해봤는데 안 통하더라"를 기록, 분석, 검색 가능한 실험 데이터로 대체

트리거 문구: "뭐가 효과 있는지 테스트", "퍼널 최적화", "최고의 훅 찾기", "실험 실행", "A/B 테스트", "뭐가 통하는지", "플레이북 만들기", "성장 실험", "전환율 개선"

사용하지 말아야 할 때: 워크플로우 자동화(n8n/Make 사용), 대화 메모리(honcho 사용), 일회성 에이전트 파이프라인(CrewAI/AutoGen 사용). 스웜마는 시간이 지남에 따라 개선되는 실험 루프에 특화되어 있습니다.

빠른 참조

명령어 한눈에 보기

명령어	기능	사용 시점
`swarma init`	인스턴스 + 시작 팀 생성	최초 설정
`swarma cycle <team>`	실험 사이클 한 번 실행	테스트, 수동 실행
`swarma cycle <team> --topic "..."`	특정 주제로 사이클 실행	임시 실험
`swarma team create <name> --from-goal "..."`	목표로부터 팀 생성	새로운 실험 영역 시작
`swarma team show <name>`	팀 설정 확인	생성된 내용 검토
`swarma team list`	모든 팀 표시	개요
`swarma status`	비용, 최근 실행, 실험	상태 점검
`swarma metric log <team> <agent> <value>`	외부 메트릭 기록	실제 데이터 반영
`swarma metric import <team> <csv>`	메트릭 대량 가져오기	배치 데이터 수집
`swarma metric show <team>`	기록된 메트릭 조회	성과 검토
`swarma serve --port 8282`	REST API 시작	외부 통합
`swarma serve --mcp`	MCP 서버 시작	Claude Code / Hermes 통합
`swarma run`	스케줄 엔진 시작	지속적 운영
`swarma expert list`	추론 렌즈 탐색	전문가 프레임워크 살펴보기

결정: 어떤 스쿼드 템플릿?

사용자가 개선하려는 것	이 스쿼드 사용	AARRR 단계
오프닝 라인 / 훅	`hook-lab`	획득
랜딩 페이지 카피	`landing-lab`	획득
SEO 순위	`seo-engine`	획득
콜드 아웃리치 응답률	`cold-outbound`	획득
멀티 플랫폼 콘텐츠	`channel-mix`	획득
가입-가치 온보딩	`activation-flow`	활성화
가격 및 패키징	`pricing-lab`	수익
이탈 및 리텐션	`retention-squad`	리텐션
바이럴 루프 및 추천	`referral-engine`	추천
시장 포지셔닝	`competitive-intel`	--
숏폼 비디오 파이프라인	`faceless-factory`	획득
광고 크리에이티브 테스트	`ad-creative-lab`	획득
UGC 콘텐츠 시뮬레이션	`ugc-factory`	획득
프로그래매틱 SEO	`programmatic-seo`	획득
뉴스레터 성장	`newsletter-engine`	리텐션
유료 + 유기 루프	`acquisition-squad`	획득
커뮤니티 주도 성장	`community-engine`	리텐션
AI 상거래 최적화	`agentic-storefront`	수익

결정: 생성 vs 템플릿?

상황	접근법
사용자가 구체적이고 명확한 목표를 가짐	`swarma team create --from-goal` (AI가 팀 설계)
목표가 기존 스쿼드 템플릿과 일치	템플릿 복사 후 커스터마이징
사용자가 폭넓게 실험하려 함	`hook-lab`으로 시작 (가장 일반적)
사용자가 어디서 시작할지 모름	퍼널 병목 현상을 물어본 후 선택

GROWS 루프 (핵심 개념)

모든 실험 사이클은 다섯 단계를 따릅니다:

  가설 생성       실행         신호 관찰       평가        축적
  Generate --> Run --> Observe --> Weigh --> Stack
     ^                                                  |
     └──────────────────────────────────────────────────┘

단계	내용	코드 위치
G -- 가설 생성(Generate)	에이전트가 strategy.md를 읽고 가설 제안	`core/cycle.py`
R -- 실행(Run)	에이전트가 가설을 활성화하여 실행, 결과물 생성	`flow/executor.py`
O -- 신호 관찰(Observe)	별도의 저비용 LLM이 결과물을 점수화(1-10, 소수점 강제)	`core/agent.py`
W -- 평가(Weigh)	5사이클 후, 평균 대비 기준선 비교. >20% = 유지/폐기	`core/experiment.py`
S -- 축적(Stack)	검증된 패턴을 strategy.md + 플레이북에 기록	`core/agent.py`

주요 지표:

평가 임계값: 유지는 20% 개선, 폐기는 20% 하락
기본 최소 샘플 크기: 평가 전 5사이클
점수: 1-10 척도, 소수점 강제 (7.3, 7 아님)

설정 가이드

플랫폼: Claude Code / Claude Desktop

pip install swarma
swarma init

.mcp.json에 추가:

{
  "mcpServers": {
    "swarma": {
      "command": "swarma",
      "args": ["serve", "--mcp"],
      "env": { "OPENROUTER_API_KEY": "sk-or-..." }
    }
  }
}

중요: OPENROUTER_API_KEY는 MCP env 블록에 있어야 합니다. 하위 프로세스는 인스턴스 .env를 상속받지 않습니다.

플랫폼: Hermes (터미널)

Hermes는 터미널 접근 권한이 있어 swarma CLI 명령어를 직접 실행할 수 있습니다. MCP가 필요하지 않습니다.

pip install swarma
swarma init

그런 다음 Hermes에게 지시: "swarma cycle hook-lab --topic 'AI 에이전트는 과대평가되었나' 실행해"

Hermes는 터미널 출력을 읽고 결과에 따라 행동합니다. 구조적 접근을 위해 MCP 추가:

# hermes config.yaml
mcp_servers:
  swarma:
    transport: stdio
    command: swarma
    args: ["serve", "--mcp"]
    env:
      OPENROUTER_API_KEY: "sk-or-..."

플랫폼: OpenClaw

pip install swarma
swarma init

OpenClaw 설정에 따라 MCP 도구로 구성하거나 터미널 접근을 사용하세요.

플랫폼: CLI (독립형)

pip install swarma
swarma init                                        # 인스턴스 + 시작 팀 생성
swarma cycle starter --topic "왜 스타트업은 실패할까"   # 한 사이클 실행
swarma status                                      # 비용, 실행, 실험 확인

소스에서

git clone https://github.com/glitch-rabin/swarma.git
cd swarma && pip install -e .
swarma init

환경 설정

swarma init 후, API 키 추가:

echo "OPENROUTER_API_KEY=sk-or-..." >> ~/.swarma/instances/default/.env

키는 openrouter.ai/keys에서 받으세요.

선택 사항 (팀 간 지식 공유용):

# 3개 이상 팀 실행 시에만 필요
 echo "QMD_ENDPOINT=http://localhost:8181/mcp" >> ~/.swarma/instances/default/.env

온보딩 흐름

사용자가 swarma를 설정하려고 할 때, 다음 순서를 따르세요. 팀 생성기가 가장 빠른 경로입니다. 사용자가 수동으로 에이전트를 구성하도록 하지 마세요.

1단계: 목표 이해

물어보세요:

"무엇을 개선하고 싶나요?" (전환, 참여, 아웃리치 응답률, SEO 순위 등)
"잠재고객은 누구인가요?" (B2B SaaS 사용자, 암호화폐 커뮤니티, 기업 구매자 등)
"성공은 어떻게 정의하나요?" (더 많은 가입, 높은 CTR, 더 나은 답장률 등)

2단계: 설치

pip install swarma
swarma init --yes

3단계: 팀 생성

이것이 핵심 단계입니다. 템플릿을 고르는 대신 팀 생성기를 사용하세요.

swarma team create growth-lab \
  --from-goal "B2B SaaS 랜딩 페이지 전환율 최적화" \
  --context "개발자 도구 회사, 무료 사용자 500명, 유료 전환 2%" \
  --budget 30

생성기는:

팀 설계 (특정 역할을 가진 2-5명의 에이전트)
각 역할에 맞는 모델 선택
에이전트 지침 및 실험 패턴 작성
즉시 실행 가능한 첫 번째 실험 가설 생성

생성된 내용 확인:

swarma team show growth-lab

4단계: 첫 번째 사이클 실행

swarma cycle growth-lab

예상 출력:

Running cycle: growth-lab
  flow: researcher -> copywriter -> judge
  agents: ['researcher', 'copywriter', 'judge']

                              Cycle: growth-lab
  Agent      Model              Cost       Output Preview
  researcher sonar-pro          $0.000384  **주제:** 임원진의 52%가...
  copywriter qwen3.5-plus-02-15 $0.000746  [A] 4,382개의 콜드 이메일을 발송했습니다...
  judge      mistral-nemo       $0.000416  **훅 변형:** A: "왜..."

  duration: 43.9s | total cost: $0.001546 | agents: 3

5단계: 더 많은 사이클 실행 및 검토

swarma cycle growth-lab                    # 다른 사이클 실행
swarma cycle growth-lab --topic "특정 각도"  # 주제 포함
swarma status                              # 진행 상황 확인

5사이클 후, 실험 엔진이 첫 번째 평가를 발행합니다. 전략 파일은 자동으로 진화합니다.

일상 사용법

실험 실행

# 단일 사이클
swarma cycle hook-lab

# 특정 주제 포함
swarma cycle hook-lab --topic "AI 에이전트가 상품화되고 있다"

# 지속적 (cron 스케줄이 있는 팀은 자동 실행)
swarma run

# API 서버와 함께 지속적 실행
swarma run --port 8282

실제 메트릭 입력

LLM 자체 평가는 시작용 프록시입니다. 프로덕션에서는 실제 신호를 피드백하세요:

# 단일 메트릭 기록
swarma metric log hook-lab copywriter 4.2 --metric ctr_pct

# 특정 실험에 첨부
swarma metric log hook-lab copywriter 127 --metric impressions --exp 3

# 메모 추가
swarma metric log hook-lab copywriter 5.1 --metric ctr_pct --note "링크드인 분석에서"

# CSV에서 대량 가져오기
swarma metric import hook-lab metrics.csv

# 기록된 메트릭 조회
swarma metric show hook-lab

CSV 형식: agent,value,metric_name,note

copywriter,4.2,ctr_pct,1주차
copywriter,5.1,ctr_pct,2주차
researcher,7.8,relevance_score,

스쿼드 템플릿 사용

# 템플릿을 인스턴스로 복사
cp -r "$(python -c "import swarma; print(swarma.__path__[0])")/examples/hook-lab" \
  ~/.swarma/instances/default/teams/hook-lab

# 리포지토리를 클론한 경우
cp -r examples/hook-lab ~/.swarma/instances/default/teams/hook-lab

# 실행
swarma cycle hook-lab --topic "왜 대부분의 스타트업은 실패하는가"

상태 확인

swarma status

표시: 모든 팀, 최근 실행, 비용(오늘 + 이번 달), 대기 중인 계획, 큐 통계.

MCP 도구 참조

MCP로 연결되면 다음 16개 도구를 사용할 수 있습니다:

도구	설명	매개변수
`swarma_health`	swarma가 실행 중인지 확인	--
`swarma_list_teams`	설정된 모든 팀 목록	--
`swarma_get_team`	팀 상세 정보 (에이전트, 흐름, 스케줄)	`team_id`
`swarma_list_agents`	팀의 에이전트 목록	`team_id`
`swarma_run_agent`	단일 에이전트 실행 (옵션 컨텍스트 포함)	`team_id`, `agent_id`, `context?`
`swarma_run_cycle`	팀의 전체 사이클 실행	`team_id`, `topic?`
`swarma_status`	인스턴스 상태 (비용, 실행, 실험)	--
`swarma_costs`	비용 분석 (오늘, 이번 달)	--
`swarma_list_plans`	보류 중인 실험 계획 표시	`team_id?`
`swarma_approve_plan`	보류 중인 실험 계획 승인	`plan_id`
`swarma_reject_plan`	보류 중인 계획 거부	`plan_id`, `reason?`
`swarma_get_outputs`	에이전트의 최근 출력	`team_id?`, `agent_id?`, `limit?`
`swarma_list_tools`	사용 가능한 에이전트 도구 목록	--
`swarma_list_experts`	전문가 추론 렌즈 탐색	--
`swarma_get_expert`	ID로 전문가 상세 정보 가져오기	`expert_id`
`swarma_generate_team`	목표로부터 새 팀 생성	`name`, `goal`, `context?`, `budget?`

일반적인 MCP 워크플로우

"무슨 일이 있었나?"

swarma_status -- 개요
swarma_get_outputs -- 최근 에이전트 출력
swarma_list_plans -- 보류 중인 실험

"실험 실행"

swarma_run_cycle (team_id와 선택적 topic 포함)
swarma_get_outputs로 결과 검토

"새로운 실험 영역 시작"

swarma_generate_team (goal과 context 포함)
swarma_get_team으로 생성된 내용 검토
swarma_run_cycle로 실행 시작

"뭐가 통하고 있나?"

swarma_get_outputs로 최근 결과 확인
검증된 패턴을 위해 팀의 strategy.md 읽기

팀 설정 참조

팀은 폴더입니다. 코드가 필요하지 않습니다.

teams/my-squad/
├── team.yaml          # 목표, 흐름, 스케줄, 예산
├── program.md         # 팀 컨텍스트 및 제약 조건
└── agents/
    ├── researcher.yaml
    ├── writer.yaml
    └── strategy.md    # 사전 시드된 성장 지식 (자동 진화)

team.yaml

name: my-squad
goal: 효과적인 것을 찾아라.
flow: "researcher -> writer"        # 순차적
# flow: "researcher -> [writer, analyst]"  # 병렬
schedule: "0 8 * * 1-5"            # 선택: 평일 오전 8시
budget: 30                          # 선택: 월별 예산 (USD)

agent.yaml

id: writer
name: Writer
instructions: |
  연구를 포스트로 전환하세요. 최대 200단어.
  첫 줄에 훅을 넣으세요. 실무자의 목소리로.
model: qwen/qwen3.5-plus-02-15     # 선택: 기본 라우팅 재정의
metric:
  name: content_quality
  target: 8.0
experiment_config:
  min_sample_size: 5
  auto_propose: true

strategy.md (자동 진화)

시드 지식으로 시작하여, 검증된 모든 실험으로 성장:

### 검증된 패턴

**구체성이 승리한다**
- 구체적인 숫자가 포함된 훅은 모호한 주장보다 저장율이 2-3배 높음
- "대부분의 스타트업" 보다 "스타트업의 47%"

### 안티패턴 (폐기됨)
- 일반적인 영감을 주는 오프닝: 기준선 대비 -23%. 폐기.

### 테스트할 패턴
- [ ] 1인칭 고백 vs 3인칭 사례 연구
- [ ] 시간 기준("2024년에...") vs 시대를 초월한 훅

플로우 DSL

# 순차적: a 실행, 출력이 b로 전달
flow: "researcher -> writer"

# 병렬: a 실행 후, b와 c가 동시에 실행
flow: "researcher -> [writer, analyst]"

# 혼합:
…

[번역을 위해 일부 내용이 잘렸습니다]

즐겨 사용하는 AI에게 물어보기

문서