본문 바로가기
AI 생성 글 정리/tech_github

GenericAgent — 3K줄 시드 코드에서 스킬 트리를 성장시키는 로컬 자가 진화 LLM Agent

by Honbul 2026. 4. 28.

한 줄 요약: GenericAgent는 큰 플러그인 생태계를 미리 탑재하기보다, 로컬 컴퓨터의 파일·브라우저·터미널·모바일 제어를 최소 도구로 수행하고 성공한 실행 경로를 Memory/SOP/Skill로 축적하는 경량 자율 Agent 프레임워크다.


Quick Links

구분 링크 비고
GitHub Repository https://github.com/lsdefine/GenericAgent 공식 저장소
README https://github.com/lsdefine/GenericAgent/blob/main/README.md 프로젝트 개요, 기능, 데모
Getting Started https://github.com/lsdefine/GenericAgent/blob/main/GETTING_STARTED.md 설치·API Key·GUI·브라우저·봇 설정 안내
Datawhale Tutorial https://datawhalechina.github.io/hello-generic-agent/ 외부 튜토리얼/학습 문서
Technical Report https://arxiv.org/abs/2604.17091 GenericAgent: A Token-Efficient Self-Evolving LLM Agent via Contextual Information Density Maximization
Technical Report PDF https://arxiv.org/pdf/2604.17091 논문 PDF
Demo Assets https://github.com/lsdefine/GenericAgent/tree/main/assets/demo 저장소 내 실행 예시 GIF/PNG
Issues https://github.com/lsdefine/GenericAgent/issues 사용자 질문·버그·기능 요청 채널

분석 범위와 문서 상태

  • 확인한 주요 문서: README.md, GETTING_STARTED.md, pyproject.toml, mykey_template_en.py, assets/tools_schema.json, assets/sys_prompt_en.txt.
  • 확인한 주요 코드: agent_loop.py, agentmain.py, ga.py, llmcore.py, TMWebDriver.py, simphtml.py, reflect/, frontends/, memory/.
  • GitHub Wiki는 /wiki 접근 시 저장소 루트로 리다이렉트되어 별도 Wiki 콘텐츠가 확인되지 않았다. GitHub Discussions 탭도 저장소 상단 내비게이션에 노출되지 않았고, 관련 공개 Discussion 검색 결과도 확인되지 않았다. 현재 공개 커뮤니티 상호작용은 주로 Issues에서 이루어지는 것으로 보인다.

수집 이미지 자산 매핑

로컬 파일 원본 저장소 자산 설명하는 기능
figures/workflow.png assets/images/workflow.jpg Agent Loop, 원자 도구, Memory System의 상호작용 구조
figures/order_tea.png assets/demo/order_tea.gif의 대표 프레임 음식 배달 주문 자동화 예시
figures/selectstock.png assets/demo/selectstock.gif의 대표 프레임 정량 조건 기반 주식 스크리닝 예시
figures/autonomous_explore.png assets/demo/autonomous_explore.png 자율 웹/데이터 탐색 후 보고서화 예시
figures/alipay_expense.png assets/demo/alipay_expense.png ADB 기반 모바일 앱 지출 분석 예시
figures/wechat_batch.png assets/demo/wechat_batch.png WeChat 클라이언트 배치 메시지 자동화 예시

 

원본 애니메이션은 figures/order_tea_original.gif, figures/selectstock_original.gif로 함께 보관했다. 본문 이미지는 요청 규칙에 맞춰 PNG 경로로 배치했다.


Key Features

1. Self-Evolving Skill Tree: 작업 경로를 재사용 가능한 Skill/SOP로 결정화

GenericAgent의 핵심 주장은 “스킬을 미리 주입하지 않고 사용 중에 진화시킨다”는 것이다. 새로운 작업을 수행할 때 의존성 설치, 스크립트 작성, 디버깅, 검증을 거친 뒤 성공한 절차를 Memory Layer와 SOP에 저장하고, 이후 유사 작업에서 짧은 호출로 재사용한다. README는 예시로 WeChat 메시지 읽기, 주식 모니터링, Gmail 파일 전송 등을 제시한다.

 

기술적으로는 start_long_term_update가 장기 기억 정산을 시작하고, memory/ 폴더의 SOP 및 L4 raw session archive가 실행 경험의 보관소 역할을 한다. ga.pyturn_end_callback은 각 턴의 요약을 history에 누적하고, 일정 턴마다 실패 방지·전략 전환·메모리 재주입을 유도한다.

2. Minimal Toolset: 적은 도구로 파일·코드·브라우저·사용자 확인을 포괄

도구 스키마 기준 공개 Function Tool은 9개다. 이 중 code_run, file_read, file_write, file_patch, web_scan, web_execute_js, ask_user가 외부 세계와 직접 상호작용하는 핵심 원자 도구이고, update_working_checkpoint, start_long_term_update가 단기·장기 기억 관리 도구다. README와 아키텍처 이미지는 이를 “9 atomic tools” 또는 “7 atomic tools + memory tools”로 표현한다.

 

이 설계의 장점은 도구 설명과 라우팅 복잡도를 낮춰 컨텍스트 밀도를 유지한다는 점이다. 반대로 code_run이 임의 코드 실행권을 갖기 때문에, 실사용에서는 작업 디렉터리 제한, 권한 분리, 네트워크·파일 접근 정책이 필요하다.

3. Real Browser Control: 로그인 세션을 보존한 실제 브라우저 조작

TMWebDriver.py는 로컬 WebSocket/HTTP 브리지를 열고 브라우저 탭 세션을 등록한 뒤, web_execute_js를 통해 DOM 조작·페이지 전환·데이터 추출을 수행한다. simphtml.py는 숨김 요소, 스크립트, 스타일, 비가시 영역을 정리한 단순 HTML을 만들어 web_scan 결과의 토큰 사용량을 줄인다.

 

이 구조는 headless sandbox가 아니라 사용자의 실제 로그인 세션을 보존한 브라우저에 주입되는 방식이므로, 쇼핑·업무 포털·문서 사이트처럼 인증 상태가 필요한 작업에 강하다. 동시에 사용자의 로그인 세션을 다루므로 자동 제출, 결제, 개인정보 조회는 ask_user 같은 human-in-the-loop 확인과 결합되어야 한다.

 

그림: order_tea.gif의 대표 프레임. 자연어 지시를 주문 단계별 행동으로 분해하고, UI 상태를 읽어 다음 액션을 선택하는 실행 예시다.

4. Token Efficiency: Context Information Density Maximization

arXiv 기술 보고서는 장기 Agent 성능의 병목을 단순 컨텍스트 길이가 아니라 “제한된 컨텍스트 안에 의사결정에 필요한 정보가 얼마나 조밀하게 유지되는가”로 본다. GenericAgent는 이를 위해 최소 도구 세트, 계층적 on-demand memory, 성공 trajectory의 SOP화, 장기 실행 중 context truncation/compression을 결합한다.

 

README에서도 <30K 수준의 컨텍스트 사용을 강조하며, 긴 도구 설명과 대량 raw feedback을 매 턴 들고 가는 방식 대신 필요한 메모리만 재주입하는 접근을 취한다. agent_loop.py는 10턴마다 tool description cache를 리셋하고, ga.py는 working checkpoint와 history summary를 통해 장기 작업의 정보 손실을 줄인다.

5. Multi-Model Compatibility와 Failover

llmcore.py는 OpenAI 호환 Chat Completions, Claude 호환 Messages, Native OpenAI/Claude tool calling, 그리고 여러 세션을 묶는 MixinSession fallback을 지원한다. mykey_template_en.py는 변수명 규칙으로 세션 타입을 선택하는 방식을 제공한다. 예를 들어 native_claude_config, native_oai_config, mixin_config처럼 설정하면 실행 시 해당 세션 클래스로 라우팅된다.

 

실무 관점에서는 같은 Agent loop와 tool schema를 유지하면서 모델별 API 차이만 session layer에서 흡수하는 구조다. 모델 교체, 장애 시 fallback, 도구 호출 형식 호환성이 중요한 자동화 환경에 유리하다.

6. Multi-Frontend: CLI, Streamlit/Qt Desktop, Telegram, WeChat, QQ, Feishu, WeCom, DingTalk

frontends/에는 Streamlit UI, Qt UI, Telegram bot, 개인 WeChat bot, QQ, Feishu/Lark, WeCom, DingTalk용 엔트리포인트가 포함되어 있다. README는 기본 GUI 외에도 frontends/qtapp.py, frontends/stapp2.py, frontends/tgapp.py 등을 안내한다.

그림: WeChat batch 데모. Agent가 채팅 클라이언트 UI를 제어하고 전송 결과를 요약하는 흐름을 보여준다.

7. Mobile/ADB와 데이터 분석 자동화

README와 Getting Started는 ADB를 통한 Android 모바일 제어를 핵심 확장 능력으로 제시한다. memory/adb_ui.py, memory/ui_detect.py, memory/ocr_utils.py, memory/vision_sop.md 등의 파일은 모바일 UI 탐지, OCR, 시각적 작업 보조의 기반으로 보인다.

그림: Alipay Expense 데모. ADB/화면 인식/데이터 정리를 결합해 개인 지출 내역을 구조화하는 예시다.

8. Autonomous Exploration과 정량 작업 자동화

GenericAgent는 특정 분야별 플러그인을 선탑재하기보다, code_run으로 패키지를 설치하고 스크립트를 만들고 검증한 다음 절차를 저장한다. 주식 스크리닝 데모는 조건 계산, 데이터 검증, 보고서 작성까지의 긴 실행 경로를 예시로 보여준다.

그림: Quantitative Stock Screening 데모. Agent가 데이터 필드를 확인하고 계산 로직을 검증하며 조건 기반 스크리닝을 진행한다.

그림: Autonomous Web/Data Exploration 데모. 단순 조회가 아니라 실험 목표, 성능 기준, 데이터 정확성 검증을 보고서 구조로 남긴다.


Tech Stack

언어와 저장소 구성

항목 내용
주요 언어 Python 중심. GitHub language summary 기준 Python 94.9%, JavaScript 3.4%, Shell 1.1%
패키지 버전 pyproject.toml 기준 genericagent version 0.1.0
Python 요구사항 >=3.10,<3.14; Getting Started는 Python 3.11 또는 3.12 권장, 3.14 비권장
라이선스 MIT
릴리스 상태 GitHub Releases 페이지 기준 별도 release package는 없음. 태그는 존재하지만 release 항목은 비어 있음

Core Dependencies

범주 패키지/버전 역할
HTTP/API requests>=2.28 LLM API, 외부 HTTP 호출
HTML parsing beautifulsoup4>=4.12 단순 DOM/HTML 추출 보조
Web bridge bottle>=0.12, simple-websocket-server>=0.4 TMWebDriver의 HTTP/WebSocket 서버
GUI optional streamlit>=1.28, pywebview>=4.0 Streamlit UI와 desktop webview
Bot optional python-telegram-bot>=20.0, qq-botpy>=1.0, lark-oapi>=1.0, wecom-aibot-sdk>=1.0, dingtalk-stream>=0.20 Telegram, QQ, Feishu/Lark, WeCom, DingTalk frontends
WeChat/QR optional pycryptodome>=3.19, qrcode>=7.4 개인 WeChat bot 및 QR 로그인 보조

Source Tree 요약

경로 역할
agent_loop.py LLM 호출, tool call 파싱, handler dispatch, StepOutcome 기반 루프 종료/계속 제어
agentmain.py tool schema 로딩, system prompt와 global memory 조합, LLM session 초기화, task queue, CLI/reflect 모드
ga.py GenericAgentHandler와 실제 도구 구현. 파일, 코드 실행, 브라우저, memory update, plan mode 관련 로직
llmcore.py OpenAI/Claude/native tool calling/session history/mixin fallback 추상화
TMWebDriver.py 브라우저 탭 세션 등록과 JavaScript 실행 브리지
simphtml.py 페이지 DOM을 단순화해 web_scan의 토큰 사용량 절감
frontends/ Streamlit, Qt, Telegram, QQ, WeChat, Feishu, WeCom, DingTalk 인터페이스
memory/ L0/L2/L3/L4 성격의 SOP, 장기 기억, skill/search, vision/ADB/OCR 보조 코드
reflect/ autonomous/scheduler 계열 장기 실행·반사 모드 스크립트
assets/ system prompt, tool schema, demo/image assets, Feishu setup 문서
plugins/ Langfuse tracing 등 확장 플러그인

Architecture

그림: 저장소의 assets/images/workflow.jpg에서 가져온 아키텍처 다이어그램. Agent Loop는 sense-think-act 사이클로 도구를 호출하고, Memory System은 Meta-SOP, Global Facts, Task SOPs를 통해 세션 간 지속성을 제공한다.

1. Runtime Flow

User / Frontend
  └─> agentmain.GeneraticAgent task queue
        ├─ load_tool_schema(): assets/tools_schema*.json
        ├─ get_system_prompt(): assets/sys_prompt*.txt + Today + Global Memory
        ├─ llmcore session: OpenAI/Claude/Native/Mixin
        └─ agent_loop.agent_runner_loop()
              ├─ LLM response + tool_calls
              ├─ BaseHandler.dispatch(tool_name)
              ├─ ga.GenericAgentHandler.do_<tool>()
              ├─ StepOutcome(data, next_prompt, should_exit)
              └─ next prompt + tool_results로 다음 턴 진행

agent_runner_loop는 매 턴 LLM을 호출하고, tool call이 있으면 GenericAgentHandlerdo_<tool> 메서드로 dispatch한다. 도구 실행 결과는 StepOutcome으로 정규화된다. next_prompt가 없으면 현재 작업을 완료한 것으로 간주하고, should_exit가 참이면 사용자 개입 또는 강제 종료 흐름으로 빠진다.

2. Tool Layer

  • code_run: Python/PowerShell 또는 Unix 계열에서는 bash를 실행한다. 임시 .ai.py 파일을 만들고 assets/code_run_header.py가 있으면 선삽입한다.
  • file_read: 파일을 line range 또는 keyword 주변으로 읽고, 긴 내용을 truncation한다.
  • file_patch: old_content가 정확히 한 번만 매칭될 때 치환한다. 다중 매칭이나 미매칭이면 실패시켜 무분별한 overwrite를 막는다.
  • file_write: 대형 파일 작성용이며 <file_content> 또는 코드 블록에서 본문을 추출한다.
  • web_scan: TMWebDriver와 simphtml을 통해 현재 탭 목록과 단순 HTML을 반환한다.
  • web_execute_js: 브라우저 탭에서 JavaScript를 실행하고, 긴 결과는 파일로 저장할 수 있다.
  • ask_user: 결제, 삭제, 외부 전송 등 결정을 사용자에게 되묻는 interrupt 도구다.
  • update_working_checkpoint: 장기 작업 중 단기 working memory를 갱신한다.
  • start_long_term_update: 검증된 환경 사실, 사용자 선호, 복잡한 작업 경험을 L2/L3 memory로 정산하게 한다.

3. Memory Layer

README는 L0~L4 계층을 설명한다.

Layer 의미 구현상 관찰 포인트
L0 Meta Rules Agent의 행동 규칙, memory 관리 SOP memory/memory_management_sop.md, assets/sys_prompt*.txt
L1 Insight Index 빠른 라우팅/회상용 인덱스 memory/skill_search/, global_mem_insight*.txt 템플릿
L2 Global Facts 환경·경로·설정·사용자 선호 등 장기 사실 memory/global_mem.txt가 없으면 agentmain.py가 초기 생성
L3 Task Skills/SOPs 특정 작업 절차 memory/*_sop.md, autonomous_operation_sop/
L4 Session Archive 장기 세션 기록의 요약/보관 memory/L4_raw_sessions/

이 계층 구조는 긴 실행 중 모든 기록을 매번 컨텍스트에 넣지 않고, 필요한 인덱스와 요약만 먼저 노출한 뒤 필요 시 파일을 읽도록 설계된 것으로 해석된다.

4. Browser Layer

TMWebDriver127.0.0.1:18765 WebSocket 서버와 18766 HTTP 서버를 사용해 브라우저 탭을 session으로 등록한다. 각 탭은 URL, title, type을 가진 session으로 추적되고, execute_js 호출은 해당 session에 payload를 전달한 뒤 ACK/result를 기다린다.

이 방식은 다음 장점을 갖는다.

  • 로그인 세션이 유지된 실제 브라우저에서 조작 가능
  • 탭별 session ID 기반 전환 가능
  • JS return이 큰 경우 파일 저장 후 후속 분석 가능
  • DOM simplification으로 web_scan 비용 절감

한계도 명확하다. 실제 브라우저 세션을 쓰기 때문에 개인정보와 쿠키 노출 리스크가 있고, 자동화 실패 시 사용자가 보고 있는 UI에 직접 영향을 줄 수 있다.

5. Frontend and Operation Modes

  • 기본 CLI: python agentmain.py
  • GUI: python launch.pyw
  • Streamlit/Qt: frontends/stapp.py, frontends/stapp2.py, frontends/qtapp.py
  • Bot frontends: Telegram, QQ, WeChat, Feishu/Lark, WeCom, DingTalk
  • Reflect mode: python agentmain.py --reflect <SCRIPT> 형태로 감시 스크립트의 check() 결과를 task로 주입
  • Task file I/O mode: --task 옵션으로 input.txt, output*.txt, reply.txt 기반의 비대화형 실행 가능

Usage & Setup

권장 Python 버전

pyproject.toml은 Python >=3.10,<3.14를 요구한다. Getting Started 문서는 Python 3.11 또는 3.12를 권장하고, 3.14는 pywebview 등과 호환 이슈가 있을 수 있어 피하라고 안내한다.

표준 설치

git clone https://github.com/lsdefine/GenericAgent.git
cd GenericAgent

# 최소 의존성
pip install requests streamlit pywebview

# API Key 설정
cp mykey_template.py mykey.py
# mykey.py에 OpenAI 호환, Claude 호환, native_oai_config, native_claude_config 중 하나를 설정

# GUI 실행
python launch.pyw

uv 또는 editable 설치

git clone https://github.com/lsdefine/GenericAgent.git
cd GenericAgent
uv pip install -e ".[ui]"
cp mykey_template.py mykey.py
python launch.pyw

CLI 모드

python agentmain.py

첫 테스트로는 다음처럼 파일 생성 작업을 요청할 수 있다.

데스크톱에 hello.txt를 만들고 내용은 Hello World로 써줘.

Bot/Frontend 예시

# Telegram
python frontends/tgapp.py

# Qt desktop app
python frontends/qtapp.py

# Alternative Streamlit UI
streamlit run frontends/stapp2.py

# WeChat personal bot
pip install pycryptodome qrcode requests
python frontends/wechatapp.py

브라우저/시각/모바일 능력 해제 방식

이 프로젝트의 독특한 온보딩 방식은 “문서를 보고 수동으로 모든 것을 설치”하기보다, 실행 중인 Agent에게 다음과 같이 지시해 능력을 해제하게 하는 것이다.

실행 가능한 python 의존성을 코드에서 확인하고 필요한 패키지를 설치해줘.
web setup sop를 실행해서 브라우저 도구를 사용할 수 있게 해줘.
ADB 환경을 구성하고 Android 기기를 제어할 준비를 해줘.

저장소 내에 별도 설치 결과 터미널 스크린샷은 확인되지 않았다. 따라서 이 섹션에는 README와 Getting Started의 커맨드를 요약했다.


Personal Insights

의료 AI 관점

GenericAgent의 “실제 브라우저 + 파일 시스템 + 코드 실행 + 기억” 구조는 의료기관 내부 업무 자동화에 매력적이다. 예를 들어 문헌 검색, 임상시험 프로토콜 양식 정리, 병원 내부 포털의 반복 조회, 비식별 데이터셋 QC 보고서 작성처럼 긴 작업 흐름을 SOP로 축적할 수 있다.

다만 의료 AI에서 이 구조를 그대로 자율 실행시키는 것은 위험하다. code_run과 실제 브라우저 조작은 PHI/PII 노출, 잘못된 제출, 권한 없는 데이터 접근을 유발할 수 있다. 의료 환경에 적용하려면 다음이 선행되어야 한다.

  • EHR/EMR 접근은 읽기 전용 또는 명시적 allowlist 기반으로 제한
  • 환자 데이터는 비식별화 후 작업 공간으로 복사
  • 외부 전송, 처방, 예약, 비용 청구 등 irreversible action은 ask_user 또는 별도 승인 시스템으로 차단
  • 모든 tool call, 파일 변경, 브라우저 액션을 감사 로그로 보관
  • 모델 응답은 임상 판단이 아니라 행정·문헌·데이터 처리 보조로 한정

핵심 통찰은 GenericAgent가 “의료 판단 AI”보다 “의료 운영 자동화 Agent”로 더 자연스럽다는 점이다.

Bioinformatics 관점

Bioinformatics는 GenericAgent와 잘 맞는 분야다. 이유는 작업이 대개 긴 CLI 파이프라인, 의존성 설치, 로그 판독, 파일 변환, QC, 재실행, 보고서 작성으로 구성되기 때문이다. GenericAgent는 실패한 설치나 파이프라인 오류를 조사하고, 검증된 해결책을 L3 SOP로 축적하는 데 강점을 가질 수 있다.

예상 활용 예시는 다음과 같다.

  • FASTQ QC → trimming → alignment → variant calling → MultiQC 보고서 생성
  • conda/mamba 환경 구성 실패 원인 분석
  • Snakemake/Nextflow 로그 요약과 재시작 지점 제안
  • 논문 supplement 코드 재현을 위한 dependency probing
  • 데이터셋별 경로, reference genome, annotation version을 L2 memory에 보관

반드시 보완해야 할 점은 재현성이다. GenericAgent식 동적 패키지 설치와 스크립트 생성을 그대로 두면 결과가 drift될 수 있다. Bioinformatics 환경에서는 Docker/Singularity, conda lockfile, reference checksum, random seed, tool version pinning을 Agent가 자동 기록하도록 SOP를 강화해야 한다.

Autonomous Agent 개발 관점

GenericAgent의 설계상 가장 흥미로운 지점은 “큰 도구 목록을 제공하지 않고, 작은 원자 도구로 복잡한 능력을 합성한다”는 점이다. 이는 Agent 연구에서 중요한 trade-off를 건드린다.

  • 도구가 많을수록 즉시 가능한 행동은 많아지지만, 라우팅·오류·컨텍스트 비용이 커진다.
  • 도구가 적을수록 모델이 계획과 합성을 더 해야 하지만, 인터페이스가 안정적이고 memory/SOP의 가치가 커진다.
  • GenericAgent는 후자를 택해, 성공 trajectory를 Skill로 축적하는 방식으로 시간이 지날수록 개인화된 능력을 얻는다.

개발자 관점의 리스크는 “능력의 범용성”과 “안전 경계”가 같은 도구에서 나온다는 점이다. code_run 하나로 패키지 설치, 파일 조작, API 호출, 시스템 명령, 하드웨어 제어가 가능하다. 따라서 실제 제품화에는 다음 제약이 필요하다.

  • sandbox 또는 VM 내 실행
  • 작업별 filesystem allowlist
  • secrets redaction과 credential vault 분리
  • 외부 네트워크 호출 정책
  • destructive action 사전 감지와 approval gate
  • 장기 memory update의 provenance 기록

GenericAgent는 완성된 안전 제품이라기보다, “자가 진화형 로컬 Agent의 최소 실행 코어”로 보는 것이 적절하다. 의료·바이오·엔터프라이즈 영역에 적용할 때는 이 코어 위에 정책, 감시, 감사, 권한 분리 계층을 추가해야 한다.


핵심 평가

GenericAgent는 컨텍스트 정보 밀도, 최소 도구, 계층 메모리, self-evolution을 강하게 밀어붙이는 프로젝트다. 코드 크기 대비 구현 범위가 넓고, 브라우저·파일·터미널·모바일을 하나의 Agent loop 아래 묶는 방식이 실험적으로 가치 있다.

가장 큰 강점은 “반복 업무를 해결한 후 기억한다”는 방향성이고, 가장 큰 위험은 “실제 시스템에 대한 광범위한 제어권”이다. 연구·개인 자동화·재현 실험에는 매력적이지만, 고위험 업무 환경에서는 sandbox와 human approval을 전제로 도입해야 한다.


Sources