long-running-agents를 실제 업무에 쓰려면 에이전트가 며칠 동안 아무 일도 하지 않다가 외부 이벤트가 오면 정확한 지점에서 다시 깨어나야 한다. Google ADK(Agent Development Kit) 튜토리얼은 신규 입사자 온보딩 에이전트를 예로 들어 상태 머신, 영속 세션, 웹훅 기반 재개 패턴을 보여준다.
예제 시나리오
신규 입사자 온보딩은 단일 채팅이 아니라 여러 대기 구간을 가진 업무 프로세스다.
- HR이 환영 패킷과 서명 링크를 보낸다.
- 며칠 동안 입사자가 문서에 서명하기를 기다린다.
- IT 서브에이전트가 계정과 장비를 준비한다.
- 장비 배송 완료 이벤트를 기다린다.
- 첫날 일정 안내를 보낸다.
이런 업무에서 원본 대화 전체를 계속 프롬프트에 넣으면 비용이 커지고, 오래된 도구 결과가 컨텍스트를 오염시키며, 모델이 실제로 없던 승인이나 완료 상태를 추론할 수 있다.
핵심 구조
1. 명시적 상태 머신
대화 기록 대신 START, WELCOME_SENT, DOCUMENTS_SIGNED, IT_PROVISIONED, HARDWARE_DELIVERED, COMPLETED 같은 상태를 세션에 저장한다. 시스템 지시는 현재 상태를 읽고 허용된 다음 단계만 수행하게 만든다.
class OnboardingStep:
START = "START"
WELCOME_SENT = "WELCOME_SENT"
DOCUMENTS_SIGNED = "DOCUMENTS_SIGNED"
IT_PROVISIONED = "IT_PROVISIONED"
HARDWARE_DELIVERED = "HARDWARE_DELIVERED"
COMPLETED = "COMPLETED"2. 도구가 상태를 전진시킨다
send_welcome_packet 같은 도구는 외부 작업을 수행한 뒤 ToolContext.state를 원자적으로 갱신한다. 컨테이너가 바로 죽어도 다음 실행은 마지막 저장 상태에서 시작한다.
3. 영속 세션 저장소
로컬에서는 SQLite, 프로덕션에서는 Cloud SQL 같은 저장소를 DatabaseSessionService로 연결한다. 메모리 세션에만 의존하면 Cloud Run scale-to-zero, 재시작, 배포 때 진행 중인 업무가 사라진다.
session_service_uri = "sqlite+aiosqlite:///sessions.db"4. 웹훅으로 휴면 상태를 깨운다
서명 완료, 하드웨어 배송, 승인 같은 외부 이벤트가 웹훅으로 들어오면 resume handler가 세션을 불러오고 state_delta를 적용한 뒤 runner.run_async로 에이전트를 깨운다. 이 방식은 폴링과 블로킹 스레드를 피한다.
설계 원칙
- 상태는 모델 기억이 아니라 DB에 저장한다.
- 긴 대기 시간은 실행 중인 프로세스가 아니라 이벤트로 표현한다.
- 도구 호출은 업무 효과와 상태 전이를 함께 기록한다.
- 멀티에이전트 위임은 상태 머신의 특정 단계에 묶는다.
- 평가에서는 “정상 완료”뿐 아니라 재시작·중복 웹훅·순서가 뒤바뀐 이벤트를 테스트한다.
어디에 쓰면 좋은가
HR 온보딩, 송장 분쟁 처리, 영업 시퀀스, 보안 승인, 장비 배송, 고객 지원 에스컬레이션처럼 사람·외부 시스템·대기 시간이 섞인 업무에 적합하다. 반대로 몇 초 안에 끝나는 챗봇이나 단일 문서 요약에는 과한 구조다.
관련 문서
- long-running-agents — 장기 실행 에이전트 설계 원칙
- google-agents-cli — ADK 에이전트 스캐폴딩과 배포를 돕는 CLI
- supermemory-tutorial-ai-sdk — 세션 밖 장기 기억을 붙이는 패턴
참고 자료
- Build Long-running AI agents that pause, resume, and never lose context with ADK — Google Developers Blog (2026-05-12)