주요 콘텐츠로 건너뛰기
AI 튜토리얼

IvyClaw 실전 가이드: 계획, 코딩, 테스트 및 검토 역량을 갖춘 멀티 에이전트 연구개발 시스템 구축

이 글에서는 IvyClaw의 핵심 아키텍처, 환경 구성, API 및 비동기 작업 시작 방식을 소개하고, 엔지니어링 관점에서 멀티 에이전트 협업, 샌드박스 실행, 영속성, 사람의 승인, 관측 가능성 및 프로덕션 배포를 설명합니다.

약 16분 소요
IvyClaw 실전 가이드: 계획, 코딩, 테스트 및 검토 역량을 갖춘 멀티 에이전트 연구개발 시스템 구축

1. IvyClaw란 무엇인가

IvyClaw는 소프트웨어 개발 작업을 위한 멀티 에이전트 AI Agent 엔지니어링 시스템으로, DeepAgents와 LangGraph를 기반으로 구축되었습니다. 단 한 번의 대규모 모델 호출만 실행하는 것이 아니라 요구사항 이해, 작업 계획, 자료 검색, 코드 구현, 자동 테스트, 코드 리뷰 및 결과 반환을 지속적으로 실행 가능한 Agent Workflow로 구성합니다.

이 프로젝트는 Python, FastAPI, PostgreSQL, Redis, ARQ, Docker, Prometheus, Grafana 등의 기술을 사용하며, AI Agent의 엔지니어링 적용을 학습하고 실습하는 데 적합합니다.

다만 저장소의 일부 기능은 아직 엔지니어링 프로토타입 또는 데모 구현 단계입니다. 프로덕션 환경에서 사용하려면 인증, 권한 제어, 보안 격리 및 인프라 설정을 추가로 보완해야 합니다.

프로젝트 주소: IvyClaw GitHub Repository.

2. 핵심 워크플로와 시스템 아키텍처

IvyClaw는 하나의 개발 요청을 여러 전문 Agent로 분할합니다. 일반적인 흐름은 다음과 같습니다.

User Request
      ↓
   Gateway
      ↓
  Dispatcher
      ↓
   Planner
      ↓
Researcher（필요 시）
      ↓
    Coder
      ↓
   Tester
      ↓
  Reviewer
      ↓
Final Response

Planner는 요구사항을 이해하고 작업을 계획하며 의사결정을 수행합니다. Researcher는 필요할 때 자료를 검색하고 정리합니다. Coder는 코드를 구현하고 수정합니다. Tester는 테스트를 실행하고 문제를 찾습니다. Reviewer는 최종 결과를 코드 리뷰합니다.

요청은 일반적으로 먼저 API Gateway로 들어간 다음 채널 어댑터와 Dispatcher를 거쳐 Agent Runtime에 전달됩니다. PostgreSQL은 세션 상태와 LangGraph Checkpointer 및 Store 데이터를 영속화하고, Redis는 캐시, 속도 제한, 런타임 상태 및 작업 큐에 사용됩니다. 시간이 오래 걸리는 작업은 ARQ Worker가 비동기로 처리합니다.

3. 실행 환경 준비

시작하기 전에 Python 프로젝트 실행 환경, 사용 가능한 PostgreSQL 및 Redis 서비스, 그리고 프로젝트 설정 요구사항에 맞는 모델 API를 준비해야 합니다. 이 프로젝트는 uv로 Python 의존성을 관리합니다.

먼저 저장소를 복제하고 프로젝트 디렉터리로 이동합니다.

git clone https://github.com/ivyfan-toowell/IvyClaw.git
cd IvyClaw

그다음 예제 파일에서 로컬 환경 설정을 생성합니다. Linux, macOS 또는 Unix 계열 환경에서는 다음을 실행할 수 있습니다.

cp .env.example .env

Windows PowerShell에서는 다음을 실행할 수 있습니다.

Copy-Item .env.example .env

.env 파일에 로컬 환경에 맞는 필수 설정을 입력합니다. 예시는 다음과 같습니다.

IVC_API_KEY=your_api_key_here
IVC_POSTGRES_URL=postgresql://user:password@localhost:5432/ivyclaw
IVC_DATABASE_URL=postgresql://user:password@localhost:5432/ivyclaw
IVC_REDIS_URL=redis://localhost:6379/0

실제 .env 파일을 GitHub에 커밋하지 마세요. LLM API Key, LangSmith API Key, Feishu App Secret, 데이터베이스 비밀번호 및 실제 게이트웨이 API Key 등의 민감한 정보는 로컬 또는 안전한 배포 환경에 보관해야 합니다.

4. 의존성 설치 및 서비스 시작

Python 의존성 설치

프로젝트 루트 디렉터리에서 다음을 실행합니다.

uv sync

이 명령은 프로젝트 설정에 따라 Python 환경과 의존성을 동기화합니다.

FastAPI API 시작

다음 명령으로 개발 서버를 시작합니다.

uv run uvicorn api.app:app --reload --port 8000

시작 후 http://localhost:8000/docs를 열면 FastAPI가 자동 생성한 Swagger API 문서를 확인할 수 있습니다.

ARQ Worker 시작

시간이 오래 걸리는 Agent 작업을 처리하려면 다른 터미널에서 ARQ Worker도 시작해야 합니다.

uv run arq tasks.worker.WorkerSettings

요청은 Redis 큐를 통해 Worker에 제출되며, Worker가 Agent Runtime을 호출하고 작업 결과를 영속화합니다. 비동기 작업 흐름에는 일반적으로 Job ID, 작업 상태 조회, 백그라운드 실행, 멱등성 제출 및 결과 조회가 포함됩니다.

Feishu 장기 연결 시작

Feishu WebSocket 연결을 사용해야 하는 경우 다음을 실행할 수 있습니다.

uv run python -m channels.feishu_ws

IvyClaw는 Feishu Webhook, Generic Webhook 및 CLI 등의 진입점도 지원합니다. 서로 다른 채널의 요청은 통일된 InboundMessage로 변환된 후 동일한 handle_message() 및 Agent 처리 로직을 재사용합니다.

5. Agent의 도구 호출 이해하기

IvyClaw는 각 Agent에 담당 업무에 맞는 최소한의 도구 세트를 할당하여 불필요한 호출과 오작동 위험을 줄입니다. 프로젝트가 지원하는 도구 유형은 다음과 같습니다.

  • Git: 코드 버전을 확인하고 조작합니다.
  • pytest: 자동화 테스트를 실행합니다.
  • Python 및 Shell: 개발 명령을 실행합니다.
  • Web Search: Tavily 또는 Exa를 통해 정보를 검색합니다.
  • MCP: 외부 도구와 서비스에 연결합니다.
  • File Tools: 작업 영역의 파일을 읽고 수정합니다.
  • Sandbox: Agent가 생성한 코드를 격리된 환경에서 실행합니다.

또한 프로젝트는 skills/를 통해 재사용 가능한 개발 프로세스를 축적합니다. 여기에는 요구사항 명확화, 체계적인 디버깅, 테스트 주도 개발, 단위 테스트 및 완료 전 검증이 포함됩니다. 대표적인 디렉터리는 다음과 같습니다.

skills/
├── fastapi-endpoint/
├── requirements-clarification/
├── systematic-debugging/
├── test-driven-development/
├── unit-test/
└── verification-before-completion/

6. 코드 샌드박스와 안전한 실행

Agent가 생성한 코드는 주요 서비스 프로세스에서 직접 실행되지 않고 격리된 환경에 배치하여 실행할 수 있습니다. IvyClaw는 Docker Sandbox와 Daytona Sandbox를 지원하며 Python, pytest, Git 등의 명령 실행도 지원합니다.

샌드박스 기능에는 독립적인 작업 디렉터리, 샌드박스 재사용 및 수명 주기 관리, CPU, Memory 및 PID 등의 리소스 제한이 포함됩니다. 프로덕션 환경에서는 기본적으로 Docker Sandbox를 사용하며, gVisor 또는 Kata와 같은 더욱 강력한 격리 런타임으로 확장할 수 있는 여지도 제공합니다.

샌드박스를 설정할 때는 실제 위험 평가를 바탕으로 네트워크 권한, 파일 접근 범위, 리소스 한도 및 동시 실행 규모를 결정해야 합니다. README에서도 프로덕션 환경의 보안 격리를 추가로 강화해야 하며, 현재 데모 설정을 완전한 보안 솔루션으로 간주해서는 안 된다고 명시합니다.

7. 상태 영속화와 비동기 작업

영속화 구성 요소

PostgreSQL은 주로 LangGraph Checkpointer, Store, 세션 상태 및 기타 영속화 데이터를 저장합니다. Redis는 캐시, 속도 제한, 작업 큐 및 런타임 상태 등을 담당합니다. Checkpointer와 Store를 사용하면 Agent 실행 컨텍스트를 여러 요청에 걸쳐 지속적으로 유지할 수 있습니다.

비동기 작업 흐름

실행 시간이 긴 개발 작업은 FastAPI가 작업을 생성하고 Redis와 ARQ Worker가 비동기로 처리하도록 구성하는 것이 좋습니다.

Client
  ↓
FastAPI
  ↓
Create Job
  ↓
Redis Queue
  ↓
ARQ Worker
  ↓
Agent Runtime
  ↓
Persist Result
  ↓
Query Job Status

이 방식은 동기 HTTP 요청을 장시간 점유하는 것을 방지하고, 작업 상태 조회, 재시도 및 결과 영속화를 위한 기반을 제공합니다.

8. Human-in-the-Loop: 고위험 작업에 승인 추가

파일 삭제나 파괴적인 수정 실행과 같은 작업은 완전히 자동화하기에 적합하지 않습니다. IvyClaw는 Human-in-the-Loop를 지원하므로 Agent가 고위험 도구 호출을 요청하면 실행을 중단하고 사람의 결정을 기다릴 수 있습니다.

Agent requests risky action
          ↓
       Interrupt
          ↓
    Human Approval
       ↓       ↓
    Approve   Reject
       ↓
 Command(resume)
       ↓
Agent continues

사람이 승인하면 재개 명령을 통해 실행을 계속합니다. 거부할 경우 현재 흐름을 종료하거나 변경합니다. 이 메커니즘은 자동화 효율성과 작업 안전성 사이에 제어 지점을 마련합니다.

9. 게이트웨이, 멀티테넌시 및 안정성 관리

요청은 Agent Runtime에 들어가기 전에 게이트웨이 계층을 거치며, 이곳에서 신원 확인과 기본적인 거버넌스가 수행됩니다. 현재 저장소가 제공하는 기능은 다음과 같습니다.

  • API Key 인증.
  • Tenant 식별 및 격리.
  • Rate Limit 속도 제한.
  • Idempotency 멱등성 제어.
  • Request Context 요청 컨텍스트.
  • Audit Log 작업 감사.

README에서는 현재 Key와 Tenant가 주로 데모 설정으로 사용된다고 설명합니다. 프로덕션 환경에서는 데이터베이스 또는 전용 인증 시스템을 연동하고, 테넌트 권한과 데이터 격리를 추가로完善해야 합니다.

인프라 계층은 Retry, Timeout, Fallback, Concurrency Control, PostgreSQL Connection Pool, Redis Connection Pool 및 Sandbox Pool 등의 메커니즘도 제공하여 높은 동시성, 모델 오류 및 인프라 불안정에 대응합니다.

10. 관측 가능성, 테스트 및 평가

IvyClaw는 다양한 관측 가능성 구성 요소를 통합합니다. LangSmith는 Agent 및 LLM 호출 체인을 추적하고, Prometheus는 지표를 수집하며, Grafana는 시각화 모니터링을 담당합니다. 이 밖에도 구조화 로그와 감사 로그를 제공합니다.

런타임에서는 다음 지표를 중점적으로 확인할 수 있습니다.

  • 요청 지연 시간 및 오류율.
  • 동시 요청 수.
  • LLM 호출 횟수.
  • Token 사용량 및 비용.
  • ARQ Worker 상태.
  • Sandbox 상태.

프로젝트에는 tests/, eval/ 및 loadtest/ 디렉터리도 포함되어 있습니다. 여기에는 pytest 자동화 테스트, Agent Runtime 테스트, Code Cases, Execution Scorer, LLM Judge, Baseline Evaluation, Reviewer Flow Test 및 Locust 부하 테스트가 포함됩니다.

Agent의 신뢰성을 한 번의 수동 대화만으로 판단하기보다는 “개발, 자동화 테스트, Agent Evaluation, 부하 테스트, 지표 관찰, 문제 개선”의 순서로 검증 루프를 구축하는 것이 좋습니다.

11. Docker 프로덕션 배포

전체 서비스 스택을 시작하려면 저장소에서 제공하는 프로덕션 Compose 설정을 사용할 수 있습니다.

docker compose -f docker-compose.prod.yml up -d --build

프로덕션 배포에는 FastAPI 웹 서비스, ARQ Worker, Feishu 서비스, PostgreSQL, Redis, Prometheus 및 Grafana가 포함됩니다. API와 Worker는 Agent Runtime에 함께 액세스할 수 있으며, Agent Runtime은 Docker Sandbox를 통해 생성된 코드를 실행합니다.

정식 출시 전에 데이터베이스와 Redis 연결, 비밀 정보 관리, API 인증, 테넌트 격리, 속도 제한 정책, 샌드박스 리소스 제한, 로그 감사 및 모니터링 알림 구성을 점검해야 합니다.

12. 프로젝트 구조로 코드 찾기

디렉터리 구조를 익히면 기능을 빠르게 확장할 수 있습니다.

IvyClaw/
├── agent/          # 메인 Agent 및 작업 스케줄링
├── api/            # FastAPI API
├── channels/       # CLI / Feishu / Webhook 연동
├── gateway/        # API 인증, Tenant, 속도 제한
├── infra/          # PostgreSQL, Redis, LLM Router
├── middleware/     # 요청 컨텍스트, 동시성, 감사, 비용 통계
├── obs/            # Metrics 및 관측 가능성
├── profiles/       # 모델 및 Agent Profile
├── sandbox/        # Docker / Daytona 샌드박스
├── skills/         # Agent Skills
├── subagents/      # Planner / Researcher / Coder / Tester / Reviewer
├── tasks/          # ARQ 비동기 작업
├── tools/          # Git / pytest / Search / MCP 도구
├── eval/           # Agent Evaluation
├── loadtest/       # Locust 부하 테스트
├── tests/          # 자동화 테스트
├── scripts/        # 개발, 테스트 및 데모 스크립트
├── web/            # Web UI
├── Dockerfile
├── docker-compose.prod.yml
├── pyproject.toml
└── .env.example

13. 실전 사용 권장 사항

  1. 먼저 .env, PostgreSQL 및 Redis를 구성하고 API가 Swagger 문서를 통해 액세스 가능한지 확인합니다.
  2. 먼저 동기 API 또는 CLI로 기본 Agent Workflow를 검증한 다음, ARQ Worker를 시작해 장시간 작업을 처리합니다.
  3. Coder, Tester 및 Reviewer의 도구 권한을 각각 점검하여 단일 Agent에 불필요한 고위험 기능을 할당하지 않도록 합니다.
  4. 생성된 코드에는 샌드박스 실행을 활성화하고 CPU, 메모리, 프로세스 수 및 작업 디렉터리에 합리적인 제한을 설정합니다.
  5. 삭제 또는 파괴적인 수정이 관련된 경우 Human-in-the-Loop를 활성화하고 기본적으로 자동 승인하지 않도록 합니다.
  6. LangSmith, Prometheus, Grafana 및 구조화된 로그를 통해 요청 경로, 비용, 지연 시간 및 오류를 관찰합니다.
  7. 출시 전에 pytest, Agent Evaluation 및 Locust 부하 테스트를 실행하고 결과에 따라 모델 라우팅, 동시성 및 재시도 정책을 조정합니다.

맺음말

IvyClaw의 핵심은 단일 모델 호출이 아니라 멀티 에이전트 협업, 도구 호출, 코드 샌드박스, 상태 지속성, 비동기 실행, 인간 승인, 게이트웨이 거버넌스 및 관측 가능성을 하나의 소프트웨어 연구개발 Agent 엔지니어링 시스템으로 결합하는 데 있습니다.

로컬 실행을 완료한 후에는 기존 subagents/, tools/ 및 skills/부터 살펴보며 Planner, Researcher, Coder, Tester 및 Reviewer의 협업 방식을 단계적으로 이해할 수 있습니다. 그런 다음 비즈니스 요구 사항에 따라 채널, 도구 또는 평가 프로세스를 확장하면 됩니다.