AgentLoom

간단한 설정, 최소한의 글루 코드 (glue code), 안전한 런타임 제어, 그리고 일급 수준의 관측성 (observability)을 통해 복잡한 멀티 에이전트 애플리케이션을 구축하세요.

AgentLoom은 개발자가 멀티 에이전트 워크플로우를 실행 가능하고, 관측 가능하며, 재개 가능하고, 제어 가능한 애플리케이션으로 전환할 수 있도록 돕습니다.

AgentLoom은 저장소 클론(repository clone)부터 실제 멀티 에이전트 애플리케이션 구축까지 빠르게 도달할 수 있도록 설계되었습니다.

git clone <repo-url> AgentLoom
cd AgentLoom
uv sync
...

첫 실행 후, 다음과 같은 사항을 확인할 수 있습니다:

• 에이전트 이름, 태스크 ID (task IDs), 단계 지속 시간, 토큰 사용량이 포함된 구조화된 터미널 로그;
• .logs/<agent>/<timestamp>/ 아래에 아카이브된 실행 파일;
• 체크포인팅 (checkpointing)이 활성화되었을 때의 재개 가능한 태스크 상태;
• uv run loom ui를 통한 선택적 시각화;
• uv run loom dashboard를 통한 선택적 터미널 모니터링.

AgentLoom은 복잡한 에이전트 애플리케이션을 구축하고 운영하는 데 필요한 런타임 구성 요소들을 이미 구현하고 있습니다:

영역	구현된 기능
멀티 에이전트 앱 조립	Supervisor / Worker 역할, YAML workflow, worker_agents, 직접적인 loom run, loom create를 통한 생성된 엔트리 스크립트 (entry scripts), 그리고 run_app()을 통한 Python 임베딩 (embedding).
...

많은 에이전트 프레임워크가 구성 요소(components)를 제공한다면, AgentLoom은 애플리케이션의 형태를 제공합니다.

복잡한 에이전트 애플리케이션은 종종 다음과 같은 동일한 글루 코드 (glue code)를 반복해서 작성하게 됩니다: Worker 등록, 파라미터 어댑터 (parameter adapters), 런타임 엔트리포인트 (runtime entrypoints), 전/후 처리 (pre/post processing), 배치 실행 (batch execution), 로깅 (logging), 트레이싱 (tracing), 그리고 안전 제어 (safety controls). 이러한 코드는 다음 에이전트 애플리케이션의 워크플로우가 달라질 경우 재사용하기가 어렵기 때문에 비용이 많이 듭니다.

Worker Agents는 호출 가능한 도구 (callable tools)로 내보내지며, Supervisor Agents가 이를 자동으로 로드하고 스케줄링합니다. 이는 복잡한 워크플로우가 집중된 에이전트들, 적은 양의 비즈니스 글루 코드, 그리고 직접적인 런타임 엔트리포인트를 통해 조립될 수 있음을 의미합니다.

AgentLoom은 재사용 가능한 구성 요소들을 YAML과 런타임 (runtime)으로 이동시킵니다. YAML은 워크플로우 (workflow), 워커 (Worker) 목록, 도구 (tools), 모델 (models), 권한 (permissions), 그리고 스킬 (skills)을 기술합니다. 워커는 호출 가능한 도구가 되며, 슈퍼바이저 (Supervisors)가 이를 자동으로 로드합니다. Python은 전처리 (preprocessing), 후처리 (postprocessing), 캐싱 (caching), 루프 (loops), 검증 (validation), 그리고 아티팩트 쓰기 (artifact writing)와 같은 애플리케이션 특정 부분에 집중할 수 있습니다. 스킬 (Skills)과 훅 (Hooks)은 라이프사이클 동작을 패키징하여 여러 애플리케이션에서 재사용할 수 있도록 합니다.

다음 명령어로 시작할 수 있습니다:

uv run loom run <workflow>

애플리케이션을 직접 실행하려면 사용합니다;
uv run loom create <workflow>

Python 엔트리 스크립트 (entry script)를 생성하려면 사용합니다;
run_app("<workflow>")

자신의 Python 파이프라인 (pipeline) 내에 AgentLoom 앱을 임베딩 (embed)하려면 사용합니다;
tool.batch(tasks)

동일한 워커 에이전트 (Worker Agent)를 여러 입력에 대해 병렬로 호출하려면 사용합니다.

이것이 핵심적인 개발 사이클 (development-cycle)의 이점입니다. 오케스트레이션 (orchestration) 배관 작업을 구축하는 데 드는 시간은 줄이고, 실제 에이전트 역할, 도구, 그리고 태스크 흐름 (task flow)을 형성하는 데 더 많은 시간을 할애할 수 있습니다.

일반적인 에이전트 프레임워크 패턴	AgentLoom의 접근 방식
컴포넌트 우선 (Component-first): 사용자가 저수준 프리미티브 (low-level primitives)를 직접 조립합니다.	애플리케이션 우선 (Application-first): 멀티 에이전트 (multi-agent) 앱을 직접 실행, 생성, 임베딩, 모니터링 및 재개할 수 있습니다.
...

AgentLoom의 핵심 모델은 간단합니다:

flowchart LR
User["Application / CLI"] --> Supervisor["Supervisor Agent"]
Supervisor --> WorkerA["Worker Agent as Tool"]
...

중요한 부분은 경계 (boundary)입니다:

• 워커 에이전트는 자신의 목적, 도구, 입력 및 출력 계약 (output contract)을 정의합니다.
• AgentLoom은 해당 워커를 실제 함수 시그니처 (function signature)를 가진 호출 가능한 Python 도구로 변환합니다.
• 슈퍼바이저는 워커를 도구처럼 호출하여 전체 태스크를 조정합니다.
• 비즈니스 Python은 스캐닝 (scanning), 캐싱 (caching), 검증 (validation), 인자 파싱 (argument parsing), 그리고 아티팩트 쓰기 (artifact writing)와 같은 결정론적 단계 (deterministic steps)를 위해 여전히 워크플로우를 감쌀 수 있습니다.

보통 글루 코드 (Glue Code)가 되는 작업	AgentLoom 배치
재사용 가능한 에이전트 오케스트레이션	YAML workflow 및 worker_agents
...

repo_map

애플리케이션은 이러한 하이브리드 방식을 보여줍니다: 결정론적 (deterministic) Python 스캔이 저장소를 스캔하고 순위를 매기면, AgentLoom이 Worker Agents를 호출하여 디렉토리를 분석하고 아키텍처 문서를 생성합니다.

applications/ 디렉토리는 AgentLoom이 어떻게 사용되도록 설계되었는지를 보여주는 작동 가능한 앱들을 포함하고 있습니다.

애플리케이션	생성 대상	시연 내용
ai_quality_analysis	다차원 코드 리뷰 애플리케이션	12개의 Worker Agents, 단계별 리뷰 (staged review), 직접적인 loom run 실행, 장시간 실행되는 코드베이스 분석
unit_test_studio	Python pytest 생성 워크플로우	엄격한 다단계 파이프라인 (multi-step pipeline), 커스텀 엔트리 스크립트, 함수 입력, 시나리오 계획, 테스트 생성, 정교화 (refinement), 결과 보고서
repo_map	저장소 아키텍처 맵 생성기	결정론적 (deterministic) Python 전처리 및 에이전트 기반 분석, 상향식 (bottom-up) 디렉토리 처리, tool.batch(tasks), 진행 상황 유지 (progress persistence)
codex_exec_demo	로컬 Codex Exec 도구 호출 예시	직접적인 loom run 실행, 일반 함수 도구 등록, Codex 파라미터를 위한 fixed_args, 구조화된 tool_call 시퀀싱

기본 코드 리뷰 예제를 실행합니다:

uv run loom run applications/ai_quality_analysis/workflows/code_review_agent.yaml

커스텀 Python 엔트리포인트로 Repo Map을 실행합니다:

uv run python applications/repo_map/repo_map_app.py /path/to/project \ 
--output_dir /tmp/repo-map-output \ 
--exclude_dirs vendor \ 
... 

선택한 함수에 대해 pytest 테스트를 생성합니다:

uv run python applications/unit_test_studio/studio_runner.py \ 
/path/to/your/project \ 
"src/utils.py:parse_config,src/core.py:run_pipeline" \ 
... 

로컬 Codex Exec 도구 예제를 실행합니다:

uv run loom run applications/codex_exec_demo/workflows/use_codex_exec_demo.yaml

Worker Agents는 호출 가능한 도구 (callable tools)로 내보낼 수 있습니다. AgentLoom은 함수 시그니처 (function signatures)를 생성하고, 필수 입력을 검증하며, 작업 페이로드 (task payload)를 구축하고, 문자열 결과를 반환합니다. 동일한 Worker는 병렬 실행을 위해 .batch(tasks)를 노출할 수도 있습니다.

Supervisor Agent (감독 에이전트)는 작업을 조정합니다. Worker Agent (작업 에이전트)는 작업의 한 부분에 특화되어 있습니다. 이를 통해 책임 소재를 명확히 하고 워크플로우 (workflow)를 디버깅하기 쉽게 만듭니다.

워크플로우 (workflow)는 에이전트가 무엇을 달성해야 하는지, 그리고 Supervisor가 Worker를 어떻게 사용해야 하는지를 기술합니다. AgentLoom은 이 워크플로우를 사용하여 런타임 작업 명세 (runtime task specification)를 구축하고, 장기 실행되는 실행 (runs)이 일관성을 유지하도록 합니다.

Skills (기술)는 재사용 가능한 지식이나 동작을 추가합니다. Hooks (훅)는 작업 생명주기 (task lifecycle), 하위 에이전트 생명주기 (sub-agent lifecycle), 도구 호출 (tool calls) 및 기타 런타임 이벤트 주변에 로직을 연결합니다. 이는 검증 (validation), 메모리 (memory), 정책 강제 (policy enforcement), 결과 변환 (result transformation) 및 시각화 수집 (visualization collection)에 사용될 수 있습니다.

AgentLoom은 제어된 오케스트레이션 (orchestration)을 위한 구조화된 도구 호출 (structured tool calling)과 더 유연한 프로그래밍 작업을 위한 코드 실행 모드 (code execution mode)를 지원합니다. 각 에이전트는 자신의 역할에 맞는 모드를 선택할 수 있습니다.

AgentLoom에는 src.tools.codex.codex_tool.codex가 포함되어 있으며, 이는 로컬의 codex exec를 일반적인 함수 도구 (function tool)로 노출합니다. 이를 Agent YAML에서 module/function으로 등록하면 되며, 별도의 system.yaml 내 Codex 섹션은 필요하지 않습니다.

prompt, cwd, sandbox, search와 같은 입력을 고정하려면 fixed_args를 사용하세요. 고정된 입력은 프레임워크에 의해 바인딩되어 LLM이 볼 수 있는 도구 스키마 (tool schema)에서 제거되며, 고정되지 않은 입력은 LLM이 제공할 수 있도록 유지됩니다. sandbox: ""는 --sandbox를 생략하고 로컬 Codex CLI 설정이 권한 (permissions)을 결정하도록 합니다. search: "true"는 --search를 전달하며, 검색은 기본적으로 꺼져 있습니다. 도구를 실행하기 전에 codex가 PATH에 있는지, 그리고 codex login status가 성공하는지 확인하십시오.

명령어	목적
uv run loom run <workflow>	AgentLoom 애플리케이션을 실행합니다.
uv run loom create <workflow>	애플리케이션을 위한 Python 엔트리 스크립트를 생성합니다.
uv run loom ui	웹 시각화 패널을 엽니다.
uv run loom dashboard	터미널 작업 대시보드를 엽니다.
uv run loom list-tasks	재개 가능한 체크포인트 작업 (resumable checkpoint tasks) 목록을 표시합니다.
uv run loom clean-tasks	오래된 체크포인트 데이터를 정리합니다.

문서	설명
구성 개요 (Configuration Overview)	구성 레이어 (Configuration layers), 병합 규칙 (merge rules), 그리고 모델 구성 격리 (model configuration isolation).
...

이 저장소에는 AI 코딩 어시스턴트를 위한 하나의 루트 레벨 Agent Skill이 포함되어 있습니다:
agentloom-framework-skill/

어시스턴트가 프레임워크의 형태를 처음부터 추측하는 대신 AgentLoom을 사용하여 개발하기를 원할 때 이를 사용하세요. 어시스턴트에게 agentloom-framework-skill/SKILL.md를 읽도록 요청한 다음, 구축하거나 확장하고자 하는 기능을 설명하세요.

이 Skill은 어시스턴트가 목표, 입력(inputs), 출력(outputs), 그리고 수락 기준(acceptance criteria)을 명확히 하고; 단일 Agent, Supervisor/Worker 워크플로우, Tool, 프라이빗 Skill, Hook, 또는 문서 변경 중 어떤 것이 가장 짧은 경로인지 결정하며; 관련 파일을 생성하거나 업데이트하고; README에 검증 결과를 기록하도록 안내합니다.

이 Skill은 코딩 어시스턴트를 위한 개발 보조 도구입니다. skills/ 아래에 저장되지 않으므로, AgentLoom 런타임 애플리케이션이 이를 일반적인 런타임 Skill로 자동 로드하지 않습니다.

AgentLoom은 복잡한 에이전트 자동화를 위한 실용적인 프레임워크로 구축되었습니다. 이슈(Issues), 기능 아이디어, 문서 개선, 그리고 예제 애플리케이션을 환영합니다.

• 이슈 생성: GitHub Issues
• 연락처: raine_walker@163.com
• 프로젝트가 도움이 되었다면, GitHub star를 눌러 다른 사람들이 더 쉽게 찾을 수 있도록 도와주세요.