12-Factor Agents로 실행 상태와 제어 흐름 설계하기

문의 답변 에이전트에서는 초안 작성, 승인 대기, 실제 전송을 서로 다른 상태로 관리해야 합니다. 세 상태를 같은 성공 기록으로 남기면 운영자는 전송 여부와 다음 행동을 확인할 수 없습니다. 대기 중 프로세스가 종료되는 경우를 포함해 상태를 저장하고 재개하는 방법도 정해야 합니다.

대규모 언어 모델(LLM)에 목표와 도구를 주고 반복하게 하면 개발자는 에이전트의 기본 형태를 만들 수 있습니다. HumanLayer의 12-Factor Agents는 프롬프트, 입력, 상태, 실행 흐름을 개발자가 이해하고 조정할 수 있어야 한다고 제안합니다. 문의 처리 예시로 모델이 판단할 부분과 실행 코드가 통제할 부분을 구분하겠습니다.

모델의 요청을 실행하는 코드

도구 호출은 모델이 선택한 구조화된 요청입니다. 애플리케이션은 입력, 권한, 현재 상태를 검사한 뒤 실행 여부를 정합니다.

예를 들어 고객 문의를 읽고 답변 초안을 만드는 시스템을 생각해보겠습니다. 모델은 문의 분류나 초안을 만들 수 있습니다. 실제 전송은 수신자, 내용, 승인 상태를 확인한 코드가 처리하도록 나눌 수 있습니다. 초안 생성과 전송을 같은 성공 상태로 취급하면 무엇이 끝났는지 알기 어렵습니다.

개발자는 프롬프트도 코드와 함께 관리합니다. 어떤 지시와 자료를 모델에 보냈는지 확인할 수 있어야 잘못된 출력의 원인을 비교할 수 있습니다. 프레임워크를 고를 때도 최종 입력을 읽고 수정할 수 있는지 확인합니다.

직접 작성한 문의 답변 흐름입니다. 그림에는 초안 작성과 실제 전송을 구분하고, 승인 대기 중 저장해야 할 질문·초안·현재 상태를 표시했습니다.

실행 기록과 다음 판단의 입력

실행 이력을 전부 보존하는 것과 매번 모델에 전부 보내는 것은 다른 일입니다. 감사와 디버깅에는 자세한 기록이 필요할 수 있지만, 다음 판단에는 현재 목표와 유효한 상태, 관련 도구 결과만 필요할 수 있습니다.

현재 목표: 문의 답변 초안 작성
확인된 상태: 주문은 배송 완료, 환불 요청은 미접수
다음 판단에 필요한 정보: 문의 내용과 환불 기준
아직 허용되지 않은 행동: 고객에게 답변 전송

문의 처리의 입력 예시입니다. 애플리케이션은 전체 실행 이력을 별도로 보존하고, 모델에는 현재 판단에 필요한 내용을 보냅니다. 개발자는 입력을 구성하는 단계에서 비밀이나 불필요한 고객 정보를 제외하거나 가릴 수도 있습니다.

승인 대기에서 저장할 상태

사람의 승인을 기다리는 동안 프로세스가 종료되어도 작업을 이어갈 수 있어야 합니다. 상태를 프로세스 메모리에만 두면 종료 후 재개 위치를 알 수 없습니다. 승인할 초안과 수신자, 대기 중인 질문, 이미 실행한 행동을 데이터베이스처럼 프로세스 종료 후에도 유지되는 저장소에 남깁니다. 재개할 때는 승인 응답이 저장된 초안과 대상에 대한 것인지 확인합니다.

특히 외부 효과가 있는 행동은 실행 여부를 확인해야 합니다. 메일을 보낸 뒤 결과 저장에 실패한 상황에서 전체 작업을 재실행하면 중복 전송이 생길 수 있습니다. 모델이 “보냈다”고 말한 기록보다 실제 실행 결과와 식별자가 필요합니다.

6번째 원칙은 호출하는 쪽에서 시작·일시 정지·재개를 다룰 수 있는 단순한 API를 제안합니다. 애플리케이션은 다음 모델 호출을 시작할 때 확정된 상태와 대기 중인 상태를 구분해 전달할 수 있어야 합니다.

오류 뒤의 판단과 재시도

도구 오류를 숨기면 모델은 성공한 것으로 판단할 수 있습니다. 반대로 긴 오류와 실패 호출을 계속 넣으면 현재 문제를 찾기 어렵습니다. 실패 원인과 바꿔야 할 조건을 짧게 제공하고, 재시도 횟수와 중단 기준은 실행 코드에서 관리할 수 있습니다.

한 에이전트의 책임도 좁게 정합니다. 문의 분류, 주문 조회, 답변 작성, 전송 승인 전체를 하나의 무제한 루프로 맡기기보다 각 단계의 입력과 결과를 정하면 실패 위치를 검사하기 쉽습니다. 반드시 에이전트를 여러 개 만들어야 한다는 뜻은 아닙니다. 먼저 한 작업의 범위부터 줄일 수 있습니다.

상태 설계를 검증할 때는 승인 대기 중 프로세스를 종료하고 저장된 상태로 재개하는 상황을 포함합니다. 초안과 수신자가 유지되는지, 승인 전에는 전송되지 않는지, 이미 완료한 전송이 중복 실행되지 않는지 확인합니다. 운영자는 실행 기록에서 현재 상태와 다음 행동을 구분할 수 있어야 합니다.