12-팩터 AI 에이전트: 효과적으로 확장 가능한 AI 시스템 구축하기

효과적인 AI 에이전트란 무엇인가?

각 요소를 살펴보기 전에, 여기서 말하는 “AI 에이전트”의 의미를 명확히 정의해봅시다. 본질적으로, 이들은 자연어 요청을 해석하고, 맥락에 따라 의사결정을 내리며, 도구나 API를 통해 특정 작업을 실행하면서도 일관성 있는 상호작용을 지속하는 시스템입니다.

가장 강력한 에이전트는 언어 모델의 추론 능력과 결정론적 코드의 신뢰성을 결합합니다. 하지만 이 균형을 잡기 위해서는 신중한 설계가 필요하며, 바로 이 요소들이 그 방법을 제시합니다.

견고한 AI 에이전트 구축을 위한 12가지 요소

1. 자연어 → 도구 호출 변환의 마스터링

자연어 요청을 구조화된 도구 호출로 변환하는 능력은 에이전트 기능의 핵심입니다. 예를 들어, “2월 AI Tinkerers 모임을 위해 Terri에게 $750 결제 링크 생성"이라는 명령을 적절한 API 호출로 바꿀 수 있습니다.

이미지 URL

{
  "function": {
    "name": "create_payment_link",
    "parameters": {
      "amount": 750,
      "customer": "cust_128934ddasf9",
      "product": "prod_8675309",
      "price": "prc_09874329fds",
      "quantity": 1,
      "memo": "Hey Jeff - see below for the payment link for the February AI Tinkerers meetup"
    }
  }
}

이 기능을 안정적으로 구현하려면, 언어 모델의 구조화된 출력을 결정론적 코드로 처리해야 합니다. 실행 전에 항상 API 페이로드를 검증하여 오류를 방지하고, LLM이 일관된 JSON 포맷을 반환하도록 해야 안정적으로 파싱할 수 있습니다.

2. 프롬프트를 완전히 소유하라

프롬프트는 애플리케이션과 언어 모델 사이의 인터페이스입니다. 즉, 코드의 일급 객체처럼 관리해야 합니다. 프롬프트를 추상화하는 프레임워크는 편리해 보일 수 있지만, 실제로는 LLM에 전달되는 지침을 모호하게 하여 세밀한 튜닝이 어렵거나 불가능하게 만듭니다.

따라서, 프롬프트를 명시적으로 작성하여 직접 통제하세요.

function DetermineNextStep(thread: string) -> DoneForNow | ListGitTags | DeployBackend | DeployFrontend | RequestMoreInformation {
  prompt #"
    {{ _.role("system") }}
    You are a helpful assistant that manages deployments for frontend and backend systems.
    ...
    {{ _.role("user") }}
    {{ thread }}
    What should the next step be?
  "#
}

이 방법의 장점은 다음과 같습니다.

• 구체적인 지침을 직접 작성해 사용 사례에 맞게 정교하게 조정 가능
• 프롬프트도 코드처럼 평가 및 테스트 가능
• LLM이 어떤 입력을 받는지 투명하게 확인 가능
• 성능 지표에 따라 신속하게 반복 개선 가능

3. 컨텍스트 윈도우를 전략적으로 설계하라

컨텍스트 윈도우는 LLM의 입력으로, 프롬프트, 대화 이력, 외부 데이터 등을 포함합니다. 이 윈도우를 최적화하면 성능과 토큰 효율성이 개선됩니다.

이미지 URL

표준 메시지 기반 포맷을 넘어서, 정보 밀도를 극대화하는 커스텀 구조를 도입하세요.

<slack_message>
    From: @alex
    Channel: #deployments
    Text: Can you deploy the backend?
</slack_message>
<list_git_tags>
    intent: "list_git_tags"
</list_git_tags>
<list_git_tags_result>
    tags:
      - name: "v1.2.3"
        commit: "abc123"
        date: "2024-03-15T10:00:00Z"
</list_git_tags_result>

이 방식의 장점은 다음과 같습니다.

• 컴팩트한 포맷으로 토큰 사용량 절감
• LLM에 전달 전 민감 데이터 필터링 용이
• LLM의 이해도를 높이는 구조 실험 가능

4. 도구를 구조화된 출력으로 구현하라

도구란 본질적으로 LLM에서 출력된 JSON이 코드 내 결정론적 동작을 트리거하는 것입니다. 즉, AI의 의사결정과 실행 로직을 명확히 분리합니다.

도구 스키마를 명확히 정의하세요.

class CreateIssue {
  intent: "create_issue";
  issue: {
    title: string;
    description: string;
    team_id: string;
    assignee_id: string;
  };
}

class SearchIssues {
  intent: "search_issues";
  query: string;
  what_youre_looking_for: string;
}

이후 LLM의 JSON 출력을 신뢰성 있게 파싱하고, 결정론적 코드로 액션을 실행한 뒤, 결과를 컨텍스트에 피드백하여 반복적인 워크플로우를 만드세요.

5. 실행 상태와 비즈니스 상태를 통합하라

많은 에이전트 프레임워크는 실행 상태(예: 현재 프로세스 단계)와 비즈니스 상태(예: 도구 호출과 결과 이력)를 분리합니다. 하지만 이 분리는 불필요한 복잡성을 초래합니다.

모든 상태를 컨텍스트 윈도우에 직접 저장하고, 이벤트의 순서에서 실행 상태를 추론하세요.

<deploy_backend>
    intent: "deploy_backend"
    tag: "v1.2.3"
    environment: "production"
</deploy_backend>
<error>
    error running deploy_backend: Failed to connect to deployment service
</error>

이 방식의 장점은 다음과 같습니다.

• 하나의 진실된 소스로 상태 관리 단순화
• 전체 이력이 한 곳에 있어 디버깅 용이
• 원하는 지점에서 스레드를 로드해 쉽게 복구 가능

AI 에이전트의 운영 배포

6. 시작, 일시정지, 재개 가능한 API 설계

운영 등급의 에이전트는 외부 시스템과 원활하게 통합되어야 하며, 장기 작업 중 일시정지 및 재개가 가능해야 합니다.

에이전트의 실행, 일시정지, 재개를 지원하는 API와, 각 작업 간 상태를 견고하게 저장하는 구조를 구현하세요. 이를 통해 다음이 가능합니다.

• 비동기 워크플로우 유연하게 지원
• 웹훅 등 외부 시스템과의 깔끔한 통합
• 중단 후에도 재시작 없이 신뢰성 있게 재개

7. 도구 호출을 통한 인간 협업 활성화

AI 에이전트는 중요한 결정이나 모호한 상황에서 인간의 입력이 필요할 수 있습니다. 구조화된 도구 호출을 활용하면 상호작용이 매끄럽게 이루어집니다.

class RequestHumanInput {  
  intent: "request_human_input";  
  question: string;  
  context: string;  
  options: {  
    urgency: "low" | "medium" | "high";  
    format: "free_text" | "yes_no" | "multiple_choice";  
    choices: string[];  
  };  
}

이미지 URL

이 방식은 상호작용 유형과 긴급도를 명확히 지정할 수 있고, 여러 사용자의 입력도 지원하며, 지속 가능한 워크플로우 API와 잘 결합됩니다.

8. 에이전트의 흐름을 직접 제어하라

사용자 정의 컨트롤 플로우를 통해, 인간 승인 대기, 결과 캐싱, 속도 제한 등 특정 요구에 맞게 에이전트의 동작을 조정할 수 있습니다.

이미지 URL

async function handleNextStep(thread: Thread) {
  while (true) {
    const nextStep = await determineNextStep(threadToPrompt(thread));
    if (nextStep.intent === 'request_clarification') {
      await sendMessageToHuman(nextStep);
      await db.saveThread(thread);
      break;
    } else if (nextStep.intent === 'fetch_open_issues') {
      const issues = await linearClient.issues();
      thread.events.push({ type: 'fetch_open_issues_result', data: issues });
      continue;
    }
  }
}

이 접근법의 장점은 다음과 같습니다.

• 중요한 작업 전, 인간 검토를 위해 일시중지(인터럽트) 가능
• 로깅, 캐시, 요약 등 맞춤형 기능 조정
• 장기 작업도 신뢰성 있게 처리 가능

9. 오류를 컨텍스트에 요약해 셀프힐링 구현

오류를 컨텍스트 윈도우에 직접 포함하면, AI 에이전트가 실패 경험에서 학습하여 스스로 방식을 조정할 수 있습니다.

try {
  const result = await handleNextStep(thread, nextStep);
  thread.events.push({ type: `${nextStep.intent}_result`, data: result });
} catch (e) {
  thread.events.push({ type: 'error', data: formatError(e) });
}

이 기능을 효과적으로 활용하려면,

• 무한 반복 방지를 위해 재시도 횟수 제한
• 반복 실패 시 인간에게 에스컬레이션
• LLM이 오류를 이해할 수 있도록 명확한 포맷 사용

아키텍처 베스트 프랙티스

10. 작고 집중된 에이전트로 설계

3~20단계 정도만 처리하는 작은 에이전트는 컨텍스트 윈도우 관리가 쉬워져 LLM 성능과 신뢰성이 높아집니다. 이 방식의 장점은 다음과 같습니다.

• 각 에이전트의 역할이 명확해짐
• 에이전트가 집중력을 잃을 위험 감소
• 특정 기능 테스트 및 검증 용이

이미지 URL

LLM이 계속 발전함에 따라, 이러한 작은 에이전트는 품질을 유지하면서 점차 범위를 확장할 수 있어 장기적으로 확장성이 보장됩니다.

11. 다양한 소스에서 트리거 지원

에이전트가 Slack, 이메일, 이벤트 시스템 등 여러 채널에서 트리거될 수 있도록 하면, 사용자가 익숙한 플랫폼에서 쉽게 접근할 수 있습니다.

여러 채널에서 에이전트를 실행하고, 동일한 채널로 응답하는 API를 구현하세요. 이를 통해 다음이 가능합니다.

• 사용자가 선호하는 플랫폼과의 통합으로 접근성 향상
• 이벤트 기반 자동화 워크플로우 지원
• 중요한 작업을 위한 인간 승인 과정 지원

12. 무상태 리듀서로 에이전트 설계

에이전트를 입력 컨텍스트를 출력 액션으로 변환하는 무상태 함수로 취급하면, 상태 관리가 단순해지고 예측 가능성과 디버깅 용이성이 높아집니다.

이미지 URL

이 개념은 에이전트를 내부 상태를 유지하지 않는 순수 함수로 바라보며, 다음과 같은 장점이 있습니다.

• 동일한 입력에 대해 예측 가능한 동작
• 컨텍스트 이력을 통한 이슈 추적 용이
• 테스트 및 검증이 간단함

미래를 위한 구축

AI 에이전트 분야는 빠르게 진화하고 있지만, 이러한 핵심 원칙은 기반 모델이 발전해도 유효합니다. 작고 집중된 에이전트로 시작해 위의 베스트 프랙티스를 따르면, 현재도 가치를 제공하고 미래 변화에도 유연히 대응할 수 있는 시스템을 만들 수 있습니다.

가장 효과적인 AI 에이전트는 언어 모델의 추론 능력과 결정론적 코드의 신뢰성을 결합한다는 점을 기억하세요. 이 12가지 요소가 그 균형을 잡는 데 도움을 줄 것입니다.

FlowHunt의 12-팩터 방법론 적용 사례

FlowHunt에서는 이 원칙들을 실제로 적용하여 고객의 워크플로우 자동화를 자동으로 생성하는 자체 AI 에이전트를 개발했습니다. 다음은 신뢰성 높은 운영 등급 시스템을 구축하기 위해 12-팩터 방법론을 어떻게 적용했는지에 대한 내용입니다.