ADK 장기 실행 에이전트 설계법: 상태 머신과 웹훅으로 며칠짜리 업무를 처리하는 구조

Google Developers Blog가 공개한 ADK 장기 실행 에이전트 튜토리얼은 production agent를 만드는 팀이 반드시 봐야 할 패턴을 담고 있습니다. 예시는 신입사원 온보딩입니다. 에이전트가 welcome packet을 보내고, 며칠 동안 서명을 기다리고, IT provisioning sub-agent에 위임하고, 노트북 배송을 기다린 뒤, 첫날 일정을 보냅니다. 중요한 것은 대화가 몇 분 안에 끝나지 않는다는 점입니다.

대부분의 agent 데모는 stateless chatbot입니다. 사용자가 묻고 모델이 답합니다. 하지만 실제 업무는 idle time으로 가득합니다. 승인, 서명, 입금, 배송, 벤더 회신, 내부 검토를 기다리며 며칠씩 멈춥니다. 이 구간을 처리하지 못하면 agent는 장난감에서 production system으로 넘어가지 못합니다.

문제: 긴 업무를 conversation history로 버티면 깨집니다

일반적인 챗봇 구조는 매번 이전 메시지와 모델 답변을 context에 붙여 다음 호출로 보냅니다. 짧은 Q&A에서는 괜찮습니다. 하지만 2주짜리 온보딩이나 한 달짜리 sales sequence에서는 문제가 됩니다.

첫 번째 문제는 context pollution입니다. 오래된 tool output, 잡담, 중복 instruction이 쌓여 모델이 현재 단계가 무엇인지 헷갈립니다. 두 번째는 token cost explosion입니다. 지금 필요한 것은 “서명 완료 여부” 하나인데, 매 호출마다 수백 턴을 다시 넣으면 비용이 커집니다. 세 번째는 idle time hallucination입니다. 3일 후 재개할 때 모델이 중간에 실제로 일어나지 않은 승인이나 완료를 기억한 것처럼 말할 수 있습니다.

해결은 더 큰 context window가 아닙니다. 현재 단계와 필요한 데이터를 명시적인 durable state로 저장해야 합니다.

해결 1: 상태 머신을 먼저 정의하세요

ADK 튜토리얼은 온보딩 상태를 START, WELCOME_SENT, DOCUMENTS_SIGNED, IT_PROVISIONED, HARDWARE_DELIVERED, COMPLETED로 나눕니다. 이 구조가 핵심입니다. 모델이 대화 기록에서 추측하는 것이 아니라 session state의 current_step을 읽습니다.

실무에서도 먼저 상태 머신을 그려야 합니다. 예를 들어 invoice dispute agent라면 다음처럼 나눌 수 있습니다.

• START
• INVOICE_RECEIVED
• VENDOR_CONTACTED
• VENDOR_REPLIED
• AP_REVIEW_PENDING
• APPROVED
• REJECTED
• CLOSED

상태는 적을수록 좋지만, 승인 gate와 외부 이벤트 gate는 반드시 별도 상태로 둬야 합니다. 그래야 에이전트가 “기다려야 하는 단계”에서 도구를 실행하지 않습니다.

해결 2: tool이 상태를 원자적으로 바꾸게 하세요

상태 머신은 문서로만 있으면 의미가 없습니다. tool call이 성공할 때 session state를 함께 바꿔야 합니다. ADK 예시에서는 send_welcome_packet 도구가 실행되면 current_step을 WELCOME_SENT로 바꾸고, pending_signals에 document_signed를 넣습니다. 서버가 그 직후 죽어도 상태는 이미 저장되어 재시작 후 이어갈 수 있습니다.

이 패턴은 매우 중요합니다. 모델 답변이 “환영 메일을 보냈습니다”라고 말했지만 실제 도구가 실패했거나 상태가 저장되지 않으면 운영 사고가 납니다. 따라서 production agent에서는 tool result와 state transition을 하나의 transaction처럼 다뤄야 합니다.

권장 원칙은 다음입니다.

• 모델 텍스트로 상태를 바꾸지 않습니다.
• 상태 변경은 검증된 tool 또는 webhook handler만 수행합니다.
• tool 성공 전에는 다음 단계로 이동하지 않습니다.
• 실패 시 상태를 유지하고 error event를 남깁니다.
• 상태 변경마다 actor, timestamp, reason을 기록합니다.

해결 3: idle time은 polling이 아니라 webhook으로 깨우세요

장기 실행 agent의 핵심은 “잠들 수 있어야 한다”는 것입니다. 문서 서명을 기다리는 동안 thread를 붙잡고 있거나 주기적으로 API를 polling하면 비용과 장애 포인트가 늘어납니다. ADK 튜토리얼은 FastAPI webhook endpoint를 두고, 외부 시스템이 서명 완료나 배송 완료 이벤트를 보내면 session을 hydrate한 뒤 agent를 resume합니다.

핵심 메커니즘은 state_delta입니다. webhook이 들어오면 current_step을 DOCUMENTS_SIGNED로 바꾸고, 그 상태로 다음 inference를 실행합니다. 모델은 긴 대화 기록을 뒤지지 않습니다. system instruction에 채워진 현재 상태를 보고 바로 다음 일을 합니다.

실무에서는 webhook에 idempotency key를 반드시 넣어야 합니다. 외부 시스템은 같은 이벤트를 여러 번 보낼 수 있습니다. 같은 document_signed 이벤트가 두 번 들어와도 IT provisioning이 두 번 실행되면 안 됩니다.

해결 4: sub-agent로 역할을 나누세요

긴 workflow를 하나의 agent prompt에 모두 넣으면 prompt가 비대해지고 reasoning 품질이 떨어집니다. ADK 예시는 coordinator agent가 전체 흐름을 관리하고, IT provisioning은 it_agent sub-agent에 위임합니다. 이 구조는 좋은 기본값입니다.

Coordinator는 상태 머신과 gate를 책임집니다. Sub-agent는 좁은 도구와 좁은 instruction만 가집니다. 예를 들어 onboarding에서는 IT 계정 생성, hardware tracking, HR message 작성이 서로 다른 sub-agent가 될 수 있습니다. invoice dispute에서는 vendor communication, AP policy check, payment system update를 나눌 수 있습니다.

중요한 것은 sub-agent도 공유 state를 무분별하게 수정하지 않게 하는 것입니다. 각 sub-agent가 바꿀 수 있는 state key를 제한하고, coordinator가 최종 전환을 검증하는 구조가 안전합니다.

검증: 며칠을 기다리지 말고 eval로 시뮬레이션하세요

장기 실행 agent는 사람이 실제로 며칠 기다려서 테스트할 수 없습니다. ADK 튜토리얼은 golden evaluation으로 idle time을 시뮬레이션합니다. 예를 들어 사용자가 서명 전인데 “그냥 IT 계정 만들자”고 하면 agent가 tool을 호출하지 않고 대기 상태를 유지해야 합니다. 또 48시간 배송 지연 후 resume해도 신입사원 세부 정보를 잃지 않아야 합니다.

테스트 케이스는 최소한 다음을 포함해야 합니다.

• gate를 건너뛰려는 사용자 요청
• webhook 중복 전달
• webhook 순서 뒤바뀜
• 서버 재시작 후 resume
• sub-agent 실패 후 재시도
• 상태는 바뀌었지만 외부 tool이 실패한 경우
• 오래된 session에 이벤트가 들어온 경우

이런 케이스를 CI에 넣어야 production 배포가 가능합니다. agent는 happy path보다 edge case에서 위험합니다.

운영 지표: agent 응답보다 workflow completion을 봐야 합니다

장기 실행 agent의 성공 지표는 답변 품질만이 아닙니다. 전체 workflow가 안전하게 끝났는지 봐야 합니다.

권장 지표는 다음입니다.

• workflow completion rate
• 평균 완료 시간과 idle time 비율
• 상태별 stuck count
• webhook retry count
• duplicate event 처리 수
• gate violation attempt 수
• sub-agent failure rate
• manual intervention rate
• resume latency
• state transition error rate

이 지표가 있어야 agent가 실제 업무를 줄이는지, 아니면 사람이 edge case를 수습하느라 더 바빠지는지 판단할 수 있습니다.

실행 체크리스트

• conversation history가 아니라 명시적인 상태 머신으로 workflow를 정의합니다.
• 승인, 서명, 배송, 외부 회신 같은 idle gate를 별도 상태로 둡니다.
• tool 성공과 state transition을 원자적으로 묶습니다.
• session state는 SQLite, Cloud SQL, managed session store처럼 재시작 후 살아남는 저장소에 둡니다.
• 외부 이벤트는 polling보다 webhook으로 resume합니다.
• webhook에는 idempotency key와 event timestamp를 포함합니다.
• coordinator와 sub-agent의 역할과 수정 가능한 state key를 나눕니다.
• gate skip, duplicate event, server restart, sub-agent failure를 eval로 테스트합니다.
• 완료율, stuck count, resume latency, manual intervention rate를 운영 지표로 봅니다.

ADK 튜토리얼의 핵심은 agent를 더 길게 말하게 만드는 것이 아닙니다. 며칠짜리 업무를 상태 머신, durable session, event-driven resume, sub-agent delegation으로 쪼개는 것입니다. production agent는 대화가 아니라 오래 살아남는 workflow process에 가깝게 설계해야 합니다.

참고: Google Developers Blog, “Build Long-running AI agents that pause, resume, and never lose context with ADK”, 2026-05-12.