12-Factor Agents는 HumanLayer 팀이 정립한 LLM 기반 소프트웨어를 프로덕션 수준으로 만드는 12가지 엔지니어링 원칙이다. 유명한 “12-Factor App” 방법론에서 이름을 빌려, AI 에이전트 개발에서 반복적으로 나타나는 패턴을 체계화했다. GitHub에서 2만 개 이상의 스타를 받으며 에이전트 엔지니어링의 실용적 참고서로 자리잡았다.
배경
LLM 애플리케이션이 급증하면서 개발자들은 에이전트 프레임워크에 전면 의존하거나 처음부터 직접 짜는 두 극단 사이에서 고민한다. 이 프로젝트는 세 번째 길을 제시한다: 기존 제품에 에이전트 원칙을 모듈 단위로 적용하라.
핵심 전제:
- 에이전트를 훌륭하게 만드는 핵심 요소들이 있다
- 프레임워크 전면 도입은 역효과를 낼 수 있다
- 12가지 원칙은 AI 배경 없이도 숙련된 소프트웨어 엔지니어라면 적용할 수 있다
12가지 원칙
| # | 원칙 | 핵심 내용 |
|---|---|---|
| 1 | Natural Language to Tool Calls | 자연어 요청을 구조화된 툴 호출로 변환 |
| 2 | Own your prompts | 프롬프트를 외부 추상화에 숨기지 말고 직접 관리 |
| 3 | Own your context window | 컨텍스트 창에 무엇이 들어가는지 명시적으로 제어 |
| 4 | Tools are just structured outputs | 툴 호출은 특별한 것이 아니라 구조화된 출력일 뿐 |
| 5 | Unify execution state and business state | 실행 상태와 비즈니스 상태를 분리하지 말고 통합 |
| 6 | Launch/Pause/Resume with simple APIs | 단순한 API로 에이전트 시작·중지·재개 지원 |
| 7 | Contact humans with tool calls | 인간 개입도 일반 툴 호출과 동일한 패턴으로 처리 |
| 8 | Own your control flow | 에이전트 흐름 제어 코드를 직접 작성하고 소유 |
| 9 | Compact Errors into Context Window | 오류를 컨텍스트 창으로 압축해 모델이 복구 가능하게 |
| 10 | Small, Focused Agents | 범용 에이전트 하나보다 작고 집중된 에이전트 여럿이 낫다 |
| 11 | Trigger from anywhere | 어디서든 트리거 가능한 구조로 사용자를 직접 만나라 |
| 12 | Make your agent a stateless reducer | 에이전트를 상태 없는 리듀서(순수 함수)로 설계 |
누가, 어떤 경우에 쓰면 좋은가
- LLM 에이전트를 처음 프로덕션에 올리는 백엔드·풀스택 엔지니어
- LangChain 같은 프레임워크의 추상화에 답답함을 느끼는 개발자
- 기존 제품에 에이전트 기능을 점진적으로 추가하고 싶은 팀
- AI 배경 없이 에이전트 시스템을 설계해야 하는 소프트웨어 엔지니어
활용
코드 라이선스: Apache 2.0 / 콘텐츠 라이선스: CC BY-SA 4.0
git clone https://github.com/humanlayer/12-factor-agents.git각 원칙은 별도 마크다운 파일(content/factor-N-*.md)로 상세히 설명되며, 구체적인 코드 예제와 함께 “왜 이 원칙이 필요한가”를 논증한다.
관련 문서
- agent-harness — 에이전트 하네스 설계 방법론
- agent-governance — 에이전트 도구·비용·정책 제어 프레임워크
- mcp — 에이전트와 외부 시스템을 연결하는 표준 프로토콜