12-Factor Agents: 신뢰할 수 있는 AI 에이전트 구축을 위한 엔지니어링 원칙

12-Factor Apps의 정신을 담아. 이 프로젝트의 소스 코드는 https://github.com/humanlayer/12-factor-agents 에 공개되어 있으며, 여러분의 피드백과 기여를 환영합니다. 함께 해결해 나갑시다!

Tip

AI Engineer World's Fair를 놓치셨나요? 여기서 강연을 확인하세요.

Context Engineering (컨텍스트 엔지니어링)을 찾고 계신가요? 바로 factor 3로 이동하세요.

npx/uvx create-12-factor-agent에 기여하고 싶다면

• 토론 스레드를 확인하세요.

안녕하세요, Dex입니다. 저는 한동안 AI 에이전트(AI agents)를 해킹해 왔습니다.

저는 시중에 나온 모든 에이전트 프레임워크(agent framework)를 시도해 보았습니다. 플러그 앤 플레이 방식인 crew/langchains부터,

• 우리가 여기에 도달한 과정: 소프트웨어의 짧은 역사
• Factor 1: 자연어에서 도구 호출 (Natural Language to Tool Calls)로
• Factor 2: 프롬프트 (Prompts)를 직접 관리하라
• Factor 3: 컨텍스트 윈도우 (Context Window)를 직접 관리하라
• Factor 4: 도구 (Tools)는 단지 구조화된 출력 (Structured Outputs)일 뿐이다
• Factor 5: 실행 상태 (Execution State)와 비즈니스 상태 (Business State)를 통합하라
• Factor 6: 단순한 API로 실행/일시 중지/재개를 수행하라
• Factor 7: 도구 호출 (Tool Calls)을 통해 인간과 접촉하라
• Factor 8: 제어 흐름 (Control Flow)을 직접 관리하라
• Factor 9: 에러를 컨텍스트 윈도우 (Context Window)에 압축하라
• Factor 10: 작고 집중된 에이전트 (Small, Focused Agents)
• Factor 11: 어디서든 트리거하고, 사용자가 있는 곳에서 만나라
• Factor 12: 에이전트를 상태가 없는 리듀서 (Stateless Reducer)로 만들어라

저의 에이전트 여정과 우리가 여기에 도달하게 된 배경에 대해 더 깊이 알고 싶다면, '소프트웨어의 짧은 역사 (A Brief History of Software)'를 확인해 보세요. 여기 요약본이 있습니다:

우리는 유향 그래프 (Directed Graphs, DGs)와 그 비순환 친구인 DAG (Directed Acyclic Graphs)에 대해 많이 이야기하게 될 것입니다. 우선... 소프트웨어는 유향 그래프라는 점을 짚고 넘어가겠습니다. 우리가 과거에 프로그램을 순서도 (Flow charts)로 표현했던 데에는 이유가 있습니다.

약 20년 전부터 DAG 오케스트레이터 (Orchestrators)가 대중화되기 시작했습니다. Airflow, Prefect와 같은 클래식한 도구들부터 그 이전의 선구자들, 그리고 Dagster, Ingest, Windmill과 같은 최신 도구들을 말합니다. 이들은 관찰 가능성 (Observability), 모듈성 (Modularity), 재시도 (Retries), 관리 기능 등의 이점을 더한 동일한 그래프 패턴을 따랐습니다.

제가 처음 말하는 것은 아니지만, 제가 에이전트에 대해 배우기 시작했을 때 얻은 가장 큰 깨달음은 DAG를 버려도 된다는 것이었습니다. 소프트웨어 엔지니어가 각 단계와 예외 케이스 (Edge case)를 코딩하는 대신, 에이전트에게 목표와 일련의 전이 (Transitions)를 제공할 수 있습니다:

그리고 LLM이 실시간으로 결정을 내려 경로를 찾도록 하는 것입니다.

여기서의 약속은 소프트웨어를 더 적게 작성한다는 것입니다. 그저 LLM에게 그래프의 '간선 (Edges)'을 제공하고 노드 (Nodes)는 스스로 찾아내게 하는 것이죠. 에러로부터 복구할 수 있고, 코드를 더 적게 작성할 수 있으며, LLM이 문제에 대한 새로운 해결책을 찾아내는 것을 발견할 수도 있습니다.

나중에 살펴보겠지만, 결과적으로 이것이 완벽하게 작동하지는 않는다는 것이 밝혀졌습니다.

한 단계 더 깊이 들어가 보겠습니다. 에이전트의 경우 다음과 같은 3단계로 구성된 루프 (Loop)를 갖게 됩니다:

• LLM이 워크플로 (Workflow)의 다음 단계를 결정하고

어쨌든, 다시 본론으로 돌아가서...

수백 개의 AI 라이브러리 (Libraries)를 파헤치고 수십 명의 창업자들과 협업하며 얻은 저의 직관은 다음과 같습니다.

• 에이전트 (Agents)를 훌륭하게 만드는 몇 가지 핵심 요소가 있습니다.

• 특정 프레임워크 (Framework)에 올인하여 본질적으로 완전히 새로운 방식 (Greenfield rewrite)으로 다시 작성하는 것은 오히려 역효효과를 낼 수 있습니다.

• 에이전트를 훌륭하게 만드는 몇 가지 핵심 원칙이 있으며, 프레임워크를 도입하면 그중 대부분 또는 전부를 얻을 수 있습니다.

• 하지만, 개발자가 고객에게 고품질의 AI 소프트웨어를 전달할 수 있는 가장 빠른 방법은 에이전트 구축에서 얻은 작고 모듈화된 (Modular) 개념들을 가져와 기존 제품에 통합하는 것입니다.

• 이러한 에이전트의 모듈화된 개념들은 AI 배경 지식이 없더라도 숙련된 대부분의 소프트웨어 엔지니어들이 정의하고 적용할 수 있습니다.

• 우리가 여기에 도달한 과정: 소프트웨어의 짧은 역사

• Factor 1: 자연어에서 도구 호출 (Tool Calls)로

• Factor 2: 프롬프트 (Prompts)를 직접 소유하라

• Factor 3: 컨텍스트 윈도우 (Context Window)를 직접 소유하라

• Factor 4: 도구 (Tools)는 단지 구조화된 출력 (Structured Outputs)일 뿐이다

• Factor 5: 실행 상태 (Execution State)와 비즈니스 상태 (Business State)를 통합하라

• Factor 6: 단순한 API로 실행/일시 중지/재개 (Launch/Pause/Resume)를 구현하라

• Factor 7: 도구 호출을 통해 사람에게 연락하라

• Factor 8: 제어 흐름 (Control Flow)을 직접 소유하라

• Factor 9: 에러 (Errors)를 컨텍스트 윈도우 (Context Window)에 압축하라

• Factor 10: 작고 집중된 에이전트 (Small, Focused Agents)

• Factor 11: 어디서든 트리거 (Trigger)하고, 사용자가 있는 곳에서 만나라

• Factor 12: 에이전트를 상태가 없는 리듀서 (Stateless Reducer)로 만들어라

• 이 가이드에 기여하기

• 2025년 3월 Tool Use 팟캐스트 에피소드에서 이 내용의 상당 부분을 다루었습니다

• The Outer Loop에서 이 내용 중 일부를 작성합니다

• @hellovai와 함께 LLM 성능 극대화 (Maximizing LLM Performance)에 관한 웨비나를 진행합니다

• got-agents/agents에서 이 방법론을 사용하여 오픈 소스 (OSS) 에이전트를 구축합니다

• 우리는 우리 자신의 모든 조언을 무시하고 Kubernetes에서 분산 에이전트 (Distributed Agents)를 실행하기 위한 프레임워크를 구축했습니다

• 이 가이드의 기타 링크:

• 12-Factor Apps

• Building Effective Agents (Anthropic)

• Prompts are Functions

• Library patterns: Why frameworks are evil

• The Wrong Abstraction

• Mailcrew Agent

• Mailcrew Demo Video

• Chainlit Demo

• TypeScript for LLMs

• Schema Aligned Parsing

• Function Calling vs Structured Outputs vs JSON Mode

• GitHub의 BAML

• OpenAI JSON vs Function Calling

• Outer Loop Agents

• Airflow

• Prefect

• Dagster

• Inngest

• Windmill

• The AI Agent Index (MIT)

• NotebookLM을 통한 모델 능력 경계 탐색 (Finding Model Capability Boundaries)

12-factor agents에 기여해주신 모든 분께 감사드립니다!

모든 콘텐츠와 이미지는 CC BY-SA 4.0 라이선스에 따라 배포됩니다.

코드는 Apache 2.0 라이선스에 따라 배포됩니다.