AI 에이전트가 이메일 흐름을 검증해야 할 때, 가장 어려운 부분은 대개 모델이 아닙니다. 바로 인박스(inbox)입니다. 만약 에이전트가 공유 메일함(shared mailbox)을 폴링(polling)하고, 어떤 메시지가 중요한지 추측하며, 명확한 계약(contract) 없이 재시도한다면, 실행 과정은 매우 빠르게 이상해집니다. 저는 아주 작은 CLI 인박스 계약이 이러한 워크플로우를 훨씬 더 차분하게 만들고 디버깅을 훨씬 쉽게 만든다는 것을 발견했습니다.

인박스 계약이란 앱, 테스트 러너(test runner), 그리고 에이전트 사이의 작은 약속을 의미합니다. 즉, 인박스가 어떻게 이름 지어지는지, 어떤 메시지 마커(message marker)가 예상되는지, 폴링(polling)이 얼마나 지속되는지, 그리고 마지막에 어떤 아티팩트(artifact)가 저장되는지에 대한 약속입니다. 너무 단순하게 들릴 수도 있지만, 이는 "봇이 실패했다고 말하는 것"과 "우리가 왜 실패했는지 정확히 아는 것" 사이의 차이를 만듭니다.

이 패턴은 격리된 다이제스트 인박스 (isolated digest inboxes) 및 더 안전한 기기 로그인 이메일 (safer device sign-in emails)에 관한 포스트들과 잘 어우러집니다. 메일함 규칙이 명시되면, 에이전트는 추측을 줄이고 더 유용한 작업을 수행할 수 있습니다.

AI 에이전트에게 인박스 계약이 필요한 이유

에이전트는 단계를 따르는 데는 능숙하지만, 당신의 마음을 읽는 데는 서툽니다. 만약 당신의 프롬프트(prompt)가 "이메일이 도착했는지 확인해"라고 말한다면, 에이전트는 여전히 그 질문에 답하기 위한 결정론적인(deterministic) 방법이 필요합니다. 실제로 저는 네 가지 요소를 안정적으로 유지합니다:

1. 시나리오 ID (scenario ID)
2. 수신 인박스 이름 (recipient inbox name)
3. 예상되는 제목 파편 (expected subject fragment)
4. 최대 폴링 시간 (maximum poll window)

이것만으로도 CLI 도구가 깔끔하게 '예' 또는 '아니오'를 반환하기에 충분합니다. 또한 한 실행(run)이 다른 실행의 메시지를 가로채는 흔한 혼란을 방지합니다. 개발자들이 fake e mail com과 같은 문구로 빠른 해결책을 검색한다면, 이는 대개 팀이 워크플로우를 충분히 엄격하게 정의하지 않았다는 신호입니다.

여기에는 생산성 측면의 관점도 존재합니다. Google의 Site Reliability Workbook은 모호한 운영 업무를 줄일 것을 권장하는데, 이는 불분명한 신호가 대응 속도를 늦추고 노고 (Toil)를 증가시키기 때문입니다 (https://sre.google/workbook/eliminating-toil/). 이메일 확인이 운영 장애 (Production incidents)보다는 규모가 작긴 하지만, 동일한 원리가 적용됩니다.

내가 안정적으로 유지하는 4가지 필드

나는 계약 (Contract)을 화려하게 만들지 않으려 노력합니다. 필드를 더 많이 추가할수록 드리프트 (Drift)가 발생할 가능성도 커집니다. 매우 지루한 JSON 페이로드 (Payload)만으로도 충분히 잘 작동합니다:

{
  "scenario_id": "signup-reset-042",
  "inbox": "agent-signup-reset-042",
...

여기서부터 에이전트 (Agent)는 이메일을 트리거하는 명령 하나와 인박스 (Inbox)를 폴링 (Poll)하는 명령 하나를 호출할 수 있습니다. 만약 팀에서 실행마다 일회용 이메일 주소를 생성해야 한다면, 그 부분 또한 결정론적 (Deterministic)으로 만드세요. 임시방편으로 이름을 짓는 대신, 시나리오 ID (Scenario ID)나 실행 토큰 (Run token)으로부터 인박스 이름을 도출하세요. 마법을 줄이면, 뜻밖의 상황도 줄어듭니다.

또한 제목 (Subject) 확인 범위도 좁게 유지합니다. 전체 문자열이 아니라, 안정적인 파편 (Fragment)만 확인합니다. 마케팅 문구는 변경됩니다. 접두사 (Prefix)도 변경됩니다. 여러분이 원하는 것은, 모든 캠페인 수정이 자동화 실패로 이어지지 않으면서도 작은 편집을 견뎌낼 수 있는 신호입니다.

디버깅이 가능한 작은 CLI 패턴

내가 사용해 본 가장 좋은 설정은 두 개의 명령과 하나의 결과 파일입니다. 첫 번째 명령은 앱 경로를 트리거합니다. 두 번째 명령은 인박스를 폴링합니다. 그런 다음 래퍼 (Wrapper)가 에이전트가 검사하거나 로그에 첨부할 수 있는 하나의 아티팩트 (Artifact)를 작성합니다.

run_id="agent-$(date +%s)"

./bin/send-signup-email \
...

그게 전부입니다. 에이전트 프롬프트 (Agent prompt)에 똑똑한 분기 (Branching)를 넣을 필요도 없습니다. 무엇이 성공으로 "간주될 수 있는지"에 대한 긴 영어 설명도 필요 없습니다. 규칙은 CLI가 소유하고, 에이전트는 결과를 읽습니다. 나는 이러한 분리를 선호하는데, 이는 모델이 이메일 관련 관습 (Email folklore) 대신 오케스트레이션 (Orchestration)에 집중할 수 있게 해주기 때문입니다.

제 경험상, 가장 적절한 지점(sweet spot)은 에이전트가 다음 단계에 대해 추론(reasoning)하게 하되, 인박스 매칭 로직(inbox matching logic)에 대해서는 추론하지 않게 하는 것입니다. 만약 매칭 로직이 중요하다면, 그것은 diff를 확인하고, 테스트하고, 나머지 개발 도구들과 함께 검토할 수 있는 코드 영역에 있어야 합니다.

실행 후 아카이브해야 할 항목

저는 몇 가지 필드만 저장합니다:

• 실행 ID (run ID)
• 인박스 이름 (inbox name)
• 첫 번째 매칭된 제목 (first matched subject)
• 메시지 타임스탬프 (message timestamp)
• 첫 번째로 추출된 링크 호스트 (first extracted link host)
• 실패 원인 (failure reason, 있는 경우)

이렇게 하면 디버깅 규모를 사람이 감당할 수 있는 수준(human-sized)으로 유지할 수 있습니다. 또한 브랜치(branch)나 크론 잡(cron job) 간에 실행 결과들을 비교할 때도 도움이 됩니다. GitHub의 보고에 따르면 개발자들은 새로운 코드를 작성하는 시간보다 기존 시스템을 이해하는 데 더 많은 시간을 소비한다고 합니다. 따라서 더 작고 명확한 아티팩트(artifact)를 만드는 것은 생산성 측면에서 직접적인 이득이 됩니다 (https://github.blog/news-insights/research/research-quantifying-github-copilots-impact-on-developer-productivity-and-happiness/).

함정은 과도하게 수집하는 것입니다. 팀들은 전체 원본 HTML, 모든 헤더, 5개의 스크린샷, 그리고 전체 실행 기록(transcript)을 저장합니다. 그러고 나면 아무도 그것을 열어보지 않습니다. 작게 시작하세요. 실제 실패 사례를 통해 특정 필드가 누락되었다는 것을 깨달았을 때만 필드를 하나씩 추가하세요. 이런 습관은 지루하게 들릴 수 있지만, 워크플로우를 깔끔하게 유지하며, 솔직히 말해 더 신뢰할 수 있게 만듭니다.

Q&A

에이전트가 인박스를 동적으로 선택해야 하나요?

정해진 명명 규칙(naming rule) 내에서만 그래야 합니다. 동적인 선택은 괜찮지만, 무작위 선택은 안 됩니다. 각 실행은 나중에 재현(reproducible) 가능해야 합니다.

테스트마다 별도의 인박스가 필요한가요?

항상 그런 것은 아닙니다. 각 실행이 고유한 마커(marker)를 가지고 짧은 보관 기간(retention window)을 가진다면, 시나리오별로 구분하는 것만으로도 충분한 경우가 많습니다. 테스트별 인박스는 관리하기가 다소 번거로워질 수 있습니다.

실제적인 이점은 무엇인가요?

인박스 체크를 모호한 사이드 퀘스트(fuzzy side quest)처럼 취급하는 것을 멈추게 됩니다. 작은 계약(contract)은 AI 에이전트가 트리거(trigger), 폴링(poll), 기록(record), 결정(decide)을 수행하는 신뢰할 수 있는 운영자(operator)처럼 행동하게 해줍니다. 자동화 작업에 있어 이러한 변화는 처음 생각하는 것보다 훨씬 더 큽니다.