Kimi K2.5 에이전트 아키텍처 완벽 해부 2편 - 도구 체계와 실행 흐름

1. 도구 체계: Base Chat vs OK Computer

Kimi의 두 핵심 에이전트는 동일한 인프라를 공유하지만, 완전히 다른 도구 세트를 가진다.

1.1 Base Chat: 9개 도구

카테고리	도구명	용도
Web	web_search	웹 검색
Web	web_open_url	URL 직접 열기
Image	search_image_by_text	텍스트로 이미지 검색
Image	search_image_by_image	이미지로 이미지 검색
Code	ipython	Jupyter 커널 코드 실행
Code	shell	비영속 셸 명령어
Data	get_data_source	외부 데이터소스 조회
Data	get_data_source_desc	데이터소스 메타데이터
Memory	memory_space_edits	사용자 기억 관리

핵심 제한:

• 턴당 최대 10 tool calls (0~3 권장)
• 다운로드 가능한 파일 생성 불가 (ipython 차트 예외)
• 파일 생성 요청 시 kimi.com/agent로 리디렉션

1.2 OK Computer: 29개 도구

OK Computer는 Base Chat의 모든 도구에 20개 추가 도구를 더한다:

Browser Automation (8개)

• browser_visit: URL 방문
• browser_click: 요소 클릭
• browser_input: 입력 필드 채우기
• browser_find: 요소 검색
• browser_scroll_up/down: 스크롤
• browser_state: 현재 상태 확인
• browser_screenshot: 스크린샷 캡처

File Operations (3개)

• read_file: 파일 읽기
• write_file: 파일 쓰기
• edit_file: 파일 부분 수정

Image/Media (6개)

• generate_image: AI 이미지 생성
• find_asset_bbox: 이미지 내 영역 찾기
• crop_and_replicate: 영역 잘라내기 및 복제
• screenshot_web_full_page: 전체 페이지 스크린샷
• get_available_voices: 사용 가능 음성 목록
• generate_speech: 음성 합성 (TTS)

Todo Management (2개)

• todo_read: 할 일 목록 읽기
• todo_write: 할 일 목록 쓰기

Deployment (1개)

• deploy_website: 웹사이트 배포 및 URL 제공

---

2. Universal Shell Pattern: 핵심 설계 철학

Kimi의 가장 중요한 아키텍처 결정 중 하나: 모든 스킬이 동일한 generic 도구를 사용한다.

Tool Layer (동일): ipython, shell, read_file, write_file, browser_*
Skill Layer (다름): DOCX SKILL.md, XLSX SKILL.md, PDF SKILL.md...

의미: Excel 검증에 사용하는 shell과 LaTeX 컴파일에 사용하는 shell은 완전히 동일한 도구다. 차이는 SKILL.md가 제공하는 컨텍스트뿐이다.

장점:

• 새 도구 개발 불필요
• 스킬 추가 = 문서 작성
• 모델이 범용 도구 사용법만 학습하면 됨

---

3. 실행 흐름 Deep Dive

각 스킬별 실제 도구 호출 순서를 상세히 분석한다.

3.1 DOCX Tool Chain

1. read_file(SKILL.md): 925줄 스킬 문서 로딩
2. read_file(Example.cs): C# 템플릿 참조
3. shell: ./docx init: 프로젝트 초기화
4. ipython: Generate Program.cs: 메타프로그래밍 - Python이 C# 코드 생성
5. shell: ./docx build:
   • dotnet build/run
   • fix_element_order.py
   • Validator (OpenXML SDK)
   • validate_docx.py
   • pandoc (최종 변환)
6. KIMI_REF 태그 포함하여 결과 반환

핵심 통찰: DOCX 생성은 메타프로그래밍이다. IPython이 C#을 생성하고, C#이 문서를 생성한다.

3.2 XLSX Tool Chain

1. read_file(SKILL.md): xlsx 스킬 문서 로딩
2. Per-Sheet Loop:
   • ipython: openpyxl로 시트 생성/수정
   • wb.save()
   • KimiXlsx recheck (77MB 바이너리)
   • reference-check
   • Error? → fix & retry
3. PivotTable: KimiXlsx pivot (⚠️ MUST be last - 다른 작업 후 깨짐 방지)
4. KimiXlsx validate: 최종 검증
5. KIMI_REF 태그 포함하여 결과 반환

핵심 통찰: XLSX는 시트별 검증 루프를 사용한다. DOCX와 달리 빌드 후 검증이 아닌 점진적 검증.

3.3 PDF Tool Chain (HTML Route)

1. read_file(SKILL.md/routes/html.md): HTML PDF 라우트 스킬 로딩
2. ipython: HTML + CSS 생성, matplotlib 차트, KaTeX 수식
3. write_file(/tmp/input.html): 중간 결과물 저장
4. shell: pdf.sh html input.html:
   • Playwright + Paged.js
   • Mermaid 다이어그램 렌더링
   • scale 1.5 적용
5. KIMI_REF 태그 포함하여 결과 반환

3.4 PDF Tool Chain (LaTeX Route)

1. read_file(SKILL.md/routes/latex.md): LaTeX PDF 라우트 스킬 로딩
2. ipython: .tex 소스 생성, 수학 표현식, .bib 참고문헌
3. write_file(/tmp/main.tex): 중간 결과물 저장
4. shell: compile_latex.py --runs 2: tectonic 2회 실행 (참조 해결)
5. KIMI_REF 태그 포함하여 결과 반환

라우트 분기: PDF 생성 시 초기에 라우트 결정. HTML(시각적 자유도)과 LaTeX(학술적 정확도) 중 선택.

3.5 WebApp Tool Chain

1. read_file(SKILL.md): webapp-building 스킬 로딩
2. shell: init-webapp.sh: 73-file 템플릿 복사, npm install (26,082 files)
3. ipython: 컴포넌트 아키텍처 계획
4. write_file(src/components/*.tsx): React 컴포넌트 생성
5. shell: npm run build: Vite 빌드
6. deploy_website(dist): Public URL 반환

---

4. 도구 시너지 패턴

단일 도구가 아닌 도구 조합으로 복잡한 작업을 수행하는 패턴:

4.1 Data Pipeline Pattern

get_data_source → ipython(pandas 분석) → write_file(CSV) → KIMI_REF
용도: 외부 데이터 조회 → 가공 → 파일 출력

4.2 Web Research Pattern

web_search → browser_visit → browser_scroll → browser_screenshot
용도: 검색 → 방문 → 탐색 → 증거 캡처

4.3 Asset Extraction Pattern

screenshot_web_full_page → find_asset_bbox → crop_and_replicate
용도: 웹페이지 캡처 → 영역 식별 → 에셋 추출

4.4 Media Production Pattern

generate_image → ipython(Pillow 편집) → write_file
용도: AI 이미지 생성 → 후처리 → 저장

---

5. 검증 시스템과 바이너리

Kimi는 품질 보증을 위해 특수 바이너리를 사용한다:

5.1 KimiXlsx (77MB)

• XLSX 검증 전용 바이너리
• openpyxl 출력 검증
• 참조 체크 (깨진 수식 탐지)
• 피벗테이블 생성

5.2 Tectonic (57MB)

• LaTeX 컴파일러
• 온라인 패키지 자동 다운로드
• 2-pass 컴파일 (참조 해결)

5.3 OpenXML SDK Validator (.NET)

• DOCX 구조 검증
• fix_element_order.py와 연동
• validate_docx.py로 최종 확인

5.4 PDF.js (4MB)

• Mozilla PDF.js Chrome 확장
• CJK 문자맵 50+ 파일
• 표준 폰트 12개

---

6. Communication Guidelines: 모델 행동 규칙

OK Computer 시스템 프롬프트에 명시된 커뮤니케이션 원칙:

6.1 Match the User (사용자에게 맞춤)

• 언어: 사용자 언어로 응답
• 깊이: 전문가에게는 기술적으로, 초보자에게는 친절하게
• 형식성: 격식/비격식 매칭

6.2 Right-size (적절한 분량)

• 단순 작업: 최소 설명, 결과에 집중
• 복잡 작업: 진행상황 공유, 선택지 제시

6.3 Show the What, Not the How (결과 보여주기)

• ❌ "web_search 도구를 사용하여..."
• ❌ "SKILL.md를 읽어서..."
• ✅ "검색 결과를 찾았습니다..."
• ✅ "문서를 생성했습니다..."

---

7. 데이터소스 우선순위

외부 데이터 접근 시 엄격한 우선순위:

7.1 First: Datasource Tools

• yahoo_finance: 금융 데이터
• ifind: 중국 금융 정보
• world_bank_open_data: 세계은행 오픈데이터
• arxiv: 학술 논문
• google_scholar: 학술 검색

7.2 Second: Web Search

데이터소스가 불충분할 때만 웹 검색 사용

7.3 Datasource 워크플로우

1. get_datasource_desc로 API 정보 확인
2. get_data_source로 데이터 조회
3. 데이터 완전 → 직접 사용
4. 데이터 불완전 → ipython으로 분석/보완

---

8. 특수 정책과 규칙

8.1 이미지 포맷 규칙

• 불투명 이미지: .jpg (사진, 스크린샷)
• 투명 이미지: .png (로고, 아이콘)

8.2 슬라이드 필수 도구

• mshtools-slides_generator 필수 사용
• HTML → PPTX 변환 파이프라인

8.3 배포 정책

• HTML 생성 시 deploy 도구로 URL 제공
• 사용자가 결과를 즉시 확인 가능하도록

8.4 KIMI_REF 태그

• 문서 생성 완료 시 마지막에 KIMI_REF 태그 포함
• 파일 추적 및 참조용

8.5 Memory 민감 정보 금지

• ❌ 인종/민족
• ❌ 건강 정보
• ❌ 위치 데이터
• ❌ 정치적 성향
• ❌ 미성년자 정보

---

9. 산업적 시사점

9.1 에이전트 설계 패러다임 전환

• Before: "모델에게 더 많은 도구를 주자"
• After: "모델에게 환경과 지식을 주자"

9.2 전문화의 새로운 방식

• Before: 도메인별 파인튜닝, 특화 도구 개발
• After: SKILL.md 문서 작성, 범용 도구 재사용

9.3 품질 보증 접근

• 객관적 작업: 검증 바이너리 (KimiXlsx, OpenXML Validator)
• 주관적 작업: 페르소나 주입 (McKinsey 컨설턴트)

9.4 확장성 모델

• 새 기능 = 새 SKILL.md 문서
• 개발 비용: 도구 개발 → 문서 작성으로 대폭 감소

---

10. 향후 전망

10.1 Skill 생태계 확장

• 커뮤니티 SKILL.md 기여
• 도메인별 스킬 마켓플레이스

10.2 Persona 라이브러리

• 다양한 전문가 페르소나
• 산업별/역할별 프리셋

10.3 Multi-Agent 연동

• Agent Swarm 아키텍처 확장
• ~100 에이전트 협업
• PARL 강화학습

---

TL;DR

• Base Chat 9개 vs OK Computer 29개 도구, 동일 인프라에서 권한 차이
• Universal Shell Pattern: 모든 스킬이 동일 도구 사용, 차이는 SKILL.md 컨텍스트
• 실행 흐름: 항상 스킬 로딩 먼저, DOCX는 메타프로그래밍, XLSX는 점진적 검증
• 도구 시너지: Data Pipeline, Web Research, Asset Extraction, Media Production 패턴
• 검증 바이너리: KimiXlsx(77MB), Tectonic(57MB), OpenXML SDK
• 커뮤니케이션 원칙: Match User, Right-size, Show What Not How
• 산업적 시사점: 도구 추가 → 문서 작성, 파인튜닝 → 스킬 주입으로 패러다임 전환

---

참고 링크

• kimi-agent-internals GitHub
• Moonshot AI 공식 사이트
• Kimi Agent Platform
• Kimi Slides Platform