이메일 에이전트를 위한 관측성 (Observability)

이메일 에이전트가 작동하는 모습을 직접 지켜볼 수는 없지만, 어제 수행한 모든 작업은 단 한 번의 API 호출로 확인할 수 있습니다:

curl --request GET \
  --url "https://api.us.nylas.com/v3/grants/<GRANT_ID>/messages?limit=50" \
  --header "Authorization: Bearer <NYLAS_API_KEY>"

이것이 이메일 기반으로 에이전트를 구축할 때 얻을 수 있는 기묘하고도 과소평가된 속성입니다. 대부분의 자율 시스템(Autonomous systems)은 트레이싱 (Tracing), 구조화된 로그 (Structured logs), 재생 도구 (Replay tooling)와 같이 별도로 장착해야 하는 관측성 (Observability) 기능이 필요합니다. 하지만 편지함(Mailbox)에 거주하는 에이전트는 세 가지 관측성 기본 요소 (Observability primitives)를 무료로 얻게 됩니다. 매체 자체가 기록이기 때문입니다. 다음은 Agent Account mailboxes (현재 베타 버전)의 실제 동작 방식을 바탕으로 각 요소를 사용하는 방법입니다.

이벤트 스트림 (Event stream): 웹훅 (Webhooks)

모든 수신 메시지는 message.created 이벤트를 발생시키며 — 일반적으로 SMTP 핸드오프 (Handoff) 후 수 초 이내에 발생합니다 — 페이로드 (Payload)에는 에이전트가 대화 상태를 재구성하는 데 필요한 thread_id가 포함됩니다. 이는 별도의 계측 (Instrumentation) 없이도 사용할 수 있는 입력 측 이벤트 스트림입니다.

처리해야 할 한 가지 까다로운 점은, 메시지 본문이 약 1MB를 초과할 경우 트리거가 message.created.truncated로 변경되며 페이로드에서 본문이 생략된다는 것입니다. 이 경우 ID를 통해 전체 메시지를 가져와야 하며, 그렇지 않으면 에이전트가 아무런 정보 없이 추론을 수행하게 됩니다.

출력 측은 대부분의 사람들이 예상하는 것보다 더 풍부합니다. 플랫폼이 SMTP 경로를 엔드 투 엔드 (End-to-end)로 소유하고 모든 전송에 대해 보고하기 때문입니다:

트리거 (Trigger)	알려주는 내용
message.send_success	수신자 서버가 메시지를 수락함
...

이 세 가지를 이미 운영 중인 메트릭 시스템 (Metrics system)에 파이프라인으로 연결하면, 자율 송신자 (Autonomous sender)를 위한 메시지별 전달 텔레메트리 (Delivery telemetry)를 확보할 수 있습니다. send_failed 횟수가 증가하는 것은 규칙 (Rule), 할당량 (Quota), 평판 문제 (Reputation problem)와 같은 상위 단계의 무언가가 에이전트를 제한하고 있다는 가장 빠른 신호입니다.

두 가지 개선 사항이 있습니다. 워크플로가 실시간(real-time)이 아닌 배치(batch) 방식이라면, 입력 측면에서 웹훅(webhooks)이 전혀 필요하지 않습니다. received_after를 사용한 GET /messages 폴링(polling)만으로도 충분합니다. 웹훅은 실시간에 가까운(near-real-time) 에이전트 루프에서 그 가치를 발휘합니다. 그리고 아웃바운드 트리거(outbound triggers)를 단순히 권한(grant) 단위가 아니라 도메인(domain)별로 집계하십시오. 발신자 평판(sender reputation)은 특정 도메인 내의 모든 에이전트 계정(Agent Account) 간에 공유되므로, 하나의 오작동하는 에이전트가 발생시키는 반송률(bounce rate)은 형제 에이전트들의 전달 가능성(deliverability)을 조용히 저하시킵니다. 플릿 관측성(Fleet observability)은 개별 계정의 옷을 입고 있는 도메인 수준의 문제입니다.

읽을 수 있는 상태: 폴더 (folders)

에이전트 메일함에는 inbox, sent, drafts, trash, junk, archive라는 6개의 시스템 폴더가 포함되어 있으며, 이들은 여러분이 검사할 수 있는 상태 머신(state machine)의 역할도 겸합니다. junk 폴더는 스팸 필터링 및 mark_as_spam 규칙이 무엇을 분류했는지 보여줍니다. 만약 실제 고객의 메일이 그곳에 쌓이고 있다면, 폴더 하나를 목록화(listing)하는 것만으로도 확인할 수 있습니다. 사용자 정의 폴더(Custom folders)는 이 패턴을 확장합니다. 송장(invoices)이나 VIP 발신자를 지정된 폴더로 라우팅하는 규칙을 사용하면, "에이전트가 어떤 종류의 메일을 받고 있는가?"라는 질문을 폴더 개수 쿼리(folder-counts query)로 바꿀 수 있습니다.

drafts 폴더는 인간 참여형(human-in-the-loop) 설계에서 특별히 언급될 가치가 있습니다. 만약 에이전트가 답장을 초안(drafts)으로 제안하고 검토자가 이를 승인하는 구조라면, 초안 폴더가 곧 승인 대기열(approval queue)이 됩니다. 폴더의 개수가 곧 대기열의 깊이(queue depth)이며, 몇 시간 동안 그곳에 머물러 있는 초안은 폴더 목록 조회를 통해 감지할 수 있는 정체된 승인 건입니다.

거버넌스 계층(governance layer) 또한 관측 가능합니다. 수신 메일에 대해 실행되는 모든 규칙은 나중에 가져올 수 있는 규칙 평가(rule evaluation)로 로그에 기록됩니다. 따라서 "왜 에이전트가 그 메시지를 보지 못했는가?"라는 질문에 대해, 단순히 어깨를 으쓱하는 대신 쿼리 가능한 답변(예: SMTP 계층에서 block 규칙이 거부함)을 얻을 수 있습니다.

감사 로그 (audit log): 보낸 메일 (sent mail)

여기에 일반적인 에이전트 아키텍처에 진정으로 결여된 원시 요소(primitive)가 있습니다. 이 에이전트가 세상에서 취하는 모든 행동은 이메일이며, 에이전트가 보내는 모든 이메일은 수신인, 타임스탬프, 문맥(context)과 연결된 스레드 정보와 함께 sent 폴더에 보존됩니다. 감사 로그는 현실과 괴리될 수 없습니다. 왜냐하면 그것이 곧 현실이기 때문입니다.

스레딩 (Threading)은 로그를 읽기 쉽게 만듭니다. 답장은 표준 RFC 5322 헤더에 따라 그룹화되므로, 사고를 검토한다는 것은 하나의 스레드를 가져와서 들어온 것, 에이전트가 말한 것, 그리고 다시 돌아온 것 등 전체 교환 내용을 순서대로 읽는 것을 의미합니다.

또한 IMAP 접근은 API가 보는 것과 동일한 사서함을 노출하기 때문에, 엔지니어가 아닌 사람도 Outlook이나 Apple Mail에서 사서함을 열어 에이전트를 감사 (audit)할 수 있습니다. 프로토콜 트래픽과 API 트래픽 사이의 분리는 없습니다. 하나의 사서함, 하나의 기록, 그리고 이를 읽는 두 가지 방법이 존재할 뿐입니다. 귀하의 컴플라이언스 (compliance) 팀에게 LLM의 도구 호출 (tool-call) 로그에 대한 이러한 종류의 접근 권한을 주는 것을 시도해 보십시오.

화요일 오전의 사고, 단계별 추적

압박 상황에서 세 가지 기본 요소 (primitives)가 어떻게 구성되는지 보여드리겠습니다. 화요일 오전 9:40: 대시보드에는 지원 에이전트의 답장률이 밤사이 0으로 떨어졌다고 표시되지만, 인바운드 (inbound) 볼륨은 정상적으로 보입니다. 어디를 확인해야 할까요?

첫째, 이벤트 스트림 (event stream)입니다. message.created 이벤트가 여전히 도착하고 있으므로 메일은 수신되고 있습니다. 즉, 입력 (input)은 건강한 상태입니다. 하지만 message.send_failed가 오후 11시부터 상승하기 시작했습니다. 에이전트는 답장을 작성하고 있었지만 10시간 동안 전달에 실패하고 있었습니다.

둘째, 거버넌스 기록 (governance record)입니다. 수신자에게 도달하기 전에 실패한 전송은 일반적으로 아웃바운드 규칙 차단 또는 정책 제한 때문이며, 규칙 평가 (rule evaluations)는 권한 (grant)별로 로그에 기록됩니다:

curl --request GET \
  --url "https://api.us.nylas.com/v3/grants/<GRANT_ID>/rule-evaluations" \
  --header "Authorization: Bearer <NYLAS_API_KEY>"

평가 결과는 어떤 규칙이 일치했는지와 어떤 조치를 취했는지를 보여줍니다. 이 사례에서는 최근 활성화된 아웃바운드 규칙이 의도보다 더 광범위하게 일치하고 있습니다.

셋째, 사서함 그 자체입니다. 영향을 받은 스레드를 가져와서 순서대로 읽어보십시오. 무엇이 들어왔고, 에이전트가 무엇을 말하려고 시도했으며, 어디서 멈췄는지를 말입니다. 총 진단 범위는 웹훅 (webhook) 차트 하나, API 호출 하나, 폴더 읽기 하나입니다. 로그 애그리게이터 (log aggregator)도, 트레이스 샘플링 (trace sampling)도 필요 없으며, 사후 분석 (postmortem)은 서로 모순될 수 없는 아티팩트 (artifacts)로부터 스스로 작성됩니다.

사각지대 (The blind spots)

정직한 한계를 설정하여, 존재하지 않는 기능에 맞춰 설계하는 실수를 방지하십시오. 이러한 계정에서 API를 통해 전송된 메시지의 경우, 네이티브 오픈 및 클릭 트래킹(Native open and click tracking) — message.opened, message.link_clicked — 이 방출되지 않으므로, "사람이 읽었는가?"는 관측 가능한 이벤트(observable event)가 아닙니다. 즉, 전달 신호(delivery signals)가 여러분의 가시성이 끝나는 지점입니다. 또한 send_success는 수신 측 서버가 메시지를 수락했다는 것만을 의미합니다. 그 이후에 발생하는 수신 측 필터링(recipient-side filtering)은 지구상의 모든 발신자와 마찬가지로 여러분에게는 보이지 않습니다.

더 미묘한 격차도 존재합니다. 웹훅 스트림(webhook stream)은 무엇이 일어났는지는 알려주지만, 에이전트가 왜 그것을 선택했는지는 알려주지 않습니다. 메일박스 관측성(Mailbox observability)은 행동을 다룹니다. 각 전송을 만들어낸 추론 과정(프롬프트(prompts), 분류(classifications), 결정(decisions))을 기록하는 것은 여전히 여러분의 몫입니다.

먼저 아웃바운드 3요소를 연결하십시오

오늘 여러분의 이메일 에이전트 대시보드에는 무엇이 있습니까? 만약 대답이 "아직 아무것도 없다"라면, 세 가지 기본 요소(primitives) 중 무엇을 가장 먼저 연결하시겠습니까?