ZhuLinsen/MiniAgent: 5분 만에 직접 만드는 AI 코딩 어시스턴트 + CLI 버전 Manus!

🚀 5분 만에 직접 만드는 AI 코딩 어시스턴트 + CLI 버전 Manus! | English

단 하나의 agent.py 핵심 파일로 Claude Code의 프로그래밍 능력 + Manus의 시스템 제어 능력을 복제합니다!

MiniAgent는 극도로 단순하고, 투명하며, 강력한 CLI Agent 프레임워크로, 불필요하게 비대한 의존성과 복잡한 아키텍처를 거부합니다:

• 🧠 Code Agent: Claude Code처럼 코드를 작성하고, 버그를 수정하며, 테스트를 실행합니다.
• 🦾 OS Agent: Manus처럼 브라우저를 제어하고, 문서를 편집하며, 애플리케이션을 관리합니다.
• ⚡ 극도로 단순한 구현: 핵심 엔진은 agent.py 단일 파일입니다.

완전히 투명하고 제어 가능하여 학습 및 커스텀 수정에 적합합니다. - 🤖

• 모든 모델 지원: DeepSeek, OpenAI, Claude 등 OpenAI 인터페이스와 호환되는 모든 모델 - 🔌
• 높은 확장성: 극도로 단순한 데코레이터(Decorator) 패턴을 사용하여 3줄의 코드만으로 커스텀 도구를 마운트할 수 있습니다 - 🔄
• 이중 모드 도구 호출 (Tool Calling): 텍스트 파싱 모드 (투명하고 학습 가능) + 네이티브 Function Calling 모드 (더 신뢰할 수 있음) - 🎯
• Skill 시스템: 재사용 가능한 Agent 설정으로, 내장된 coder/researcher/reviewer/tester 4가지 역할을 제공합니다 - 🛡️
• 보안 보호: 위험한 명령어를 자동으로 차단 및 확인하여, LLM의 환각 (Hallucination)으로 인한 파괴적인 동작을 방지합니다 - 💬
• 스트리밍 출력 (Streaming Output): 타이핑 효과로 실시간 출력되며, 긴 대화는 컨텍스트를 자동으로 압축합니다 - 🔗
• MCP 프로토콜: MCP 도구 서버 연결을 지원하여 커뮤니티 생태계에 접속할 수 있습니다 - 🤝
• Agent 오케스트레이션 (Orchestration): 내장된 오케스트레이터를 통해 작업 분해(Task Decomposition) 및 다중 역할 협업을 지원합니다.

비교 항목	MiniAgent	smolagents	pydantic-ai	LangChain
핵심 포지셔닝	CLI Agent 교과서	HuggingFace 생태계	엔터프라이즈급 타입 안정성	만능 프레임워크
핵심 코드	단일 파일 가독성	~1,000행	182MB	10만+행
도구 호출	텍스트 파싱 + 네이티브 FC	Code Agent	네이티브 FC	다층 추상화
학습 곡선	⭐ 30분이면 숙달	⭐⭐	⭐⭐⭐	⭐⭐⭐⭐⭐
의존성 (Dependencies)	7개	~20개	~15개	50+
OS 제어	bash 만능	확장 필요	확장 필요	플러그인 필요

MiniAgent의 독보적인 가치: 최고의 AI Agent 교과서. 마법도 없고, 과도한 추상화도 없기에 초보자도 Agent가 어떻게 작동하는지 완전히 이해할 수 있습니다.

MiniAgent는 100개의 도구를 내장하는 대신, 6개의 코드 도구와 bash를 사용하여 무한한 가능성을 구현합니다.

• 스크린샷이 필요하다면? LLM은 다음과 같이 실행합니다:
  bash: python -c "from mss import mss; mss().shot()"

• 마우스를 제어해야 한다면? LLM은 다음과 같이 실행합니다:
  bash: python -c "import pyautogui; pyautogui.click(100,200)"

• 웹 페이지를 크롤링해야 한다면? LLM은 다음과 같이 실행합니다:
  bash: curl ... | python -c "..."

이것이 바로 미니멀리즘의 힘입니다: LLM이 가장 잘하는 일, 즉 사고하고 조합하는 것에 집중하게 만듭니다.

git clone https://github.com/ZhuLinsen/MiniAgent.git && cd MiniAgent
pip install -r requirements.txt && pip install -e .
cp .env.example .env # 자신의 API Key를 입력하세요
...

📋 상세 설치 안내

git clone https://github.com/ZhuLinsen/MiniAgent.git
cd MiniAgent
pip install -r requirements.txt
...

.env 파일 생성 (.env.example 참고):

LLM_API_KEY=your_api_key_here
LLM_MODEL=deepseek-chat
LLM_API_BASE=https://api.deepseek.com/v1

실행: miniagent (또는 python -m miniagent)

you: hello.py 파일을 만들어줘
● write hello.py (1 lines)
→ ok
...

Prompt: "브라우저를 열고, Google에서 'zhulinsen/miniagent'를 검색해줘."

Prompt: "Word에 AI 에이전트에 대한 500단어 분량의 개요를 작성하고 서식을 지정해줘."

Prompt: "ppo.py 구현체를 생성하고 테스트를 수행해줘."

카테고리	도구	설명
Coding	read	파일 내용 읽기
	write	파일 생성/덮어쓰기
	edit	파일의 지정된 행 편집
	grep	파일 내용 검색
	glob	일치하는 파일 목록 나열
	bash	Shell 명령 실행 (타임아웃 제어 지원)
OS	open_browser	웹페이지 열기 또는 검색
	open_app	로컬 애플리케이션 실행 (calc, notepad...)
	create_docx	Word 문서 생성
	clipboard_copy	클립보드에 복사
	clipboard_read	클립보드 내용 읽기
System	system_info	시스템 정보
	system_load	CPU/메모리/디스크 부하
	process_list	프로세스 목록
	disk_usage	디스크 사용량
	env_get	환경 변수 읽기
	env_set	환경 변수 설정
Misc	calculator	수학 계산 (AST 안전 평가)
	get_current_time	현재 시간
	web_search	웹 검색
	http_request	HTTP 요청
	file_stats	파일/디렉토리 통계

miniagent/
├── agent.py # 🧠 핵심 Agent 엔진 (여기서부터 읽으세요!)
# LLM 루프 + 도구 호출 (Tool Calling) + 컨텍스트 관리
...

MiniAgent는 학습과 비교를 용이하게 하기 위해 두 가지 도구 호출 (Tool Calling) 모드를 지원합니다:

LLM이 응답에서 구조화된 텍스트를 출력하고 Agent가 이를 해석하여 실행 — 완전 투명하며, 최적의 교육 모드:

agent.run("2+2 계산해줘") # 기본 텍스트 모드

OpenAI 호환 tools 파라미터를 사용 — 더 신뢰할 수 있으며, 병렬 도구 호출 지원:

agent.run("2+2 계산해줘", mode="native") # 네이티브 FC 모드

임의의 MCP 도구 서버에 연결하여 한 줄의 코드로 커뮤니티 생태계에 접속:

from miniagent import MiniAgent, load_mcp_tools
agent = MiniAgent(model="deepseek-chat", api_key="...")
# MCP 파일 시스템 도구 로드
...

내장된 오케스트레이터 (Orchestrator)가 복잡한 작업을 자동으로 분해하고 전문 Worker에게 할당합니다 (Skill 시스템 기반):

from miniagent import Orchestrator
orch = Orchestrator(model="deepseek-chat", api_key="...", base_url="...")
result = orch.run("Python 비동기 패턴을 연구하고, 데모를 작성한 뒤 테스트해줘")
...

Skill은 재사용 가능한 Agent 설정으로, Prompt + 도구 화이트리스트 + 파라미터로 구성됩니다. 4개의 내장 Skill이 있으며 사용자 정의도 가능합니다:

from miniagent import MiniAgent, Skill, register_skill
# 내장 Skill 사용
agent = MiniAgent(model="deepseek-chat", api_key="...", base_url="...")
...

from miniagent import MiniAgent
from miniagent.tools import register_tool
@register_tool
...

특징	MiniAgent	smolagents	pydantic-ai	LangChain
핵심 코드	단일 파일로 읽기 가능	~1,000행	182MB	10만+행
...

MiniAgent의 Code Tools 설계는 nanocode 프로젝트를 참고하였으며, 그 우아하고 미니멀한 구현 방식에 감사드립니다!

⭐ 이 프로젝트가 도움이 되었다면 Star를 눌러주세요!