휴먼레이어 '12-팩터 에이전트' 가이드, AI 에이전트 설계 12원칙 정리

휴먼레이어(HumanLayer) 창립자 덱스(Dex)가 공개한 '12-팩터 에이전트(12-factor agents)' 가이드가 깃허브 트렌딩에 올랐다. '12 Factor Apps' 원칙에서 영감을 받아 프로덕션급 AI 에이전트를 만드는 데 필요한 12가지 핵심 요소를 정리한 문서다.

덱스는 적어도 100명 이상의 SaaS 빌더(주로 기술 창업자)와 대화해본 결과, 현재 'AI 에이전트'를 표방하는 제품 대부분이 실제로는 결정적(deterministic) 코드 위에 LLM 단계가 핵심 지점마다 끼워 넣어진 형태라고 진단했다. 그는 크루(crew)·랭체인(langchains) 같은 플러그앤플레이 프레임워크부터 스몰에이전트(smolagents), 랭그래프(langraph), 그립테이프(griptape)까지 거의 모든 에이전트 프레임워크를 직접 사용해봤다고 밝혔다.

그가 정리한 일반적인 실패 경로는 이렇다. 빌더는 빠르게 움직이기 위해 프레임워크를 잡고 70~80% 품질 수준까지 도달하지만, 고객 대면 기능에는 80%로 부족하다는 사실을 깨닫는다. 80%를 넘기려면 프레임워크 내부의 프롬프트와 제어 흐름을 역설계해야 하고, 결국 처음부터 다시 작성하게 된다는 것이다.

가이드는 12가지 원칙을 제시한다. 1번 자연어를 도구 호출로 변환, 2번 프롬프트 직접 소유, 3번 컨텍스트 윈도우 직접 소유, 4번 도구를 구조화된 출력으로 다루기, 5번 실행 상태와 비즈니스 상태 통합, 6번 단순한 API로 시작·일시정지·재개 제어다.

이어 7번 도구 호출로 사람과 연결, 8번 제어 흐름 직접 소유, 9번 에러를 컨텍스트 윈도우에 압축해 담기, 10번 작고 초점이 뚜렷한 에이전트, 11번 어디서든 트리거되고 사용자가 있는 곳에서 만나기, 12번 에이전트를 상태 없는 리듀서(stateless reducer)로 만들기다.

덱스는 좋은 에이전트가 '프롬프트와 도구 한 묶음을 주고 목표 달성까지 반복'하는 패턴이 아니라 대부분이 일반 소프트웨어로 구성된다고 강조한다. LLM이 다음 단계를 JSON으로 출력하고 결정적 코드가 이를 실행해 결과를 컨텍스트에 추가하는 3단계 루프가 기본 구조이지만, 모든 단계를 LLM에 맡겨버리는 방식은 원하는 만큼 잘 작동하지 않는다는 것이 그의 진단이다.

대안으로 그는 프레임워크를 통째로 도입해 그린필드 재작성을 시도하기보다, 에이전트의 핵심 개념을 모듈 단위로 떼어내 기존 제품에 통합하는 방식을 권한다. 이 모듈식 개념은 AI 배경이 없는 숙련된 소프트웨어 엔지니어도 충분히 정의·적용할 수 있는 형태로 제시되어 있다고 그는 덧붙였다.

가이드는 깃허브 humanlayer/12-factor-agents 저장소에서 누구나 열람·기여할 수 있으며, 'create-12-factor-agent' npx·uvx CLI 부트스트랩 도구도 논의되고 있다. 덱스는 AI 엔지니어 월드 페어(AI Engineer World's Fair) 강연으로도 같은 내용을 발표했다.