12-Factor Agents: Patterns of reliable LLM applications - Dex Horthy, HumanLayer

영상 링크: 12-Factor Agents: Patterns of reliable LLM applications — Dex Horthy, HumanLayer
채널명: AI Engineer

12-팩터 에이전트: 신뢰할 수 있는 LLM 애플리케이션 개발 패턴 핵심 요약

• 영상은 LLM(대형 언어 모델) 기반 에이전트 개발에서 신뢰성과 품질을 높이기 위한 ‘12-팩터’ 설계 패턴을 소개함
• 발표자는 직접 에이전트 개발 경험 및 100명 이상의 개발자, 창업자, 엔지니어들 인터뷰에서 관찰된 패턴을 바탕으로 핵심 원칙을 정리
• 실무에서 대부분의 프로덕션 에이전트는 “에이전트적”이지 않으며, 추상적 프레임워크보다 소규모, 모듈러 패턴들이 실질적으로 사용됨을 강조
• Heroku의 12-Factor App처럼, “12-팩터 에이전트”의 개념을 GitHub(4,000스타, 14명 기여자) 오픈소스로 공유했으며, 큰 반향을 일으킴
• 에이전트 개발의 성공 핵심은 “프롬프트/컨텍스트/상태/흐름”을 직접 소유하고 관리하는 능력에 달려 있다고 역설
• LLM은 본질적으로 순수 함수(token in, tokens out)로, 입력 토큰 구성과 컨텍스트 구성방식이 결과의 신뢰성을 결정함
• 복잡한 툴 체인·자동화보다, 소규모·집중화된 루프(3~10단계)와 명확한 책임 분배가 실무에서 뛰어난 성능을 보임
• 에러 처리, 인간과의 인터랙션, 다양한 이벤트 트리거 및 멀티 채널(이메일, 슬랙 등) 지원의 중요성도 구체적으로 언급
• 대용량 컨텍스트 윈도우나 ‘무한대’적 에이전트 설계보다는, 구체적 경계 내 신뢰성을 확보하며 점진적 자동화 확대가 실전적이라고 설명
• 프레임워크에 대한 맹목적 의존보다, ‘엔지니어가 직접 소유하고 수정 가능한 코드 구조’가 미래의 경쟁력이 될 것임을 강조

세부 요약 - 주제별 정리

에이전트 개발 여정에서 발견한 한계와 실전적 통찰

• 발표자는 DevOps용 LLM 에이전트를 처음 만들면서 자동화의 한계에 직면
• 프롬프트를 점점 구체화했지만, 결국 bash 스크립트가 더 효율적임을 경험
• “모든 문제가 에이전트로 풀려야 하는 것은 아니다”라는 교훈 도출
• 100여명의 창업자·개발자·엔지니어와의 인터뷰에서 공통적으로 “프로덕션 에이전트는 실제론 평범한 소프트웨어에 가깝다”는 사실을 확인
• 다수의 개발자들은 대규모 프레임워크보다, 개별 모듈성 패턴을 기존 코드에 점진적으로 도입하는 방식을 택하고 있음

12-팩터 패턴 정의와 커뮤니티 반응

• Heroku의 12-Factor App처럼, “12-팩터 에이전트” 패턴을 정리해 GitHub에 공개(4,000 스타, 14명 액티브 기여자)
• Hacker News 메인 등장에서 하루 만에 20만 소셜 임프레션 유발
• 프레임워크에 대한 비판이 아니라, “실전 개발자의 위시리스트·기능 요구 목록” 성격을 부각
• 핵심은 개발자의 신뢰성 요구와 빠른 개발을 동시에 충족하는 패턴화된 원칙을 만들자는 취지
• 12개의 패턴을 전부 소개하는 대신, 강연 내에선 서로 밀접한 패턴들을 묶어서 설명

LLM이 제공하는 가장 큰 마법은 자연어→JSON 변환이다

• 가장 실용적인 활용은 “복잡한 자연어 명령을 구조적인 JSON 데이터로 변환”하는 능력
• JSON화 이후의 처리(예: 순환문, 스위치 분기, 코드 실행 등)는 기타 패턴을 통해 구현 가능
• LLM의 이 특성을 활용하면, 매우 쉽고 빠르게 기존 앱에 일부 인공지능 기능을 통합할 수 있음

툴 사용에 대한 잘못된 환상에서 벗어날 필요가 있다

• “툴 사용(tool use)은 해로울 수 있다”는 다소 도발적인 주장 제시(‘go to considered harmful’ 논문에 빗댐)
• LLM에 외부 툴 사용을 시키는 환상을 버리고, 본질적으로 “LLM이 만든 JSON → 확정적 코드 실행”의 과정을 직시해야 함
• 툴체인 활용이 고차원적인 추상화가 아니라, 실상은 데이터를 변환하여 코드에 넘기는 과정임을 구체적 예시로 설명

제어 흐름을 스스로 소유하는 것이 신뢰성과 확장성에 필수적이다

• 소프트웨어 개발에서 DAG(Directed Acyclic Graph) 개념과 제어 흐름 분기의 역사를 소개
• 단순 반복 루프에 LLM 상태를 넣어 작업시키는 구조(이벤트→프롬프트→API콜→결과→컨텍스트)는 긴 워크플로우에서 한계를 드러냄
• 지나치게 긴 컨텍스트 윈도우(수십만, 수백만 토큰 등)는 실제 신뢰성과 정확도를 저해함(2백만 토큰 대입 예시)
• 효과적인 에이전트 구조는 “프롬프트-스위치문-컨텍스트 빌더-반복루프”의 각 요소를 명시적으로 소유하며, 유연하게 흐름을 제어할 수 있어야 함

REST API 및 상태 기반 설계를 도입해야 장기 실행·중단·재개가 가능하다

• Agent를 REST API 혹은 MCP 서버 등 표준화된 인터페이스 뒤에 두어야 함
• 장기 실행 중인 워크플로우는 상태ID로 컨텍스트를 데이터베이스에 직렬화/복원할 수 있어야 중단, 재개 등 유연한 관리가 가능
• “에이전트도 결국 소프트웨어”라는 점을 상기하고, 시스템적 상태/비즈니스 상태를 직접 관리해야 함
• 이 구조를 통해 외부 장기 툴 호출·승인 대기·데이터 처리 등 현대적 API 시스템에서 요구되는 모든 플로우가 성립됨

프롬프트와 컨텍스트는 개발자가 끝까지 소유·최적화해야 한다

• 초반에는 템플릿화된 프롬프트로도 꽤 높은 수준의 결과물을 얻을 수 있으나, 품질 상향을 원한다면 모든 토큰을 직접 제어해야 함
• LLM의 신뢰성은 “들어가는 토큰 품질(= 프롬프트와 컨텍스트 구성 방법)”에 결정적으로 의존
• 이벤트 처리 기록(history), 사용자 스레드 모델링, 컨텍스트 구성 방식 모두 개발자가 마음대로 설계할 수 있어야 함
• “프롬프트 엔지니어링”이 아니라 “컨텍스트 엔지니어링”이 에이전트 품질의 본질임을 강조

오류 처리와 에러 컨텍스트 관리는 신중하게 설계해야 한다

• 모델이 잘못된 API 호출 또는 장애 상황 발생 시, 그 에러 메시지를 컨텍스트에 적절히 기록하는 것이 중요
• 무분별하게 에러/스택트레이스를 집어넣는 대신, 요약·정제해서 핵심 정보만 컨텍스트에 반영해야 LLM이 혼동되지 않음
• 올바른 툴 호출 성공 시에는 대기 중인 에러정보 등을 정리(=클리어)하여 컨텍스트를 청결하게 유지해야 함

인간과의 상호작용 설계를 자연스럽고 유연하게 통합해야 한다

• 툴 호출과 인간 메시지 전송간의 명확한 Intent 설계를 통해, LLM이 ‘다음 행동’을 자연어 토큰으로 결정하게 해야 함
• 예: 모델이 “완료됨”, “추가 설명 필요”, “담당자와 대화 필요” 같은 인간 친화적 토큰부터 생성하게 유도
• 이를 통해 자연스러운 out-loop 에이전트와 인간 협업을 손쉽게 구현 가능
• 이메일, 슬랙, 디스코드, SMS 등 다양한 채널에서 에이전트가 사용자와 직접 인터랙션할 수 있도록 설계해야 함

소규모 집중화된 마이크로 에이전트 구조가 실전에서 탁월하다

• 실무에서는 100가지 툴, 20단계 이상의 거대한 에이전트 루프보다, “3~10단계의 잘 정의된 마이크로 에이전트” 조합이 신뢰성과 유지관리 측면에서 뛰어남
• 예시: HumanLayer 내부 ‘배포 봇’ — 대부분의 파이프라인은 확정적 CI/CD 코드, Github PR 병합 후 LLM이 “다음 단계 JSON”을 결정, 필요시 인간이 보정 피드백 제공
• 백엔드와 프론트엔드 분기 수행, 승인·롤백 등도 마찬가지 구조 내에서 처리
• 앞으로 LLM이 더 진화해도, 결정적 코드(비-LM)와 LLM 에이전트의 협력 구조는 당분간 실전 최선
• 핵심은 “모델이 신뢰할 수 있는 경계선 내에서 할 수 있는 것”을 점진적으로 확장하는 것임

에이전트는 기본적으로 무상태(stateless)로 설계되어야 한다

• 상태는 외부에 저장·복원·관리하고, 에이전트 함수는 입력(토큰·컨텍스트)에 따라 언제든 재실행될 수 있어야 함
• 다양한 상태관리 방식, 추상화 수준에 대해 현재 커뮤니티 내 활발한 논의가 있음
• 프레임워크/라이브러리 논쟁도 있지만, ‘엔지니어가 직접 책임지고 소유할 수 있는 구조(예: scaffold 방식, shadcn 패턴)’가 장기적으로 유리함

신뢰성, 제어권, 사람과의 협업이 에이전트 경쟁력의 본질이다

• LLM 에이전트 개발은 소프트웨어 엔지니어링의 연장선이다 — 반복문, 분기문 등을 모두 직접 구현할 수 있어야 함
• LM은 순수 함수이므로, “올바른 컨텍스트·토큰”만 잘 넣으면 항상 신뢰성 향상
• “제어 흐름, 상태 소유, 컨텍스트 엔지니어링”을 통해 엔지니어링적 유연성과 차별화를 달성해야 함
• 협업 및 인간과의 인터랙션 설계가 미래형 에이전트의 성패를 좌우
• 어렵지만 중요한 부분(프롬프트, 흐름, 토큰 등)에 집중하는 것이 진정한 실력
• 프레임워크는 하드파츠(인프라 등)를 대행해주고, 엔지니어가 LLM의 고난이도 영역(프롬프트, 맥락 등)에 집중할 수 있게끔 진화해야 함
• 발표자의 HumanLayer 프로젝트 및 ‘A2 프로토콜’(에이전트-인간 연결 방식 표준)의 필요성 언급으로 마무리