단순 명세서로 그래프 기반 에이전트 워크플로를 구축하는 경량 라이브러리

실용적 조언

복잡한 에이전트 워크플로를 구축할 때 Pocketflow와 같은 기존 도구의 설계가 맞지 않는다면, TypeScript를 이용해 최소한의 제약 조건만 담은 경량 래퍼를 직접 구현해 보라.
에이전트에게 복잡한 로직을 맡기기보다 마크다운 형태의 명세서와 구체적인 '스킬' 세트를 제공하여 아키텍처를 강제하라.

섹션별 상세

작성자는 Pocketflow 프로젝트를 Kotlin으로 포팅하는 과정에서 복잡한 설계 결정을 단순화하고 타입 안정성을 확보할 필요성을 느꼈다. 이를 위해 86줄의 코드와 TSDoc만으로 구성된 초경량 TypeScript 라이브러리를 설계하여 복잡성을 제거했다. 결과적으로 핵심 로직은 최소화하고 마크다운 기반의 문서화가 프로젝트의 구조를 결정하도록 유도했다.

에이전트가 단순 명세 문서를 읽고 노드, 엣지, 워크(walk)로 구성된 그래프 워크플로를 스스로 구축하도록 4가지 핵심 스킬을 정의했다. 에이전트는 이 스킬들을 활용하여 라이브러리가 부과하는 의도적인 제약 사항 내에서 아키텍처와 디자인 패턴을 준수하며 워크플로를 생성한다. 이는 코드가 아닌 스킬 명세가 시스템의 형태를 결정하는 선언적 접근 방식을 취한다.

용어 해설

타입 안정성(Type-safe): — 프로그래밍 언어가 연산 시 데이터 타입을 엄격하게 검사하여 잘못된 타입 사용으로 인한 런타임 오류를 방지하는 특성이다. 에이전트 워크플로 설계 시 데이터 흐름의 정확성을 보장하고 개발자의 실수를 사전에 차단하는 역할을 한다.
에이전트 스킬(Agent Skills): — AI 에이전트가 특정 작업을 수행하기 위해 사용할 수 있는 도구나 기능의 집합이다. 이 아티클에서는 마크다운 기반의 명세서를 통해 에이전트가 그래프 구조의 워크플로를 스스로 구축하도록 가이드하는 논리적 도구로 활용되었다.
그래프 기반 워크플로(Workflow as a Graph): — 작업의 흐름을 노드(작업 단위)와 엣지(연결선)로 구성된 그래프 구조로 표현하는 방식이다. 복잡한 에이전트의 의사결정 경로와 반복 루프를 시각적이고 구조적으로 관리할 수 있게 해준다.

언급된 도구

Pocketflow중립

에이전트 워크플로 구축 프레임워크