Command Queue로 에이전트 충돌 방지하기

여러 사용자가 동시에 메시지를 보내거나, 한 사용자가 짧은 간격으로 여러 번 말을 걸 때 에이전트가 어떻게 반응해야 할지 고민해 본 적 있으신가요? LLM 호출은 비용이 많이 들 뿐만 아니라, 여러 실행이 겹치면 세션 파일이나 로그가 충돌하고 API rate limit에 걸릴 위험도 있어요.

이런 레이스 컨디션 문제를 해결하기 위해 모든 인바운드 auto-reply 실행을 작고 효율적인 FIFO Queue로 직렬화하여 관리합니다. 세션별로 실행을 보호하면서도 전체적인 병렬 처리는 안전하게 유지하는 방법을 소개할게요.

필요한 것

• runEmbeddedPiAgent를 사용하는 실행 환경
• WhatsApp, Telegram, Slack, Discord 등 Gateway 응답 파이프라인이 연결된 채널
• messages.queue 설정을 수정할 수 있는 환경

빠른 시작

별도의 설정이 없어도 모든 채널은 기본적으로 collect 모드로 작동합니다. 5분 안에 설정을 커스터마이징하려면 다음 단계를 따라 하세요.

1. 글로벌 설정 적용: config.json5 파일에서 Queue 동작 방식을 정의합니다.

{
  messages: {
    queue: {
      mode: "collect",
      debounceMs: 1000,
      cap: 20,
      drop: "summarize",
      byChannel: { discord: "collect" },
    },
  },
}

2. 세션별 즉시 변경: 에이전트와의 대화창에서 직접 명령어를 입력해 모드를 바꿀 수 있습니다.
   • /queue collect 입력

Queue 모드 선택하기

메시지가 들어오는 상황에 따라 에이전트가 대기할지, 아니면 즉시 끼어들지 결정할 수 있습니다.

• collect (기본값): 대기 중인 모든 메시지를 하나의 followup turn으로 합쳐서 처리합니다.
• steer: 현재 실행 중인 turn에 메시지를 즉시 주입합니다. 스트리밍 중이 아니라면 followup으로 전환됩니다.
• followup: 현재 turn이 끝난 후 다음 turn으로 실행되도록 Queue에 추가합니다.
• steer-backlog: 현재 실행에 즉시 주입하면서, 동시에 다음 followup turn을 위해 메시지를 보존합니다.

주요 옵션

followup, collect, steer-backlog 모드에서 사용할 수 있는 세부 옵션입니다.

• debounceMs: 연속적인 메시지 입력 시 잠시 기다렸다가 실행하여 “계속해서 말하는” 상황을 방지합니다. (기본값: 1000)
• cap: 세션당 Queue에 담을 수 있는 최대 메시지 수입니다. (기본값: 20)
• drop: Queue가 가득 찼을 때 처리 방식입니다. old(오래된 것 삭제), new(새 메시지 무시), summarize(삭제된 내용을 요약하여 전달) 중 선택하세요.

문제 해결

• 명령어가 멈춘 것 같을 때: verbose 로그를 활성화하고 “queued for …ms”라는 문구가 있는지 확인하세요. Queue가 순차적으로 비워지고 있는지 알 수 있습니다.
• Queue의 깊이를 확인하고 싶을 때: verbose 로그를 켜면 Queue 타이밍 관련 데이터를 실시간으로 볼 수 있습니다.

설정 과정에서 도움이 필요하다면 AI Setup Assistant에게 물어보세요.

다음 단계

• Gateway API Reference
• Agent Configuration Deep Dive