6단계: AI 프로젝트 실전 및 생산 배포

LLM 기반 소프트웨어를 프로덕션 환경에서 사용할 수 있도록 구축하기 위한 12가지 핵심 원칙. AI 애플리케이션의 프로토타입에서 프로덕션으로의 전환에 따른 주요 엔지니어링 과제 해결에 중점을 둡니다.

Start Learning AI →
ProductionAILLMEngineeringAIAgentsGitHubTextFreeEnglish

12 Factor Agents - 신뢰할 수 있는 LLM 애플리케이션 구축을 위한 12가지 원칙

개요

12 Factor Agents는 Dex Horthy와 HumanLayer 팀이 개발한, 프로덕션 환경에서 사용 가능한 LLM 기반 소프트웨어를 구축하기 위한 원칙적인 방법론입니다.

배경 및 동기

왜 이 원칙들이 필요한가?

저자는 100명 이상의 SaaS 개발자(주로 기술 창업자)들과 교류한 후, 대부분의 AI 에이전트 개발이 "70-80% 품질 병목 현상"에 직면한다는 것을 발견했습니다.

  1. 초기 빠른 진행: 기존 프레임워크를 사용하여 70-80%의 기능을 빠르게 달성
  2. 품질 병목: 80%가 고객 대면 기능에는 충분히 좋지 않다는 것을 발견
  3. 프레임워크 한계: 80%를 돌파하려면 프레임워크, 프롬프트, 프로세스 등을 역설계해야 함
  4. 처음부터 다시 시작: 결국 프레임워크를 버리고 처음부터 다시 시작해야 함

핵심 통찰

  • 대부분의 성공적인 프로덕션급 "AI 에이전트"는 실제로는 그렇게 "에이전트답지" 않습니다.
  • 이들은 주로 핵심 지점에서 LLM을 교묘하게 사용하는 정교하게 설계된 소프트웨어 시스템입니다.
  • 고객이 고품질 AI 소프트웨어를 가장 빠르게 사용할 수 있도록 하는 방법은 작고 모듈화된 개념을 채택하여 기존 제품에 통합하는 것입니다.

12가지 핵심 원칙

Factor 1: 자연어를 도구 호출로

자연어를 도구 호출로 변환

LLM의 핵심 초능력은 자연어를 구조화된 데이터(JSON)로 변환하는 것입니다. 모든 에이전트 작업은 이 기본 변환에서 시작되어야 합니다.

// 핵심 패턴
const response = await llm.generateToolCall(userMessage, availableTools);
// response는 구조화된 JSON이며, 자유 텍스트가 아님

Factor 2: 프롬프트 소유하기

프롬프트 소유하기

프롬프트를 일회성 입력이 아닌, 핵심적이고 버전 관리되는 코드 자산으로 취급하십시오.

  • 애플리케이션 코드베이스에서 프롬프트 관리
  • 체계적인 테스트, 배포 및 롤백 지원
  • 일관성, 재현성 및 통제된 진화 보장

Factor 3: 컨텍스트 윈도우 소유하기

컨텍스트 윈도우 소유하기

LLM의 컨텍스트 윈도우를 능동적이고 의도적으로 관리하십시오.

  • 컨텍스트 윈도우가 현재 작업과 직접 관련된 정보만 포함하도록 보장
  • "컨텍스트 드리프트"를 방지하기 위해 불필요한 데이터 제거
  • LLM 성능 향상 및 토큰 사용량 감소

Factor 4: 도구는 그저 구조화된 출력일 뿐

도구는 구조화된 출력일 뿐

"도구"를 LLM 출력의 구조화된 JSON으로 간주하고 유효성을 검사하십시오.

// 도구 호출은 그저 JSON 스키마 유효성 검사일 뿐
const toolCall = validateToolCall(llmOutput, toolSchema);
const result = await executeValidatedTool(toolCall);

Factor 5: 실행 상태와 비즈니스 상태 통합

실행 상태와 비즈니스 상태 통합

LLM의 내부 "실행 상태"가 애플리케이션의 실제 "비즈니스 상태"와 일치하도록 보장하십시오.

  • LLM이 오래되거나 잘못된 정보에 기반하여 작동하는 것을 방지
  • 환각 또는 유효하지 않은 작업 방지
  • 실행 상태를 비즈니스 상태 옆에 영구 저장

Factor 6: 간단한 API로 시작/일시 중지/재개

간단한 API로 시작/일시 중지/재개

수명 주기 관리를 지원하는 명확한 프로그래밍 인터페이스를 가진 LLM 에이전트를 설계하십시오.

interface AgentControl {
  launch(config: AgentConfig): Promise<AgentInstance>;
  pause(instanceId: string): Promise<void>;
  resume(instanceId: string): Promise<void>;
}

Factor 7: 도구 호출로 사람과 소통

도구 호출로 사람과 소통

인간 상호작용을 일등 시민 도구 호출로 처리하십시오.

  • 고위험 단계는 사람의 검토로 라우팅
  • 사람의 피드백을 구조화된 입력으로 시스템에 반환
  • 원활한 인간-기계 협업 프로세스

Factor 8: 제어 흐름 소유하기

제어 흐름 소유하기

제어 흐름을 일반 코드 또는 자체 워크플로우 엔진 내에 유지하십시오.

  • 명시적인 OODA 루프(관찰-정향-결정-행동) 실행
  • 중첩된 프롬프트 대신 수렴 휴리스틱 사용
  • LLM이 복잡한 제어 흐름을 관리하도록 하지 마십시오.

Factor 9: 오류를 컨텍스트 윈도우로 압축

오류를 컨텍스트 윈도우로 압축

피드백 루프를 닫기 위해 오류 정보를 다음 프롬프트로 압축하십시오.

  • LLM이 오류로부터 학습하고 복구할 수 있도록 함
  • 구조화된 오류 정보 제공
  • 자가 복구 능력 지원

Factor 10: 작고 집중된 에이전트

작고 집중된 에이전트

거대한 모놀리식 챗봇 대신 작고 단일 목적의 에이전트를 구축하십시오.

// 좋은 사례: 집중된 작은 에이전트
class EmailSummaryAgent {
  async summarize(email: Email): Promise<Summary> { /* ... */ }
}

class PriorityClassificationAgent {
  async classify(email: Email): Promise<Priority> { /* ... */ }
}

Factor 11: 어디서든 트리거, 사용자가 있는 곳에서 서비스 제공

어디서든 트리거, 사용자가 있는 곳에서 서비스 제공

사용자가 이미 작업하고 있는 곳에서 에이전트를 트리거하십시오: CLI, 웹훅, 크론 등.

  • 기존 워크플로우에 통합
  • 다양한 트리거 메커니즘
  • 사용자 친화적인 접근 지점

Factor 12: 에이전트를 무상태 리듀서로 만들기

에이전트를 무상태 리듀서로 만들기

애플리케이션이 상태를 관리하고, 에이전트는 무상태를 유지합니다.

// 무상태 에이전트 패턴
class StatelessAgent {
  step(state: State): Promise<State> {
 
  }
}

기술 아키텍처 패턴

핵심 루프 단순화

각 에이전트는 본질적으로 다음으로 귀결됩니다:

const prompt = "Instructions for next step selection";
const switchFunction = (json) => routeToFunction(json);
const context = manageWhatLLMSees();
const loop = whileNotDone();

전통적인 DAG와의 차이점

  • 전통적인 DAG: 소프트웨어 엔지니어가 각 단계와 엣지 케이스를 코딩
  • 에이전트 방식: 에이전트에게 목표와 일련의 변환을 제공하고, LLM이 실시간으로 경로를 결정하도록 함
  • 실제 상황: 가장 성공적인 구현은 더 큰 결정론적 DAG 내에서 에이전트 패턴을 교묘하게 사용하는 것임

적용 시나리오

가장 적합한 시나리오

  • 자연어 이해가 필요한 구조화된 작업
  • 인간-기계 협업이 필요한 워크플로우
  • 복잡한 다단계 비즈니스 프로세스
  • 높은 신뢰성이 필요한 프로덕션 환경

적합하지 않은 시나리오

  • 간단한 결정론적 작업 (코드를 직접 작성하는 것이 더 좋음)
  • 100% 정확성이 필요한 중요 업무
  • 자원이 극도로 제한된 환경

구현 제안

점진적 채택

  1. 작게 시작: 현재 당면한 과제와 관련된 원칙 하나를 선택
  2. 구현 및 관찰: 개선 효과 확인
  3. 점진적으로 추가: 그 다음 다른 원칙 추가
  4. 지속적인 최적화: 끊임없이 개선하고 조정

기술 스택 추천

  • 언어: TypeScript (저자 추천, Python 등 다른 언어도 지원)
  • 핵심 라이브러리: BAML (스키마 정렬 파싱용)
  • 배포: 클라우드 네이티브 및 Kubernetes 지원

관련 자료

공식 자료

추가 자료

요약

12 Factor Agents는 진정으로 프로덕션 환경에서 사용 가능한 LLM 애플리케이션을 구축하기 위한 체계적인 방법을 제공합니다. 이 방법론은 더 마법 같은 프레임워크를 만드는 것이 아니라, LLM 기능에 더 나은 소프트웨어 엔지니어링 관행을 적용하는 것을 강조합니다. 핵심 개념을 기억하십시오: 에이전트는 소프트웨어이며, 소프트웨어처럼 다루면 신뢰성, 유지보수성, 그리고 경쟁자가 따라올 수 없는 능력으로 보답할 것입니다.