12-Factor Agents: AI 에이전트를 제품으로 만들 때 필요한 운영 원칙

AI Agents · Context Engineering · Production AI

AI 에이전트 시장에서 가장 위험한 착각은 "프롬프트 하나, 도구 몇 개, while 루프 하나면 제품이 된다"는 생각이다. HumanLayer의 12-Factor Agents가 흥미로운 이유는 반대 방향을 말하기 때문이다. 좋은 에이전트는 더 자율적인 괴물이 아니라, LLM 호출을 소프트웨어 아키텍처 안에 정확히 끼워 넣은 시스템에 가깝다.

12-Factor Agents cover

2026년 5월 19일 기준 이 저장소는 GitHub Trending에서 다시 강하게 노출됐고, GitHub API 기준 약 2만 개 이상의 스타를 가진 프로젝트로 확인된다. README의 질문은 단순하다. "프로덕션 고객 손에 올려도 될 만큼 좋은 LLM-powered software를 만들려면 어떤 원칙이 필요한가?" 이 질문은 지금 한국 개발자와 빌더에게도 꽤 실용적이다. 에이전트 데모는 많지만, 실제 운영 가능한 에이전트 제품은 여전히 드물기 때문이다.

이 글의 결론부터 말하면 이렇다. 12-Factor Agents는 에이전트 프레임워크라기보다, 에이전트를 소프트웨어 공학의 언어로 다시 번역하는 체크리스트다. 그래서 LangGraph냐, OpenAI Agents SDK냐, Claude냐 같은 선택보다 먼저 읽을 가치가 있다.

왜 지금 12-Factor Agents가 다시 의미 있어졌나

최근 AI 개발 흐름을 보면 모델 자체보다 모델을 감싸는 운영 계층이 더 중요해지고 있다. OpenAI Agents SDK는 tools, guardrails, handoffs, sessions, tracing, MCP 같은 구성 요소를 문서 전면에 둔다. Anthropic의 "Building effective agents"도 비슷한 방향을 말한다. 복잡한 프레임워크보다 단순하고 조합 가능한 패턴을 선호하되, workflow와 agent를 구분하고, 필요할 때만 자율성을 늘리라는 조언이다.

12-Factor Agents는 이 흐름을 더 공격적으로 정리한다. README는 "좋은 에이전트는 prompt + tools + loop until goal 패턴을 따르지 않는다"고 말한다. 오히려 좋은 에이전트는 대부분 소프트웨어이고, LLM은 그 안의 몇몇 결정 지점에 들어간다.

이 관점은 제품 개발자에게 중요하다. 데모에서는 모델이 알아서 탐색하는 모습이 멋있어 보인다. 하지만 고객 데이터, 결제, 업무 승인, 배포, 장애 대응이 붙는 순간 질문은 바뀐다.

이 에이전트의 상태는 어디에 저장되는가?
실패하면 어디서 재시작되는가?
LLM이 낸 tool call을 그대로 실행해도 되는가?
사용자가 중간에 승인하거나 수정할 수 있는가?
관측, 재현, 롤백이 가능한가?

12-Factor Agents가 랭킹할 만한 키워드는 그래서 "AI 에이전트 만들기"가 아니라 **"프로덕션 AI 에이전트 설계"**에 가깝다.

핵심 원칙 1: 컨텍스트 윈도우를 소유하라

Context window engineering

12개 원칙 중 가장 실무적인 출발점은 Factor 3, "Own your context window"다. 이 문서는 LLM을 상태 없는 함수로 본다. 입력을 주면 출력을 만드는 함수다. 그렇다면 에이전트 품질의 상당 부분은 모델 선택이 아니라 그 순간 모델에게 어떤 입력을 구성해 주는가로 결정된다.

여기서 컨텍스트는 단순히 대화 기록이 아니다.

시스템 프롬프트와 작업 지시
검색된 문서와 외부 데이터
이전 tool call과 결과
업무 상태와 사용자 상태
메모리, 관련 이벤트, 별도 대화 흐름
모델이 내야 하는 구조화 출력 스키마

많은 팀이 에이전트를 만들 때 이 레이어를 LLM 클라이언트의 기본 message 포맷에 맡긴다. 하지만 운영 제품에서는 이게 곧 병목이 된다. 왜냐하면 컨텍스트는 비용, 지연 시간, 정확도, 개인정보, 재현성, 디버깅 가능성을 모두 건드리기 때문이다.

예를 들어 고객지원 에이전트를 만든다고 하자. 단순 구현은 과거 대화 전체와 고객 정보를 모두 넣는다. 하지만 운영 가능한 구현은 다르다.

이번 턴에 필요한 고객 상태만 선별한다.
정책 문서는 관련 섹션만 넣는다.
최근 tool result는 요약하고 원본은 저장소에 둔다.
결제·환불 같은 위험 액션은 별도 승인 상태로 분리한다.
모델이 다음 행동을 구조화된 형태로 내게 한다.

즉 컨텍스트 엔지니어링은 RAG의 다른 이름이 아니다. 제품의 상태 설계, 권한 설계, 비용 설계까지 포함하는 운영 계층이다.

핵심 원칙 2: 도구 호출은 마법이 아니라 구조화 출력이다

Factor 4의 메시지는 더 직접적이다. "Tools are just structured outputs." LLM이 tool을 호출했다는 말에 너무 큰 의미를 부여하지 말라는 뜻이다. 모델은 JSON 비슷한 구조를 내고, 실제 외부 API 호출은 결정론적 코드가 수행한다.

이 분리는 에이전트 안정성의 핵심이다. 모델은 "무엇을 해야 할지" 후보를 낼 수 있지만, "어떻게 실행할지"와 "실행해도 되는지"는 애플리케이션 코드가 가져야 한다.

예를 들어 모델이 다음 출력을 냈다고 하자.

{
  "intent": "refund_order",
  "order_id": "ord_123",
  "reason": "duplicate payment"
}

나쁜 구현은 이걸 곧바로 결제 API에 넘긴다. 좋은 구현은 중간에 여러 가지를 확인한다.

이 사용자가 해당 주문의 소유자인가?
금액과 환불 정책이 맞는가?
같은 주문에 대해 이미 환불이 진행 중인가?
자동 환불 한도를 넘는가?
사람 승인 또는 고객 확인이 필요한가?

이런 검증은 LLM에게 다시 물어볼 문제가 아니다. 코드, 정책, 상태 저장소, 감사 로그의 영역이다. 12-Factor Agents가 좋은 이유는 이 경계선을 선명하게 긋는다는 점이다.

핵심 원칙 3: 실행 상태와 비즈니스 상태를 합쳐라

많은 에이전트 데모는 실행 상태를 메모리 안에 둔다. 지금 몇 번째 step인지, 어떤 tool을 불렀는지, 어떤 응답을 받았는지, 어디서 실패했는지가 프로세스 안에서만 살아 있다. 데모에서는 괜찮다. 운영에서는 위험하다.

Factor 5는 실행 상태와 비즈니스 상태를 통합하라고 말한다. 이건 에이전트를 queue, workflow engine, job runner, CRM, ticket system 같은 실제 업무 시스템과 연결할 때 특히 중요하다.

실무적으로는 아래 질문을 던져야 한다.

에이전트가 멈췄을 때 어디서 이어서 실행할 수 있는가?
사용자에게 보여줘야 하는 상태와 내부 실행 상태가 따로 놀지 않는가?
tool call 결과가 감사 가능한 형태로 남는가?
사람이 개입한 결정이 다음 LLM 컨텍스트에 올바르게 반영되는가?

이 관점에서 에이전트는 "채팅 UI 뒤의 똑똑한 함수"가 아니라, 상태 전이를 가진 제품 프로세스다. 사용자는 채팅을 보고 있을 수 있지만, 운영자는 workflow 상태를 봐야 한다.

핵심 원칙 4: 제어 흐름은 모델이 아니라 제품이 소유해야 한다

Control flow and tool safety

Factor 8, "Own your control flow"는 에이전트 설계의 가장 중요한 안전장치다. LLM에게 모든 흐름을 맡기면 구현은 빨라진다. 하지만 제품화 단계에서는 관측과 테스트가 어려워진다.

Anthropic의 에이전트 글도 유사한 구분을 한다. workflow는 predefined code path로 LLM과 tool을 오케스트레이션하는 시스템이고, agent는 모델이 자기 프로세스와 tool 사용을 더 동적으로 지시하는 시스템이다. 중요한 건 둘 중 하나가 항상 우월한 게 아니라는 점이다. 많은 제품은 순수 agent보다 workflow에 LLM step을 넣는 쪽이 더 낫다.

12-Factor Agents의 실무적 해석은 이렇다.

모델은 다음 행동 후보를 낼 수 있다.
제품은 어떤 후보가 허용되는지 결정한다.
위험한 action은 사람 승인 또는 별도 policy gate를 지난다.
실패는 raw stack trace가 아니라 압축된 오류 맥락으로 돌아간다.
긴 작업은 pause/resume 가능한 API로 쪼갠다.

이 구조를 잡으면 에이전트는 덜 화려해 보일 수 있다. 대신 운영 가능해진다. 고객에게 팔 수 있는 건 대개 이쪽이다.

작은 에이전트가 큰 에이전트보다 낫다

Factor 10은 "Small, Focused Agents"다. 이 원칙은 최근 에이전트 시장의 과잉 약속에 대한 좋은 해독제다. 범용 슈퍼 에이전트 하나가 모든 업무를 처리한다는 그림은 매력적이지만, 실제 제품에서는 책임 범위가 작고 실패 모드가 명확한 에이전트가 더 유리하다.

작은 에이전트는 다음 장점이 있다.

컨텍스트를 좁게 유지할 수 있다.
tool 권한을 최소화할 수 있다.
평가 기준이 명확하다.
장애 원인을 추적하기 쉽다.
사람이 승인해야 하는 지점을 정하기 쉽다.

한국 SaaS 팀이나 내부 자동화 팀이라면 특히 이 원칙이 중요하다. "우리 회사 업무를 전부 아는 AI 비서"보다 "세금계산서 누락을 찾아 담당자에게 확인 요청을 보내는 에이전트"가 먼저 돈이 된다. 좁은 문제일수록 사용자도 결과를 검증하기 쉽고, 운영 리스크도 낮다.

실전 적용: 에이전트 제품을 만들 때의 체크리스트

12-Factor Agents를 그대로 외우기보다, 제품 설계 체크리스트로 바꿔 쓰는 편이 좋다.

1) LLM 호출을 먼저 그리지 말고 상태 전이를 먼저 그려라

사용자가 어떤 상태에서 시작하고, 어떤 검증을 거쳐, 어떤 외부 시스템을 바꾸고, 어디서 멈추고 재시작할 수 있는지를 먼저 그려야 한다. 그 뒤에 LLM이 들어갈 지점을 고르는 편이 안전하다.

2) tool call은 권한 없는 제안으로 취급하라

모델 출력은 실행 명령이 아니라 제안이다. 실행 권한은 코드가 가진다. 특히 결제, 삭제, 배포, 이메일 발송, 개인정보 조회처럼 외부 효과가 있는 action은 반드시 policy gate를 둬야 한다.

3) 컨텍스트는 로그가 아니라 제품 입력이다

대화 기록을 많이 넣는다고 좋은 에이전트가 되지 않는다. 컨텍스트는 매 턴 재구성되는 제품 입력이다. 어떤 정보를 넣고, 어떤 정보를 빼고, 어떤 정보를 요약할지 자체가 핵심 로직이다.

4) 사람 개입을 예외가 아니라 기본 기능으로 설계하라

Factor 7은 사람에게 연락하는 것도 tool call로 보라고 말한다. 이 관점은 중요하다. 사람 승인은 실패가 아니라 정상 경로다. 특히 B2B 업무 자동화에서는 사람이 끼어드는 지점을 잘 설계한 제품이 완전 자동화를 약속하는 제품보다 더 빨리 신뢰를 얻는다.

5) 평가 기준을 "자율성"이 아니라 "운영 가능성"으로 바꿔라

좋은 에이전트의 기준은 오래 혼자 돌아다니는 능력이 아니다. 더 중요한 기준은 재현성, 관측성, 비용 예측 가능성, 승인 흐름, 실패 복구다. 이 기준을 만족하지 못하면 데모가 아무리 좋아도 제품은 불안정하다.

검색 의도 관점에서 이 주제가 좋은 이유

"AI agent framework" 키워드는 이미 포화되어 있다. 하지만 실제 빌더가 검색하는 문제는 점점 더 구체화되고 있다.

AI 에이전트 프로덕션 운영
LLM agent architecture
context engineering 실무
tool calling 안전성
human-in-the-loop agent
agent workflow vs autonomous agent

12-Factor Agents는 이 검색 의도들을 한 번에 묶는다. 특히 한국어 자료는 아직 데모 소개나 프레임워크 튜토리얼에 치우쳐 있다. 그래서 이 주제는 단순 번역보다 **"에이전트를 제품으로 만들 때 무엇을 포기하고 무엇을 가져가야 하는가"**라는 해석으로 접근할 때 가치가 있다.

짧은 결론

HumanLayer의 12-Factor Agents가 주는 메시지는 꽤 차갑다. AI 에이전트는 자율성이 높아질수록 자동으로 좋은 제품이 되지 않는다. 오히려 좋은 제품은 모델의 자율성을 필요한 곳에만 제한적으로 쓰고, 나머지는 소프트웨어 공학의 영역으로 되돌린다.

그래서 이 프로젝트를 "또 하나의 에이전트 방법론"으로 보면 아쉽다. 더 정확한 해석은 이렇다. 12-Factor Agents는 에이전트를 마법에서 운영 시스템으로 끌어내리는 문서다. 지금 에이전트를 만들고 있다면, 프레임워크를 고르기 전에 이 체크리스트부터 통과시키는 편이 낫다.