pi 코어 위에 커스텀 도구·스킬·서브에이전트·MCP만 얹어 업무 에이전트를 만드는 오픈소스 예시입니다. "코어(루프·세션·LLM 호출)는 작게, 능력은 확장으로" 라는 pi 철학을 그대로 따릅니다.
이 저장소는 두 단계의 예제를 담고 있습니다.
| 단계 | 예제 | 보여주는 것 |
|---|---|---|
| ① 기본 골격 | 회의록 → 할 일 정리 | 커스텀 도구(확장) + 스킬 작성의 기본기 |
| ② 전용 에이전트 | 주간 리서치 브리핑 봇 | MCP 다중 연결 · 웹 근거 · 서브에이전트 병렬 · 관찰가능성 |
# 1) pi 설치 (이미 있으면 생략)
curl -fsSL https://pi.dev/install.sh | sh
# 2) 능력 확장 설치 (전용 에이전트용) — 이미 있으면 생략
pi install npm:pi-mcp-adapter # MCP 다중 연결
# 웹 검색(web_search/web_fetch)·서브에이전트(subagent)는 pi 환경에 기본 탑재됩니다.
# 3) 인증 — /login 또는 API 키 환경변수
export ANTHROPIC_API_KEY=sk-ant-...notes/의 회의록(.md)을 읽어 실행 가능한 할 일을 todo.md로 정리합니다.
에이전트 루프·세션·LLM 호출은 pi가 다 하고, 우리는 도구 3개와 스킬 1개만 작성했습니다.
| # | 요구사항 | 무엇으로 충족했나 |
|---|---|---|
| 1 | 에이전트 루프 | pi 코어가 제공 (우리가 안 짬) |
| 2 | 커스텀 도구 | extensions/work-tools.ts — pi.registerTool로 list_notes/read_note/write_todo |
| 3 | 확장·스킬 | skills/todo-briefing/SKILL.md — --skill 로드, --no-skills로 끄고 비교 |
| 4 | 관찰가능성 | pi 세션(-c/-r) 저장·재개, --mode json 트랜스크립트 |
# 기본 실행
pi -e extensions/work-tools.ts --skill skills/todo-briefing \
-p "이번 주 회의록들을 보고 할 일을 정리해서 todo.md로 만들어줘"
# [요구사항 3] 스킬 ON vs OFF 비교
pi -e extensions/work-tools.ts --no-skills \
-p "회의록 정리해서 todo.md로 저장해줘"
# [요구사항 4] 직전 세션 이어가기
pi -e extensions/work-tools.ts --skill skills/todo-briefing -c \
-p "방금 만든 todo에서 마감이 6/13인 것만 알려줘"여러 주제를 서브에이전트로 병렬 조사하고, 출처와 함께 통합한 브리핑을
MCP로 외부 시스템 2곳에 기록합니다. dedicated_agent_example.md의
전용 에이전트 채점 4요건(각 25점)을 실제로 충족합니다.
| # | 채점 기준 | 무엇으로 충족했나 |
|---|---|---|
| 1 | MCP 다중 연결 (외부 2곳 읽기/쓰기) | .mcp.json — briefing-store(파일시스템) + tracker-memory(메모리) MCP 서버 2개 |
| 2 | 웹 근거 (출처 URL) | 서브에이전트가 web_search/web_fetch로 조사, 모든 사실에 URL 첨부 |
| 3 | 서브에이전트 병렬 (분해→위임→통합) | .pi/agents/topic-researcher.md + subagent parallel 모드 |
| 4 | 시연·관찰가능성 | pi 세션 트랜스크립트 + -c/-r resume |
# 전용 에이전트 실행 (주제는 자유롭게 교체)
pi --skill skills/research-briefing \
-p "다음 주제를 리서치해 주간 브리핑을 만들어줘: (1) 트랜스포머 (2) RAG.
서브에이전트로 병렬 조사하고, briefing-store에 브리핑 파일을 쓰고
tracker-memory에 추적항목을 저장해."실행이 끝나면 파일시스템 MCP가 브리핑 .md 를, 메모리 MCP가 추적 항목을 기록합니다
(출력 디렉터리명은 에이전트가 정함 — 예: briefing-store/, tracker-memory/).
모든 사실 줄에는 — 출처: https://… 형태로 실제 출처 URL이 보존됩니다.
✅ 검증 완료 — 실제 pi v0.78.0에서 2개 주제 병렬 실행 시: 서브에이전트가
web_search/web_fetch로 라이브 조사 → 출처 URL 56개 보존 → 파일시스템·메모리 MCP 2곳 모두 기록 → 세션 JSONL(249KB) 저장까지 확인.
사용자: "이 주제들로 브리핑 만들어줘"
└─ 메인 에이전트 (skills/research-briefing) ── 오케스트레이터
│
├─ 분해: 주제 N개로 나눔
├─ subagent(parallel) ─┬─ topic-researcher A ─ web_search/fetch ─ 출처 [요구사항 2·3]
│ ├─ topic-researcher B ─ web_search/fetch ─ 출처 (병렬)
│ └─ topic-researcher C ─ ...
├─ 통합: 중복 제거 · 출처 보존 · 우선순위화
├─ mcp ─┬─ briefing-store(파일시스템): 브리핑 .md 쓰기 [요구사항 1]
│ └─ tracker-memory(메모리): 추적 항목 저장/읽기
└─ pi 세션 저장 → 다음 주 -c/-r 로 추적 이어가기 [요구사항 4]
이 저장소는 인증 없이 바로 돌아가도록 공식 MCP 서버 2개(filesystem·memory)를 씁니다.
실제 외부 SaaS로 바꾸려면 .mcp.json의 서버만 교체하면 구조는 그대로입니다.
.
├── extensions/
│ ├── work-tools.ts # ① 커스텀 도구 (회의록/할일)
│ └── package.json
├── skills/
│ ├── todo-briefing/SKILL.md # ① 기본 골격 스킬
│ └── research-briefing/SKILL.md # ② 전용 에이전트 스킬 (오케스트레이터)
├── .pi/agents/
│ └── topic-researcher.md # ② 병렬 위임용 리서치 서브에이전트
├── .mcp.json # ② MCP 서버 2개 설정 (filesystem + memory)
├── notes/ # ① 입력: 샘플 회의록
├── dedicated_agent_example.md # 전용 에이전트 과제 설명서(원본)
├── LICENSE # MIT
└── README.md
실행 산출물(
todo.md,briefings/)은.gitignore처리되어 있습니다. pi 세션은~/.pi/agent/sessions/아래에 JSONL로 저장됩니다.
같은 일을 "그냥 챗봇에 프롬프트 한 번 던지기"로 시키는 것과, 이 저장소처럼 도구·스킬·서브에이전트·MCP를 갖춘 에이전트로 시키는 것은 결과물의 성격이 다릅니다.
| 항목 | 단순 프롬프트 1개 | 우리가 만든 에이전트 |
|---|---|---|
| 데이터 접근 | 회의록을 사람이 복사·붙여넣어야 함 | list_notes/read_note 도구로 스스로 파일을 읽음 |
| 결과 저장 | 답변 텍스트만 출력 → 수동 저장 | write_todo로 todo.md에 직접 기록 |
| 일관성 | 매번 형식이 들쭉날쭉 | 스킬이 역할·출력형식을 고정 → 재현 가능 |
| 반복 작업 | 매번 사람이 프롬프트 재작성 | 같은 명령 한 줄로 자동 반복 |
| 재현·추적 | 대화창 닫으면 사라짐 | 세션 JSONL로 저장·재개(-c)·감사 |
| 항목 | 단순 프롬프트 1개 | 우리가 만든 전용 에이전트 |
|---|---|---|
| 사실 근거 | 모델 기억(학습 시점)에 의존 → 환각·옛 정보 위험 | 서브에이전트가 웹에서 라이브 조사 + 출처 URL 첨부 |
| 처리 방식 | 한 모델이 모든 주제를 순차로 처리 | 주제마다 서브에이전트 병렬 → 빠르고 컨텍스트 격리 |
| 외부 연동 | 사람이 결과를 복사해 노션/메일에 옮김 | MCP로 외부 시스템 2곳에 직접 읽기/쓰기 |
| 연속성 | 매주 처음부터 다시 | 메모리 MCP + 세션으로 지난주 대비 추적 |
| 관찰가능성 | 내부 과정 안 보임(블랙박스) | 도구 호출·서브에이전트·MCP 호출이 트랜스크립트에 다 남음 |
- 정확성 — 출처 URL 기반이라 검증 가능, 환각 감소 (단순 프롬프트는 출처 없음).
- 자동화 — 데이터 수집 → 처리 → 외부 기록까지 사람 개입 없이 한 번에.
- 확장성 — 도메인을 바꿔도 코어는 그대로, 도구·스킬·서브에이전트만 교체.
- 재현·감사 — 세션 JSONL로 "무엇을 보고 무엇을 했는지" 추적·재개 가능.
- 속도 — 독립 작업은 서브에이전트로 병렬 처리.
- 셋업 비용 — pi 설치, 확장·MCP 설정, 스킬 작성이 선행돼야 함(단순 프롬프트는 0).
- 비용·지연 — 서브에이전트·웹조사·MCP 호출이 늘면 토큰·시간이 더 든다.
- 외부 의존 — 웹/ MCP 서버가 죽으면 그 능력은 멈춘다(코어 루프는 유지).
- 비결정성 — LLM이라 도구 호출 순서·표현이 매 실행 조금씩 다를 수 있다 (그래서 스킬에 형식·규칙을 명시적으로 강제한다).
- 권한·보안 — MCP로 외부 시스템에 쓰기 권한을 주므로, 신뢰할 수 있는 설정에서만 사용.
한 줄 요약: 일회성 질문엔 단순 프롬프트가, 반복·자동화·근거·연동이 필요한 실제 업무엔 에이전트가 맞습니다.
{ "mcpServers": { "notion": { "command": "npx", "args": ["-y", "@notionhq/notion-mcp-server"], "env": { "NOTION_TOKEN": "secret_..." } }, "gmail": { "command": "npx", "args": ["-y", "@gongrzhe/server-gmail-autoauth-mcp"] } } }