Agent Zero 깊게 살펴보기: 18.9k Star의 범용 Agent 프레임워크
GitHub에 Agent 프레임워크는 넘치지만, 실제로 돌아가면서 컴퓨터를 안 터뜨리는 건 드물다. Agent Zero는 그 중 하나다. 18.9k star에 Python으로 작성됐고, Docker로 AI를 샌드박스 안에 가둬서 실행한다.
직접 돌려봤고, 아래는 그 분석 내용이다.
이게 뭘 해결하나
2023년 AutoGPT가 한창일 때, 설치하고 첫 실행하고 후회한 사람이 많았다. Agent가 로컬 파일 시스템 권한을 그대로 받았기 때문에, prompt 하나 잘못 쓰면 rm -rf /가 실제 실행됐다. 웃긴 게 아니라 위험한 얘기다.
Agent Zero의 접근은 단순하다. Agent를 Docker 컨테이너 안에 넣는다. 터미널, 브라우저, 파일 읽기/쓰기 같은 도구 권한은 그대로 주되, 물리적으로 격리한다. 동시에 "과정 투명성"을 강조해서, 매思考 단계와 도구 호출을 전부 사용자에게 보여준다.
이 포지셔닝은 양 극단 사이의 어딘가다:
- AutoGPT: 구조 없이 Agent가 도구를 만들고流程도 스스로 정한다. 자유도는 높지만 통제도 어렵다
- LangGraph: 상태 머신 기반의 고도화된 구조. 통제력은 좋지만 구축이 번거롭다
- Agent Zero: 바로 쓸 수 있는 Agent + 샌드박스 + UI를 제공한다. 별도 설치 없이 동작하지만, 흐름을 강제하지는 않는다
사용 방법
먼저 Docker Desktop을 설치하고, 저장소를 clone한다.
git clone https://github.com/agent0ai/agent-zero
cd agent-zero
./run.sh
시작 스크립트가 자동으로 컨테이너를 build하고, 작업 디렉토리를 마운트하고, API key를 설정하게 해준다. 완료되면 브라우저에서 Web UI를 열면 되고, 더 이상 명령줄을 만질 필요는 없다.
설정은 conf/agent-zero.ini의 ini 파일을 통해 진행한다:
[llm]
provider = openai # anthropic / ollama / 기타도 지원
model = gpt-4o
api_key = sk-xxx
UI에 들어가서 Agent에 prompt를 준다. 예를 들어 "GitHub에서 가장 인기 있는 Python 웹 프레임워크 5개를 조사해줘" 같은 식이다. 그러면 Agent가 알아서 움직이는 걸 볼 수 있다.
동작 원리 (아키텍처)
3계층 구조로 되어 있고, 대략 이렇게 그릴 수 있다:
┌─────────────────────────────┐
│ 메인 Agent (Agent Zero) │ ← 진입점, 요청 접수·작업 분해
└──────────────┬──────────────┘
│ 동적 생성
┌──────────────┐
▼ ▼
┌──────────┐ ┌──────────┐
│ 서브 Agent │ │ 서브 Agent │ ← 독립적인 서브 작업 처리
└────┬─────┘ └────┬─────┘
│ │
▼ ▼
─────────────────────────────
│ 도구 계층 (터미널/파일/브라우저) │
└─────────────────────────────┘
│
▼
┌─────────────────────────────┐
│ Docker 샌드박스 (실행 격리) │
└─────────────────────────────┘
핵심 포인트 몇 가지:
- 메인 Agent가 진입점이다. 요청을 받고, 작업을 분해하고, 서브 Agent에게 일을 맡길지 결정한다
- 서브 Agent는 메인 Agent가 동적으로 생성한다. 각 서브 Agent는 독립적인 서브 작업을 처리하고, 끝나면 결과를 메인 Agent에 보고한다
- 도구 계층은 터미널 실행, 파일 읽기/쓰기, 브라우저 자동화(Playwright), 코드 실행을 캡슐화한다
- 기억 시스템은 두 층으로 나뉜다: 단기(현재 세션의 context window)와 장기(跨 세션의 벡터 저장소/파일)
- Docker 컨테이너가 실행 격리를 담당한다. 모든 shell 명령과 파일 작업이 컨테이너 안에서 돌아가기 때문에 호스트를 오염시키지 않는다
핵심 루프는 ReAct 패턴이다: 思考 → 도구 선택 → 실행 → 결과 관찰 → 반복.
장점과 단점
장점
- Docker 격리가 실제로 작동한다. Agent가
rm -rf /를 작성해도 터지는 건 컨테이너다 - 설정이 단순하다. ini 파일에 LLM만 지정하면 바로 돌아간다. 프레임워크 개념을 새로 배울 필요가 없다
- Web UI가 잘 만들어졌다. 매 단계가 시각화돼서 순수 명령줄보다 디버깅이 훨씬 친절하다
- 다중 Agent 협업의 계층 구조가 복잡한 작업에 유용하다. 예를 들어 "프레임워크 5개 조사"는 5개의 서브 Agent가 병렬로 돌릴 수 있다
- 커뮤니티가 활발하다. 18.9k star에 issue와 PR 모두 빠르게 반응이 온다
단점
- 의존성이 무겁다. Docker가 필수고, 디스크 점유 5GB 이상, 부팅도 느리다
- Agent 행동의 예측 불가능성. 복잡한 작업에서 무한 루프에 빠지기 쉽다. 같은 도구를 반복 호출하다 token을 다 태워버린다
- 디버깅이 어렵다. 에러가 났을 때 로그만 볼 수 있고, Agent의 "思考" 과정은 보이지만 근본 원인 분석은 찍어야 한다
- token 소모가 크다. 아래에서 실행한 작업 하나에 12k tokens이 들어갔고, 복잡한 작업은 백만을 넘기기 쉽다
- 한국어 환경에서는 도구 호출 정확도가 영어보다 떨어진다. Prompt의 한국어 설명 때문에 Agent가 잘못된 도구를 고르는 경우가 있다
LangGraph와 비교하면 구조화 정도는 낮지만, 진입 장벽이 10분의 1이다. AutoGPT와 비교하면 안전성과 안정성이 훨씬 낫다.
직접 돌려봤다
기종: 8GB 메모리 Mac mini (M1).
작업 prompt:
"Python으로 크롤러를 만들어서 Hacker News 首页의 제목을 가져오고 CSV로 저장해줘."
Agent는 약 4분 동안 8단계로 작업을 진행했다:
- 작업 분해 思考 (requests, beautifulsoup4 필요)
- terminal 도구 호출:
pip install requests beautifulsoup4 - 크롤러 코드를 `/work_dir/hn_scraper.py`에 작성
- 테스트 실행
- 구문 오류 발견 (자기가 짠 코드에 버그가 있었음)
- 디버깅, 코드 수정
- 재실행, 또 버그
- 재디버깅 후 성공, CSV 파일이 작업 디렉토리에 생성됨
전체 과정에서 약 12k tokens이 소비됐다 (GPT-4o).
최소 실행 흐름 예시 (README 및 실제 설정 기반):
# Agent Zero의 최소 실행 흐름
# 1. 클론 및 실행
# git clone https://github.com/agent0ai/agent-zero
# cd agent-zero && ./run.sh
# 2. LLM 설정 (conf/agent-zero.ini)
[llm]
provider = openai # anthropic / ollama도 지원
model = gpt-4o
api_key = sk-xxx
# 3. Agent에게 작업 부여 (Web UI 또는 API)
prompt = """
작업: Python으로 크롤러를 만들어서 Hacker News 首页의 모든 제목과 링크를 가져오고 CSV 파일로 저장해줘.
요구사항: 페이지네이션 처리, 최소 3페이지 데이터를 수집.
"""
# Agent는 자동으로:
# - 작업 분해를 思考하고
# - terminal 도구를 호출해 의존성(requests, beautifulsoup4)을 설치하고
# - /tmp 파일에 코드를 작성하고
# - 실행 및 디버깅을 수행하고
# - 작업 디렉토리에 최종 결과를 출력한다
# 4. 핵심 설정: 작업 디렉토리 마운트
# Docker 실행 시 ./work_dir가 컨테이너의 /work_dir로 자동 마운트된다
# Agent의 모든 파일 작업은 이 디렉토리 안에서 일어난다
겪었던 문제들:
- 첫 번째 코드에 구문 오류가 있어서, Agent가 두 번 디버깅해야 통과했다
- 더 복잡한 작업(예: "완전한 웹 애플리케이션 만들어줘")의 경우 Agent가 도구를 반복 호출하면서 token을 빠르게 소진한다
- 8GB 메모리에서 돌리니 빠듯했다. Docker + Python + 브라우저 도구(Playwright)가 RAM을 꽤 먹는다
이런 사용자에게 추천
적합한 경우:
- Agent 기능을 빠르게 경험해보고 싶고, 프레임워크를 처음부터 만들고 싶지 않은 사람
- 연구·데이터 처리 작업 (크롤링, 데이터 정제, 리포트 생성)
- 로컬 배포가 필요하거나 데이터 프라이버시가 중요한 시나리오 (데이터가 본機を 벗어나지 않음)
- 다중 Agent 협업 데모를 만들고 싶은 사람
적합하지 않은 경우:
- 운영 환경의 비즈니스 시스템 (안정성이 부족해 SLA 보장 불가)
- 엄격하게 통제된 실행 흐름이 필요한 시나리오 (LangGraph가 더 적합)
- 저사양 머신 (Docker + LLM API 둘 다 리소스를 많이 먹는다)
- 순수 프론트엔드/디자인 작업 (Agent가 잘 못한다)
Agent 프레임워크를 처음 만져보는 사람에게는 여기서 시작하는 걸 추천한다. AutoGPT보다 안전하고, LangGraph보다 단순하고, ReAct 루프를 직접 짜는 것보다 훨씬 편하다.
Agent Zero는 은탄환(silver bullet)은 아니다. 하지만 "Agent가 샌드박스 안에서 자율적으로 일한다"는 패턴을 실제로 쓸 수 있는 제품으로 만들어냈다. Agent 프레임워크의 동작 원리를 이해하고 싶으면서 설정에 지치고 싶지 않은 사람에게는 좋은 출발점이다.