GenericAgent

KO | EN

gitlite — search

#javascript #python #react #rust #docker #macos #java #kubernetes #vue #awesome-list #security #mcp #ios #openai

(★ 13,785)

Self-evolving agent: 3.3K줄의 시드(seed)로부터 스킬 트리를 성장시켜, 6배 적은 토큰 소비로 완전한 시스템 제어 달성

GenericAgent 최신버젼 다운로드

최종 버전 다운로드 (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

![GenericAgent Banner](assets/images/bar.jpg)
# GenericAgent
\*\*미니멀하고 스스로 진화하는 자율 에이전트 프레임워크\*\*
\*~3K 줄의 시드 코드 · 9개의 원자적 도구 · ~100줄의 Agent Loop\*

[![Official Website](https://img.shields.io/badge/Official_Website-gaagent.ai-00A67E?style=flat-square)](https://gaagent.ai)
[![Technical Report](https://img.shields.io/badge/Technical_Report-PDF-EA4335?style=flat-square&logo=adobeacrobatreader&logoColor=white)](https://arxiv.org/abs/2604.17091)
[![Reproduction Repo](https://img.shields.io/badge/Code_%26_Data-Reproduction-181717?style=flat-square&logo=github)](https://github.com/JinyiHan99/GA-Technical-Report)
[![Tutorial](https://img.shields.io/badge/Tutorial-Datawhale-blue?style=flat-square)](https://datawhalechina.github.io/hello-generic-agent/)
[![Sophub](https://img.shields.io/badge/Skill_Hub-Sophub-purple?style=flat-square)](https://fudankw.cn/sophub)

[![Trendshift](https://trendshift.io/api/badge/repositories/25944)](https://trendshift.io/repositories/25944)

\*\*[English](#-english) · [中文](#-中文)\*\*

> 📌 \*\*공지:\*\* GitHub 및 https://gaagent.ai만 공식 채널입니다. DintalClaw는 유일한 공식 상업 파트너이며, 그 외는 관련이 없습니다.
---
## 🌟 개요
\*\*GenericAgent\*\*는 미니멀하고 스스로 진화하는 자율 에이전트 프레임워크입니다. 핵심 코드는 단 \*\*~3K 줄\*\*에 불과합니다. \*\*9개의 원자적 도구 + ~100줄의 Agent Loop\*\*를 통해 모든 LLM에 브라우저, 터미널, 파일 시스템, 키보드/마우스 입력, 화면 비전, 모바일 기기(ADB)를 포함한 로컬 컴퓨터의 시스템 수준 제어 권한을 부여합니다.
> 디자인 철학 — \*\*스킬을 미리 로드하지 말고, 진화시키세요.\*\*
GenericAgent는 새로운 작업을 해결할 때마다 실행 경로를 재사용 가능한 \*\*Skill\*\*로 자동으로 구체화합니다. 사용할수록 스킬이 쌓이며, 3K 줄의 시드 코드에서 온전히 자라난 개인 맞춤형 스킬 트리를 형성합니다.
> 🤖 \*\*Self-Bootstrap 증명\*\* — Git 설치와 `git init` 실행부터 모든 커밋 메시지에 이르기까지, 이 리포지토리의 모든 것은 GenericAgent가 자율적으로 완료했습니다. 저자는 터미널을 단 한 번도 직접 열지 않았습니다.
### 📑 목차
- [주요 기능](#-key-features)
- [데모 쇼케이스](#-demo-showcase)
- [빠른 시작](#-quick-start)
- [사용법](#-usage)
- [고급 기능 잠금 해제](#-unlocking-advanced-capabilities)
- [아키텍처](#-architecture)
- [자가 진화 메커니즘](#-self-evolution-mechanism)
- [비교](#-comparison)
- [평가](#-evaluation)
- [로드맵 및 소식](#-roadmap--news)
- [커뮤니티 및 지원](#-community--support)
- [라이선스](#-license)
---
## 📋 주요 기능
| 기능 | 설명 |
| :--- | :--- |
| 🧬 \*\*자가 진화 (Self-Evolving)\*\* | 각 작업을 자동으로 Skill로 구체화합니다. 사용할수록 역량이 성장하여 나만의 스킬 트리를 형성합니다. |
| 🪶 \*\*미니멀 아키텍처\*\* | 핵심 코드 ~3K 줄. Agent Loop는 ~100줄. 복잡한 의존성 없음, 제로 배포 오버헤드. |
| ⚡ \*\*강력한 실행력\*\* | \*\*TMWebdriver\*\*가 실제 브라우저에 주입되어 작동합니다 (로그인 세션 유지). 9개의 원자적 도구가 시스템을 직접 제어합니다. |
| 🔌 \*\*높은 호환성\*\* | Claude / Gemini / Kimi / MiniMax 및 기타 주요 모델 지원. 크로스 플랫폼. |
| 💰 \*\*토큰 효율성\*\* | 30K 미만의 컨텍스트 윈도우 — 다른 에이전트가 소비하는 200K~1M의 일부에 불과합니다. 노이즈 감소, 환각 현상 감소, 높은 성공률, 낮은 비용. |
---
## 🎯 데모 쇼케이스

|  |  |
| --- | --- |
| **🛡️ 실제 브라우저 CAPTCHA 우회** | **🌐 자율 웹 탐색** |
| 실제 브라우저에서 Discord hCaptcha 통과 | 웹 탐색 |
| Discord 봇을 설정하는 동안 작업 중에 hCaptcha *"인간이십니까?"* 챌린지가 나타나면 GA의 실제 브라우저 세션이 이를 통과하고 작업이 계속됩니다. [Browser Realness](#browser-realness-of-ga-web-tools)를 참조하세요. | 웹 콘텐츠를 자율적으로 탐색하고 주기적으로 요약합니다. |
| **🧋 음식 배달 주문** | **📈 퀀트 주식 스크리닝** |
| 밀크티 주문 | 주식 종목 선정 |
| *"밀크티 주문해줘"* — 배달 앱을 탐색하고, 상품을 선택하고, 결제를 완료합니다. | *"EXPMA 골든 크로스, 회전율 > 5%인 창업판(GEM) 주식을 찾아줘"* — 퀀트 스크리닝. |
| **💰 지출 추적** | **💬 대량 메시지 전송** |
| Alipay 지출 내역 | WeChat 대량 전송 |
| *"지난 3개월간 2,00위안이 넘는 지출 내역을 찾아줘"* — ADB를 통해 Alipay를 제어합니다. | WeChat 클라이언트를 완전히 제어하여 대량의 WeChat 메시지를 보냅니다. |

---
## 🚀 빠른 시작
> ⚠️ \*\*Python 버전\*\*: \*\*Python 3.11 또는 3.12\*\*를 사용하세요. Python 3.14는 \*\*사용하지 마세요\*\* — `pywebview` 및 기타 몇 가지 GA 의존성과 호환되지 않습니다.
>
> 📖 상세한 설치 가이드: \*\*[installation.md](docs/installation.md)\*\* · \*\*[installation\_zh.md（中文）](docs/installation\_zh.md)\*\*
### LLM Agent용
설치 가이드를 가져와서 따르세요:
```bash
curl -fsSL https://raw.githubusercontent.com/lsdefine/GenericAgent/refs/heads/main/docs/installation.md
```
### 사용자용
#### 방법 1 — 클론 및 설치 \*(추천)\*
```bash
git clone https://github.com/lsdefine/GenericAgent.git && cd GenericAgent
uv venv && uv pip install -e ".[ui]"
cp mykey\_template\_en.py mykey.py # LLM API 키 입력
```
의존성은 단계별로 신중하게 구성되어 있습니다. 에이전트 코어는 `requests`만 필요로 하며, TMWebdriver의 로컬 서버를 위해 네 개의 경량 패키지(`beautifulsoup4`, `bottle`, `simple-websocket-server`, `aiohttp`)가 추가로 필요합니다. `[ui]` 옵션은 프론트엔드 라이브러리(Streamlit, TUI용 `prompt\_toolkit`/`rich` 등)를 함께 설치합니다. 번들된 UI를 사용하려면 설치하고, 헤드리스(headless)로 에이전트를 구동하려면 생략해도 됩니다. Playwright나 LangChain, 다운로드해야 하는 브라우저 바이너리가 없습니다.
그런 다음 실행합니다:
```bash
python frontends/tui\_v3.py # 터미널 UI (추천)
python launch.pyw # Streamlit 웹 UI
```
#### 방법 2 — 한 줄 설치 프로그램 \*(간편)\*
독립된 Python 환경, Git, 그리고 바로 실행할 수 있는 패키지가 포함된 격리된 디렉토리를 설정합니다. 먼저 내용을 확인하고 싶다면 스크립트는 [`assets/`](assets/)에 있습니다.
\*\*Windows PowerShell\*\*
```powershell
powershell -ExecutionPolicy Bypass -c "$env:GLOBAL=1; irm https://raw.githubusercontent.com/lsdefine/GenericAgent/main/assets/ga\_install.ps1 | iex"
```
\*\*Linux / macOS\*\*
```bash
GLOBAL=1 bash -c "$(curl -fsSL https://raw.githubusercontent.com/lsdefine/GenericAgent/main/assets/ga\_install.sh)"
```
> 💡 GenericAgent는 모든 것을 미리 설치하는 대신 \*\*Agent 자체를 통해\*\* 환경을 확장합니다. 아래의 [고급 기능 잠금 해제](#-unlocking-advanced-capabilities)를 참조하세요.
---
## 💻 사용법
### 프론트엔드
#### 터미널 UI \*(추천)\*
`prompt\_toolkit`과 `rich` 기반으로 구축된 가벼운 스크롤백 우선 터미널 인터페이스입니다. 다중 동시 세션과 실시간 스트리밍을 지원합니다.
```bash
python frontends/tui\_v3.py
```
**⚠️ Windows TUI 문제 해결**
Windows에서의 TUI 렌더링은 터미널과 폰트에 따라 불안정할 수 있습니다. 일반적인 원인:
1. `prompt\_toolkit` / `rich`가 최신 버전이 아님 — 먼저 `pip install -U prompt\_toolkit rich`를 실행하세요.
2. PowerShell / cmd 기본 터미널은 유니코드 및 키 바인딩 지원이 미흡합니다. \*\*훨씬 원활하게 작동하는 Windows용 Git Bash를 권장합니다\*\*.
3. 그래도 깨져 보인다면, GA 자체에게 수정을 요청하세요:
> \*"Windows의 PowerShell / cmd / Git Bash에서 `frontends/tui\_v3.py`를 사용하는 경험이 매우 좋지 않습니다. 호환성 문제가 많습니다. Claude Code의 Windows 터미널 모범 사례를 참고하여 모든 폰트 및 렌더링 호환성 문제를 해결해 주세요."\*
#### Streamlit UI
```bash
python launch.pyw
```
### 봇 인터페이스 (IM)
GenericAgent는 Telegram, Discord, Lark 같은 IM 프론트엔드도 지원합니다.
| 플랫폼 | 명령어 |
| :--- | :--- |
| Telegram | `python frontends/tgapp.py` |
| Discord | `python frontends/dcapp.py` |
| Lark / Feishu | `python frontends/fsapp.py` |
> WeChat, QQ, WeCom 및 DingTalk도 지원됩니다 — 아래의 중국어 섹션을 참조하세요.
> 상세한 설정은 GenericAgent 자체에 문의하세요.
---
## 🔓 고급 기능 잠금 해제
GA에서 고급 기능은 문서를 읽거나 추가 패키지를 설치하는 것이 아니라 \*\*에이전트에 지시를 내려서\*\* 잠금 해제됩니다. 아래의 각 지시는 GA가 사전 설치된 SOP(메모리에 내장된 검증된 플레이북)를 읽고, 누락된 항목을 설치하고, 사용자의 OS에 맞게 조정한 후, 그 결과를 자신의 메모리에 영구 저장하도록 만듭니다.
| 기능 | GA에게 요청하기 |
| :--- | :--- |
| 🌐 웹 자동화 | \*"웹 자동화 기능을 설정해 주세요."\* — GA가 단 하나의 수동 단계(번들 드래그)를 안내합니다. |

![GenericAgent Workflow](assets/images/workflow.jpg)
  
*GenericAgent Workflow Diagram*

|  |  |
| --- | --- |
| 도구 사용 효율성 레이더  **Tool-use efficiency radar.** GA는 4가지 작업 차원에서 품질을 유지하면서 토큰, 요청, 도구 호출 축을 지배합니다. | 교차 작업 자기 진화 수렴성  **Cross-task self-evolution.** 2차 및 3차 실행의 GA는 8개의 웹 작업 전반에 걸쳐 안정적인 저비용 체제로 수렴하는 반면, OpenClaw은 그러한 수렴을 보여주지 않습니다. |

### GA Web Tools의 브라우저 실제감 (TMWebdriver)
GA web tools는 일회용 헤드리스 샌드박스가 아니라 \*\*실제 영구적인 Chrome/Chromium 세션\*\*을 통해 실행되는 로컬 WebSocket 서버와 Chrome 확장 프로그램인 \*\*TMWebdriver\*\*로 구동되며, 쿠키, 로그인 상태, 확장 프로그램, GPU/WebGL 동작 및 일반 브라우저 세션 지문을 유지합니다.
| 탐지 서비스 / 시그널 | 순정 헤드리스 자동화 | GA Web Tools | 참고 사항 |
| :--- | :---: | :---: | :--- |
| SannySoft 헤드리스 테스트 | 자주 탐지됨 | ✅ 56/56 통과 | `bot.sannysoft.com` |
| bot.incolumitas.com | 일반적으로 webdriver / CDP 검사 실패 | ✅ 36/36 통과 | `WEBDRIVER`, `SELENIUM\_DRIVER`, `webDriverAdvanced` 모두 정상 |
| BrowserScan 봇 탐지 | 종종 비정상 | ✅ 정상 | `browserscan.net` |
| 기기 및 브라우저 정보 봇 테스트 | 여러 봇 플래그 | ✅ 인간 / `isBot=false` | `deviceandbrowserinfo.com` |
| FingerprintJS 봇 탐지 데모 | 자주 탐지됨 | ✅ 통과 | 봇 판정 없이 데모 흐름 완료 |
| reCAPTCHA v3 데모 | 낮은 봇 유사도 점수 | ✅ 0.9 인간 유사도 점수 | 점수 기반 위험 시그널; 0.9는 일반적인 프로덕션 임계값보다 높음 |
reCAPTCHA v3의 경우, `0.9`는 "체크박스 해결" 결과가 아니며, 위험 모델이 반환하는 높은 신뢰도의 인간 유사도 점수로, 일반적으로 프로덕션 흐름에서 추가적인 챌린지를 피하기에 충분합니다.
---
## 📅 로드맵 및 소식
- \*\*2026-05-23\*\* — 🆕 \*\*TUI v3 출시\*\* (`frontends/tui\_v3.py`). 적절한 크기 조절 리플로우가 포함된 블록 기반 스크롤백, 크로스 터미널 일관성을 위한 터미널별 색상 프로파일, v2와의 기능 동등성 제공.
- \*\*2026-05-18\*\* — 🆕 \*\*Morphling 모드\*\*. 프로젝트 수준의 스킬 흡수 — 외부 저장소에서 목표와 테스트를 추출한 다음, 컴포넌트별로 호출, 재작성 또는 폐기 여부를 결정합니다. `memory/morphling\_sop.md`를 참조하세요.
- \*\*2026-05-17\*\* — 🆕 \*\*Goal Hive 모드\*\*. 다중 작업자 협업 Goal 모드 — BBS로 조율되는 마스터/작업자가 장기적인 목표를 병렬로 실행합니다. `memory/goal\_hive\_sop.md`를 참조하세요.
- \*\*2026-05-15\*\* — 🖥️ \*\*데스크톱 GUI 출시\*\*. 한 줄 설치로 바로 실행 가능한 데스크톱 앱(`frontends/GenericAgent.exe`)을 제공합니다. 개발자는 `python launch.pyw`를 통해 실행합니다.
- \*\*2026-05-14\*\* — 🆕 \*\*Conductor 서브 아이전트 오케스트레이션\*\*. 병렬 서브 아이전트 생성, 감독 및 자동 정리; `/btw` 부가 질문을 보완하는 최고 수준의 위임 프리미티브.
- \*\*2026-05-12\*\* — 🆕 \*\*TUI v2 출시\*\* (`frontends/tuiapp\_v2.py`). 이미지 붙여넣기 접기, 파일 붙여넣기, 블록 삭제, Ctrl+C 복사, 히스토리 탐색 및 `/llm` / `/export` / `/continue` 선택기가 포함된 개선된 Textual 프론트엔드.
- \*\*2026-05-08\*\* — 🆕 \*\*Goal 모드\*\* (`reflect/goal\_mode.py`). 시간 예산 기반의 자율 구동 루프 — 조기 완료 없이 "N시간 동안 X를 계속 최적화".
- \*\*2026-04-21\*\* — 📄 [\*\*arXiv 기술 보고서\*\*](https://arxiv.org/abs/2604.17091) — \*GenericAgent: A Token-Efficient Self-Evolving LLM Agent via Contextual Information Density Maximization\*.
- \*\*2026-04-11\*\* — \*\*L4 세션 아카이브 메모리\*\* 및 스케줄러 크론 통합 도입.
- \*\*2026-03-23\*\* — 개인용 WeChat을 봇 프론트엔드로 지원.
- \*\*2026-03-10\*\* — [백만 규모 스킬 라이브러리 출시](https://mp.weixin.qq.com/s/q2gQ7YvWoiAcwxzaiwpuiQ?scene=1&click\_id=7) \*(중국어\*.
- \*\*2026-03-08\*\* — [GenericAgent 기반 대외무역 봇 "Dintal Claw" 출시](https://mp.weixin.qq.com/s/eiEhwo-j6S-WpLxgBnNxBg) \*(중국어\*.
- \*\*2026-03-01\*\* — [기계지심(机器之心) 소개](https://mp.weixin.qq.com/s/uVWpTTF5I1yzAENV\_qm7yg) \*(중국어\*.
- \*\*2026-01-16\*\* — GenericAgent \*\*V1.0\*\* 정식 출시.
---
## ⭐ 커뮤니티 및 지원
이 프로젝트가 도움이 되었다면 \*\*Star!\*\*를 남겨주세요 🙏
### 🚩 유용한 링크
\*\*LinuxDo\*\* 커뮤니티의 지원에 감사드립니다!
[![LinuxDo](https://img.shields.io/badge/Community-LinuxDo-blue?style=for-the-badge)](https://linux.do/)
\*\*커뮤니티 GUI\*\* \*(독립 오픈소스 프로젝트\*\*:
- [chilishark27/ga-manager

](https://github.com/chilishark27/ga-manager)
- [wangjc683/galley](https://github.com/wangjc683/galley) — GA 런타임(CPython 3.11 + 의존성)이 번들로 포함된 즉시 사용 가능한 로컬 에이전트 워크벤치, 네이티브 GUI/CLI, 다중 세션 + 프로젝트 오케스트레이션, 로컬 퍼스트.
- [FroStorM/A3Agent](https://github.com/FroStorM/A3Agent/tree/workbench)
- [Fwind43/GenericAgent-Admin](https://github.com/Fwind43/GenericAgent-Admin) — Go + React 데스크톱 어드민 패널: 서비스 라이프사이클 관리, 네이티브 채팅, Goal 모드, BBS 팀보드, 파일 편집기, 모델 설정 마법사, TMWebDriver 모니터, 자체 업데이트 및 Windows 트레이/데스크톱 펫 통합.
---
## 📄 License
\*\*MIT License\*\*에 따라 배포됩니다. 전체 내용은 [`LICENSE`](LICENSE)를 참조하세요.
> \*면책 조항: 공식 GenericAgent 채널은 이 GitHub 리포지토리와 https://gaagent.ai 입니다. 현재 DintalClaw만이 유일하게 공식 승인된 상업 파트너이며, 여기에 명시적으로 나열되지 않은 한 GenericAgent 이름을 사용하는 다른 제3자 웹사이트, 조직 또는 개인은 공식이 아닙니다.\*
---
## 🌟 프로젝트 소개
\*\*GenericAgent\*\*는 미니멀하고 스스로 진화하는 자율 Agent 프레임워크입니다. 핵심 코드는 단 \*\*~3K 줄\*\*에 불과하며, \*\*9개의 원자적 도구 + ~100줄의 Agent Loop\*\*를 통해 브라우저, 터미널, 파일 시스템, 키보드 및 마우스 입력, 화면 시각 자료, 모바일 기기(ADB)를 아우르는 시스템 수준의 제어 권한을 임의의 LLM에 부여합니다.
> 디자인 철학 —— \*\*사전에 기술을 정의하지 않고, 진화를 통해 능력을 획득합니다.\*\*
새로운 태스크를 해결할 때마다 GenericAgent는 실행 경로를 Skill로 자동 고정하여 이후에 직접 호출할 수 있도록 합니다. 사용할 시간이 길어질수록 축적되는 기술이 많아지며, 3K 줄의 시드 코드에서 자라난 자신만의 전용 스킬 트리가 형성됩니다.
> 🤖 \*\*부트스트랩 실증\*\* — Git 설치, `git init`부터 모든 commit message에 이르기까지 이 리포지토리의 모든 것은 GenericAgent가 자율적으로 수행했습니다. 작성자는 개발 과정에서 단 한 번도 터미널을 열지 않았습니다.
### 📑 목차
- [핵심 특징](#-핵심-특징)
- [실례 시연](#-실례-시연)
- [빠른 시작](#-빠른-시작)
- [사용 방법](#-사용-방법)
- [아키텍처 디자인](#-아키텍처-디자인)
- [자기 진화 메커니즘](#-자기-진화-메커니즘)
- [유사 제품 비교](#-유사-제품-비교)
- [평가](#-평가)
- [로드맵 및 최신 소식](#-로드맵-및-최신-소식)
- [커뮤니티 및 지원](#-커뮤니티-및-지원)
- [라이선스](#-라이선스)
---
## 📋 핵심 특징
| 특징 | 설명 |
| :--- | :--- |
| 🧬 \*\*자기 진화\*\* | 태스크마다 Skill을 자동 축적하여 사용에 따라 능력이 지속적으로 성장하고 전용 스킬 트리 형성 |
| 🪶 \*\*미니멀 아키텍처\*\* | ~3K 줄의 핵심 코드, 약 100줄의 Agent Loop, 복잡한 의존성 없음, 제로 부담 배포 |
| ⚡ \*\*강력한 실행력\*\* | 실제 브라우저 주입(로그인 상태 유지), 9개의 원자적 도구로 시스템 직접 제어 |
| 🔌 \*\*높은 호환성\*\* | Claude / Gemini / Kimi / MiniMax 등 주류 모델 지원, 크로스 플랫폼 실행 |
| 💰 \*\*극도로 낮은 토큰 사용량\*\* | 컨텍스트 창이 30K 미만으로 다른 Agent(200K–1M)의 극히 일부에 불과함; 노이즈가 적고 환각이 낮으며 성공률이 높고 비용이 한 자릿수 낮음 |
---
## 🎯 실례 시연

|  |  |
| --- | --- |
| **🧋 배달 주문** | **📈 퀀트 주식 종목 선정** |
| 배달 주문 | 퀀트 주식 종목 선정 |
| *"Order me a milk tea"* — 배달 앱 자동 탐색, 상품 선택 및 결제 완료 | *"Find GEM stocks with EXPMA golden cross, turnover > 5%"* — 퀀트 조건 검색 |
| **🌐 자율 웹 탐색** | **💰 지출 추적** |
| 웹 탐색 | Alipay 지출 |
| 웹페이지 정보를 자율적으로 브라우징하고 주기적으로 요약 | *"查找近 3 个月超 ¥2K 的支出"* — ADB를 통한 Alipay 제어 |
| **💬 대량 메시지 전송** | |
| WeChat 대량 전송 | |
| WeChat 메시지 대량 전송, WeChat 클라이언트 완전 제어 | |

---
## 🚀 빠른 시작
> ⚠️ \*\*Python 버전:\*\* \*\*Python 3.11 또는 3.12\*\*를 권장합니다. \*\*Python 3.14는 사용하지 마세요\*\*, `pywebview` 및 일부 의존성과 호환되지 않습니다.
>
> 📖 상세 설치 가이드: \*\*[installation\_zh.md (중국어)](docs/installation\_zh.md)\*\* · \*\*[installation.md (영어)](docs/installation.md)\*\*
### LLM Agent용
설치 가이드를 가져와서 그대로 실행하세요:
```bash
curl -fsSL https://raw.githubusercontent.com/lsdefine/GenericAgent/refs/heads/main/docs/installation\_zh.md
```
### 일반 사용자용
#### 방법 1 — 원클릭 설치 \* (권장) \*
원클릭 설치는 독립된 Python 환경, Git, 프로젝트 파일 및 데스크톱 앱을 자동으로 준비하며 시스템 환경을 오염시키지 않습니다.
\*\*Windows PowerShell\*\*
```powershell
powershell -ExecutionPolicy Bypass -c "irm http://fudankw.cn:9000/files/ga\_install.ps1 | iex"
```
\*\*Linux / macOS\*\*
```bash
curl -fsSL http://fudankw.cn:9000/files/ga\_install.sh | bash
```
설치 완료 후 실행:
- \*\*Windows\*\* — `frontends/GenericAgent.exe` 더블 클릭
- \*\*Linux / macOS\*\* — 설치 디렉토리에서 `python launch.pyw` 실행
#### 방법 2 — Python 설치 \* (개발자용) \*
```bash
git clone https://github.com/lsdefine/GenericAgent.git
cd GenericAgent
uv venv
uv pip install -e ".[ui]" # 코어 + UI 의존성
cp mykey\_template.py mykey.py # LLM API Key 입력
python launch.pyw
```
> 💡 GenericAgent는 미리 수동으로 전체 의존성을 설치하는 것보다 \*\*Agent가 사용 중에 환경을 부트스트랩(Self-bootstrap)\*\*하는 것을 더 권장합니다.
📖 전체 안내 프로세스는 [`docs/GETTING\_STARTED.md`](docs/GETTING\_STARTED.md)를 참조하세요.
📖 초보자용 이미지 가이드: [Feishu 문서](https://my.feishu.cn/wiki/CGrDw0T76iNFuskmwxdcWrpinPb)
📘 전체 입문 튜토리얼 (Datawhale 제작): [Hello GenericAgent](https://datawhalechina.github.io/hello-generic-agent/) · [GitHub](https://github.com/datawhalechina/hello-generic-agent)
---
## 💻 사용 방식
### 프론트엔드 실행
#### 데스크톱 앱
원클릭 설치에 데스크톱 앱(Windows)이 포함되어 있습니다. 다음 파일을 더블 클릭하세요:
```text
frontends/GenericAgent.exe
```
#### 터미널 UI
[Textual](https://github.com/Textualize/textual) 기반의 경량 키보드 구동 인터페이스. 멀티 세션 동시 실행, 실시간 스트리밍 출력을 지원하며 터미널만 있으면 실행할 수 있습니다.
```bash
python frontends/tuiapp\_v2.py
```
**⚠️ Windows에서 TUI가 비정상적으로 표시될 때의 문제 해결 방법**
1. `textual` 버전이 너무 오래된 경우, 먼저 `pip install -U textual` 실행;
2. PowerShell / cmd 기본 터미널은 Unicode 및 키 맵핑 지원이 좋지 않으므로, \*\*Windows에서는 Git Bash 사용을 권장\*\*하며 체감상 훨씬 안정적입니다;
3. 여전히 비정상적으로 표시되는 경우, GA가 직접 수정하도록 할 수 있습니다. 프롬프트 예시:
> \*"我在 Windows 的 PowerShell / cmd / Git Bash 中使用 `frontends/tuiapp\_v2.py` 体验非常差，出现了一堆不兼容问题。请参考 Claude Code 在 Windows 终端的最佳配置，把所有字体和显示不兼容的问题修一遍。"\*
#### Streamlit UI
```bash
python launch.pyw
```
### Bot 인터페이스 (IM)
GenericAgent는 Telegram, Discord, WeChat, QQ, Feishu / Lark, WeCom, DingTalk 등의 IM 프론트엔드를 지원합니다.
| 플랫폼 | 실행 명령어 |
| :--- | :--- |
| Telegram | `python frontends/tgapp.py` |
| Discord | `python frontends/dcapp.py` |
| WeChat | `python frontends/wechatapp.py` |
| QQ | `python frontends/qqapp.py` |
| Feishu / Lark | `python frontends/fsapp.py` |
| WeCom | `python frontends/wecomapp.py` |
| DingTalk | `python frontends/dingtalkapp.py` |
> 상세 설정은 GenericAgent에게 직접 물어보세요.
---
## 🧠 아키텍처 설계
GenericAgent는 \*\*계층형 메모리 × 최소 도구 세트 × 자율 실행 루프\*\*를 통해 복잡한 작업을 완료하며, 실행 과정에서 지속적으로 경험을 축적합니다.
### 1️⃣ 계층형 메모리 시스템
> \*작업 실행 과정에서 메모리가 지속적으로 축적되어, Agent가 점진적으로 안정적이고 효율적인 업무 방식을 갖추도록 합니다.\*
| 계층 | 이름 | 설명 |
| :---: | :--- | :--- |
| \*\*L0\*\* | 메타 규칙 (Meta Rules) | Agent의 기본 행동 규칙 및 시스템 제약 조건 |
| \*\*L1\*\* | 메모리 인덱스 (Insight Index) | 빠른 라우팅과 조회를 위한 극도로 단순화된 인덱스 계층 |
| \*\*L2\*\* | 전역 팩트 (Global Facts) | 장기 실행 과정에서 축적된 안정적인 지식 |
| \*\*L3\*\* | 작업 Skills / SOPs | 특정 유형의 작업을 완료하기 위한 재사용 가능한 프로세스 |
| \*\*L4\*\* | 세션 아카이브 (Session Archive) | 완료된 작업에서 추출한 아카이브 기록으로, 장거리 조회에 사용됨 |
### 2️⃣ 자율 실행 루프
> \*환경 상태 인지 → 작업 추론 → 도구 호출 및 실행 → 메모리에 경험 기록 → 반복\*
전체 코어 루프는 단 \*\*약 100여 줄의 코드\*\*로 이루어져 있습니다 ([`agent\_loop.py`](agent\_loop.py)).
### 3️⃣ 최소 도구 세트
> \*GenericAgent는 외부 세계와 상호 작용하는 기본 기능을 구성하는 \*\*9개의 원자 도구(Atomic Tools)\*\*만 제공합니다.\*
| 도구 | 기능 |
| :--- | :--- |
| `code\_run` | 임의의 코드 실행 (Python / PowerShell) |
| `file\_read` | 파일 읽기 |
| `file\_write` | 파일 쓰기 / 생성 / 덮어쓰기 |
| `file\_patch` | 파일 수정 |
| `web\_scan` | 웹페이지 내용 인지 |
| `web\_execute\_js` | 브라우저 동작 제어 |
| `ask\_user` | 인간-AI 협업 확인 |
| `update\_working\_checkpoint` | \* (메모리) \* 단기 작업 메모장 |
| `start\_long\_term\_update` | \* (메모리) \* 장기 메모리 추출 |
### 4️⃣ 능력 확장 메커니즘
> \*새로운 도구를 동적으로 생성할 수 있는 능력을 갖추고 있습니다.\*
`code\_run`을 통해 GenericAgent는 런타임에 동적으로 Python 패키지를 설치하고, 새 스크립트를 작성하며, 외부 API를 호출하거나 하드웨어를 제어하여 임시 능력을 영구적인 도구로 고정할 수 있습니다.

![GenericAgent 워크플로](assets/images/workflow.jpg)
  
*GenericAgent 워크플로 다이어그램*

|  |  |
| --- | --- |
| 도구 사용 효율성 레이더 차트  **도구 사용 효율성 레이더 차트.** GA는 Token, 요청 수, 도구 호출 축에서 전면적으로 우위를 점하는 동시에, 네 가지 작업 차원에서 품질을 유지합니다. | 크로스 작업 자기 진화 수렴 곡선  **크로스 작업 자기 진화.** GA의 2라운드 및 3라운드 실행은 8개의 웹 작업에서 안정적인 저비용 구간으로 수렴합니다. |

### GA Web 도구의 브라우저 진위성
GA Web 도구는 일회성 headless 샌드박스가 아닌 \*\*실제 지속형 Chrome/Chromium 세션\*\*에서 실행되므로 쿠키, 로그인 상태, 확장 프로그램, GPU/WebGL 동작 및 정상적인 브라우저 세션 지문을 유지할 수 있습니다.
| 감지 서비스 / 신호 | 일반 Headless 자동화 | GA Web 도구 | 설명 |
| :--- | :---: | :---: | :--- |
| SannySoft headless test | 자주 감지됨 | ✅ 56/56 통과 | `bot.sannysoft.com` |
| bot.incolumitas.com | webdriver / CDP 항목에서 자주 예외 발생 | ✅ 36/36 통과 | `WEBDRIVER`, `SELENIUM\_DRIVER`, `webDriverAdvanced` 전부 OK |
| BrowserScan bot detection | 예외가 자주 표시됨 | ✅ Normal | `browserscan.net` |
| Device & Browser Info bot test | 여러 봇 태그 지정 | ✅ Human / `isBot=false` | `deviceandbrowserinfo.com` |
| FingerprintJS bot detection demo | 자주 감지됨 | ✅ 통과 | 데모 프로세스 완료, 봇 판정 없음 |
| reCAPTCHA v3 demo | 낮은 점수 / 봇 유사성 | ✅ 0.9 인간 유사도 점수 | v3는 점수 기반 위험 신호입니다. 0.9는 일반적인 프로덕션 임계값보다 높습니다. |
reCAPTCHA v3의 경우 `0.9`는 "캡차를 풀었다"는 결과가 아니라, 위험 관리 모델이 반환한 높은 신뢰도의 인간 유사도 점수입니다. 이는 일반적으로 프로덕션 환경의 일반적인 임계값을 통과하여 더 엄격한 챌린지로 진입하는 것을 방지하기에 충분합니다.
---
## 📅 로드맵 및 최신 소식
- \*\*2026-05-23\*\* — 🆕 \*\*TUI v3 정식 출시\*\* (`frontends/tui\_v3.py`). 블록 기반 스크롤백 + 올바른 크기 조정 리플로우 제공, 터미널 간 일관성을 보장하는 터미널별 독립 색상 적용, v2와의 기능 동기화 완료.
- \*\*2026-05-18\*\* — 🆕 \*\*Morphling 모드\*\*. 프로젝트 수준의 기능 흡수 —— 임의의 외부 저장소에서 목표와 테스트 케이스를 추출한 후, 각 핵심 구성 요소별로 호출, 재작성 또는 폐기 여부를 결정합니다. 자세한 내용은 `memory/morphling\_sop.md`를 참조하세요.
- \*\*2026-05-17\*\* — 🆕 \*\*Goal Hive 모드\*\*. 멀티 워커 협업 버전의 Goal —— Master/Worker가 BBS를 통해 협력하여 장기 목표를 추진합니다. 자세한 내용은 `memory/goal\_hive\_sop.md`를 참조하세요.
- \*\*2026-05-15\*\* — 🖥️ \*\*데스크톱 GUI 출시\*\*. 원클릭 설치 시 바로 실행 가능한 데스크톱 클라이언트(`frontends/GenericAgent.exe`)가 포함되며, 개발자는 `python launch.pyw`로 실행할 수도 있습니다.
- \*\*2026-05-14\*\* — 🆕 \*\*Conductor 서브 Agent 오케스트레이션\*\*. 병렬 서브 Agent 파견, 모니터링, 자동 정리 기능 제공; `/btw` 사이드밴드 서브 Agent 상호 보완, 일급(First-class) 시민 수준의 작업 위임 프리미티브 제공.
- \*\*2026-05-12\*\* — 🆕 \*\*TUI v2 정식 출시\*\* (`frontends/tuiapp\_v2.py`). 시각적 스타일을 재구상한 Textual 프론트엔드, 이미지 붙여넣기 접기, 파일 붙여넣기, 블록 삭제, Ctrl+C 복사, 기록 탐색 및 `/llm` / `/export` / `/continue` 선택기 지원.
- \*\*2026-05-08\*\* — 🆕 \*\*Goal 모드\*\* (`reflect/goal\_mode.py`). 시간 예산 기반의 자율 구동 루프 —— "X시간 동안 지속적인 최적화", 예산이 충족되지 않으면 조기 납품이 허용되지 않습니다.
- \*\*2026-04-21\*\* — 📄 [\*\*arXiv에 기술 보고서 게시됨\*\*](https://arxiv.org/abs/2604.17091) — \*GenericAgent: A Token-Efficient Self-Evolving LLM Agent via Contextual Information Density Maximization\*.
- \*\*2026-04-11\*\* — \*\*L4 세션 아카이브 메모리\*\* 도입 및 스케줄러 크론(cron) 연동.
- \*\*2026-03-23\*\* — 개인 위챗(WeChat) 연동을 Bot 프론트엔드로 지원.
- \*\*2026-03-10\*\* — [백만 수준의 Skill 라이브러리 출시](https://mp.weixin.qq.com/s/q2gQ7YvWoiAcwxzaiwpuiQ?scene=1&click\_id=7).
- \*\*2026-03-08\*\* — [GenericAgent 중심의 "정무 랍스터" Dintal Claw 출시](https://mp.weixin.qq.com/s/eiEhwo-j6S-WpLxgBnNxBg).
- \*\*2026-03-01\*\* — [지기지심(机器之心) 보도됨](https://mp.weixin.qq.com/s/uVWpTTF5I1yzAENV\_qm7yg).
- \*\*2026-01-16\*\* — GenericAgent \*\*V1.0\*\* 공개 버전 출시.
---
## ⭐ 커뮤니티 및 지원
이 프로젝트가 도움이 되었다면 \*\*Star!\*\*를 눌러주세요! 🙏
또한 \*\*GenericAgent 체험 소통 그룹\*\*에 가입하여 함께 소통하고 피드백을 나누며 발전시켜 보세요 👏

|  |
| --- |
| **위챗 그룹 22** 위챗 그룹 22 QR 코드 |

### 🚩 유용한 링크
\*\*LinuxDo\*\* 커뮤니티의 지원에 감사드립니다!
[![LinuxDo](https://img.shields.io/badge/社区-LinuxDo-blue?style=for-the-badge)](https://linux.do/)
\*\*커뮤니티 GUI 클라이언트\*\* \*(독립 오픈소스 프로젝트)*:
- [chilishark27/ga-manager](https://github.com/chilishark27/ga-manager)
- [wangjc683/galley](https://github.com/wangjc683/galley) —— 바로 사용할 수 있는 로컬 Agent 워크벤치, GA 커널 내장 (CPython 3.11 + 실행 의존성 포함), GUI/CLI 듀얼 네이티브, 멀티 세션 + 프로젝트 오케스트레이션, 로컬 우선.
- [FroStorM/A3Agent](https://github.com/FroStorM/A3Agent/tree/workbench)
- [Fwind43/GenericAgent-Admin](https://github.com/Fwind43/GenericAgent-Admin) —— Go + React 데스크톱 관리 패널: 서비스 수명 주기 관리, 네이티브 Chat, Goal 모드, BBS 팀 대시보드, 파일 편집기, 모델 설정 마법사, TMWebDriver 모니터링, 자동 업데이트 및 Windows 트레이/데스크톱 펫 통합.
---
## 📄 라이선스
\*\*MIT License\*\*에 따라 배포되며, 자세한 내용은 [`LICENSE`](LICENSE)를 참조하세요.
> \*면책 조항: GenericAgent의 공식 채널은 본 GitHub 저장소와 https://gaagent.ai입니다. DintalClaw는 현재 유일하게 공식 승인된 상업적 파트너입니다. 여기에 명시적으로 나열되지 않은 경우, GenericAgent의 이름을 사용하는 다른 제3자 웹사이트, 기관, 조직 또는 개인은 모두 공식이 아닙니다.\*
---
## 📈 Star History

[![Star History Chart](https://api.star-history.com/svg?repos=lsdefine/GenericAgent&type=Date)](https://star-history.com/#lsdefine/GenericAgent&Date)

GenericAgent

GenericAgent 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

GenericAgent

GenericAgent 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README