google-developers

ADK로 일시 중지, 재개, 그리고 컨텍스트를 절대 잃지 않는 장기 실행 AI 에이전트 구축하기

요약

ADK(Agent Development Kit)를 활용하면 기업의 복잡하고 장기적인 워크플로우를 안정적으로 처리할 수 있는 AI 에이전트를 만들 수 있어요. 이는 상태 관리, 이벤트 기반 재개, 그리고 멀티 에이전트 협업을 통해 일반적인 챗봇의 한계를 뛰어넘는답니다.

인사이트

  • 상태를 명시적으로 정의하는 '내구성 있는 메모리 스키마'를 통해 에이전트가 정확한 워크플로우 진행 상황을 파악하고, 불필요한 컨텍스트 오염 및 토큰 비용 폭증을 방지할 수 있어요.
  • 장시간 대기(idle time)를 효율적으로 처리하기 위해 '이벤트 기반 휴면 게이트'를 사용해서, 에이전트가 불필요하게 폴링하거나 스레드를 점유하지 않고 외부 이벤트가 발생할 때만 깨어나도록 설계할 수 있어요.
  • 모든 작업을 하나의 거대한 프롬프트에 담는 대신 '멀티 에이전트 위임' 아키텍처를 통해 전문화된 서브 에이전트에게 특정 작업을 맡겨, 추론 품질을 높이고 복잡한 워크플로우를 명확하게 관리할 수 있어요.

왜 중요한가

일반적인 챗봇은 컨테이너가 재시작되면 모든 컨텍스트를 잃어버리는 '무상태(stateless)' 방식이라 실제 기업 워크플로우처럼 몇 주씩 걸리는 장기적인 프로세스에는 사용할 수 없었어요. 이런 한계는 프롬프트 오염, 토큰 비용 폭증, 그리고 '환각(hallucination)' 현상으로 이어지기도 했죠. ADK를 활용하면 에이전트의 상태를 명시적으로 저장하고, 장시간 대기 중에도 리소스를 낭비하지 않으며, 필요할 때 정확히 중단된 지점부터 다시 시작할 수 있는 견고한 에이전트를 만들 수 있어서, 인사 온보딩, 청구서 분쟁 해결, 영업 파이프라인 관리 등 실제 비즈니스 문제를 해결할 수 있게 돼요.

2026년 5월 12일

Eric Dong 개발자 관계 엔지니어

대부분의 에이전트 튜토리얼은 무상태 챗봇에서 끝나곤 해요. 컨테이너가 재시작되는 순간 모든 것을 잊어버리는 대화 루프 말이에요. 하지만 실제 기업 워크플로우는 단일 API 호출로 끝나지 않는답니다.

인사 온보딩은 2주가 걸리고, 청구서 분쟁은 공급업체 답변을 기다리느라 며칠씩 지연되기도 해요. 영업 잠재 고객 발굴 시퀀스는 한 달 동안 여러 접점을 거쳐 진행되기도 하고요. 이런 프로세스들은 '휴면 시간(idle time)'이 지배적이에요. 즉, 사람이 서명하거나 배송 확인을 받거나 승인 과정을 통과해야 하는 긴 대기 시간이죠. 무상태 챗봇으로는 이런 상황을 버틸 수가 없어요.

이 튜토리얼에서는 ADK(Agent Development Kit)를 사용해서 몇 주 동안 안정적으로 실행되는 신규 직원 온보딩 코디네이터 에이전트를 구축하는 방법을 자세히 설명해 드릴 거예요. 이 에이전트는 환영 꾸러미를 보내고, 직원이 서류에 서명하는 동안 며칠 동안 대기하고, IT 프로비저닝은 전문화된 서브 에이전트에게 위임하고, 하드웨어 배송을 위해 다시 기다린 다음, 마지막으로 개인화된 첫날 일정을 보내는 일련의 과정을 컨텍스트를 단 한 바이트도 잃지 않고 수행해요.

이 과정을 통해 데모 챗봇과 프로덕션 에이전트를 구분하는 세 가지 아키텍처 변화를 배우게 될 거예요.

  • 원시 JSON을 벡터 DB에 덤핑하는 대신 내구성 있는 메모리 스키마를 사용하는 거예요.
  • 활성 폴링이나 블록된 스레드 대신 이벤트 기반 휴면 게이트를 사용하는 거고요.
  • 모놀리식 단일 에이전트 프롬프트 대신 멀티 에이전트 위임을 활용하는 거죠.

전체 소스 코드는 GitHub에서 확인하실 수 있어요.

Image 1: Diagram-1

왜 무상태 에이전트가 실제 워크플로우에서 망가지는 걸까요?

표준 무상태 패턴은 모든 사용자 메시지와 모델 응답을 늘어나는 대화 기록에 추가한 다음, 전체 덩어리를 다음 LLM 호출에 다시 전달하는 방식이에요. 이건 5분짜리 Q&A 세션에는 잘 작동하죠. 하지만 며칠 또는 몇 주에 걸쳐 진행되면 세 가지 방식으로 문제가 발생해요.

프롬프트 컨텍스트 오염 - 2주 동안 진행되는 온보딩 과정에서 수백 번의 턴이 오가다 보면, 대화 기록이 관련 없는 잡담, 오래된 도구 출력, 중복된 지시로 가득 차 버려요. 모델은 지금 어떤 단계를 진행 중인지 헷갈리기 시작한답니다.

토큰 비용 폭증 - 모든 추론 호출마다 2주 전체 대화 기록을 다시 재생하면 토큰 예산이 빠르게 소진돼요. 한 번의 온보딩 실행으로 수천 개의 턴이 생성될 수 있는데, 대부분은 현재 결정과 관련이 없죠.

휴면 시간 동안 추론 환각(hallucination) - 에이전트가 서류 서명을 기다리느라 3일 동안 멈춰 있다가, 거대한 컨텍스트 덤프와 함께 다시 시작하면 모델은 실제로 일어나지 않은 중간 단계를 자주 환각하기 시작해요. 주어지지 않은 승인을 '기억'하거나 완료되었다고 가정한 단계를 건너뛰기도 한답니다.

해결책은 더 큰 컨텍스트 윈도우가 아니에요. 근본적으로 다른 아키텍처가 필요하죠. 에이전트의 상태가 명시적이고, 내구성이 있으며, 원시 채팅 기록과 분리된 아키텍처 말이에요.

사용 사례: 신규 직원 온보딩

회사가 신규 직원을 채용할 때 어떤 일이 일어나는지 생각해 보세요.

  1. 인사팀이 환영 꾸러미와 문서 링크를 보내요.
  2. 휴면 시간 – 직원이 서류에 서명하는 동안 며칠이 지나요.
  3. IT팀이 회사 이메일과 슬랙 계정을 프로비저닝해요.
  4. 휴면 시간 – 노트북이 직원 집으로 배송되는 동안 며칠이 지나요.
  5. 인사팀이 개인화된 첫날 일정을 보내요.

Image 2: live-onboarding-overview

이건 단일 대화가 아니에요. 여러 번의 중지-재개 주기, 사람의 승인 게이트, 그리고 팀 간 핸드오프가 있는 백그라운드 프로세스죠. 같은 패턴은 청구서 분쟁 해결(공급업체 답변 대기 후 AP 라우팅 재개), 영업 잠재 고객 발굴(아웃리치 접점 사이 대기), 그리고 수십 가지 다른 운영 워크플로우에서 나타나요.

코딩 에이전트와 Agents CLI로 프로젝트 부트스트랩하기

Agents CLI는 Gemini Enterprise Agent Platform의 공식 명령줄 인터페이스예요. 이 튜토리얼의 워크플로우에서는 CLI 명령을 수동으로 실행하는 대신 코딩 에이전트를 사용해서 많은 작업을 처리할 거예요. 고수준의 의도 중심 프롬프트를 입력하면, 코딩 에이전트가 알아서 스캐폴딩을 처리해 준답니다. 먼저, CLI를 전역으로 설치해 보세요:

uv tool install google-agents-cli Shell

Copied

그런 다음 코딩 에이전트에게 이 프롬프트를 주세요:

ADK를 사용해서 HR 온보딩 에이전트를 만들어 줘. 영구 세션으로 장기 실행 백그라운드 프로세스로 동작해야 해. Shell

Copied

코딩 에이전트는 적절한 agents-cli 명령을 실행하고, 프로젝트 구조를 생성하며, 처음부터 영구 세션 및 메모리 뱅크 설정을 연결해 줄 거예요. 이 반복적인 프롬프트 기반 접근 방식은 튜토리얼 전체에 걸쳐 계속될 거예요. 필요한 것을 설명하면 코딩 에이전트가 아래 각 섹션에 표시된 코드를 생성해 줄 거예요.

Image 3: Diagram-2

내구성 있는 상태 머신에 에이전트 기반 다지기

진행 상황을 추적하기 위해 대화 기록에 의존하는 대신, 워크플로우에서 에이전트가 항상 어디에 있는지 정확히 알려주는 명시적인 상태 스키마를 정의해 보세요. 코딩 에이전트에게 이 프롬프트를 주세요:

온보딩 진행 상황을 추적할 상태 머신을 추가해 줘. START, WELCOME_SENT, DOCUMENTS_SIGNED, IT_PROVISIONED, HARDWARE_DELIVERED, COMPLETED 같은 단계가 필요해. 에이전트는 채팅 기록이 아니라 세션 상태에서 현재 단계를 읽어야 해. Shell

Copied

상태 스키마 정의하기

온보딩 흐름의 각 체크포인트에 대한 이름 있는 상수를 가진 간단한 클래스를 만드세요.

# app/state_schema.py

class OnboardingStep:
    START = "START"
    WELCOME_SENT = "WELCOME_SENT"
    DOCUMENTS_SIGNED = "DOCUMENTS_SIGNED"
    IT_PROVISIONED = "IT_PROVISIONED"
    HARDWARE_DELIVERED = "HARDWARE_DELIVERED"
    COMPLETED = "COMPLETED"

Python

Copied

여섯 가지 상태. 모호함이 없죠. 상태 머신이 순서를 강제하기 때문에 에이전트가 단계를 건너뛰거나 진행 상황을 환각할 수 없어요.

상태를 시스템 지침에 연결하기

에이전트의 시스템 프롬프트는 오래된 메시지를 다시 재생하는 대신 세션 상태 변수에서 직접 현재 위치를 읽어와요.

# app/agent.py

from google.adk.agents import Agent
from google.adk.agents.callback_context import CallbackContext
from google.adk.models import Gemini
from app.state_schema import OnboardingStep
from app.tools import (
    send_welcome_packet,
    check_hardware_delivery,
    send_day_one_schedule,
)

async def initialize_onboarding_state(callback_context: CallbackContext) -> None:
    """모든 상태 머신 키가 초기화되어 오류를 방지하도록 합니다."""
    state = callback_context.state
    if "current_step" not in state:
        state["current_step"] = OnboardingStep.START
    if "new_hire_details" not in state:
        state["new_hire_details"] = {}
    if "pending_signals" not in state:
        state["pending_signals"] = []

instruction = """당신은 HR 온보딩 코디네이터 에이전트입니다.

현재 단계: {current_step}
신규 직원 세부 정보: {new_hire_details}
대기 중인 신호: {pending_signals}

이 상태 머신 흐름을 정확히 따르세요:
1. current_step이 'START'이면: 이름, 이메일, 시작일을 물어보고 'send_welcome_packet'을 호출합니다.
2. current_step이 'WELCOME_SENT'이면: 문서 서명을 기다리는 동안 일시 중지됨을 사용자에게 알립니다. 다른 도구를 호출하지 마세요.
3. current_step이 'DOCUMENTS_SIGNED'이면: IT 프로비저닝을 'it_agent'에 위임합니다.
4. current_step이 'IT_PROVISIONED'이면: 하드웨어 추적 ID를 물어보고 'check_hardware_delivery'를 호출합니다.
5. current_step이 'HARDWARE_DELIVERED'이면: 'send_day_one_schedule'을 호출합니다.
6. current_step이 'COMPLETED'이면: 온보딩이 완료되었음을 확인합니다.

항상 도구와 현재 상태를 기반으로 판단하세요. 단계를 건너뛰지 마세요."""

Python

Copied

{current_step}, {new_hire_details}, {pending_signals}를 지침에 직접 넣으면, 에이전트가 실행될 때마다 파이썬이 이 빈칸들을 실제 데이터로 자동으로 채워줘요. 이렇게 하면 모델은 오래된 채팅 메시지를 뒤지거나 추측할 필요 없이 온보딩 워크플로우의 정확한 상태를 항상 알 수 있게 된답니다.

도구들이 상태 머신을 진행시켜요

각 도구 함수는 ADK의 ToolContext.state를 통해 체크포인트를 원자적으로 업데이트해요.

# app/tools.py

from google.adk.tools import ToolContext
from app.state_schema import OnboardingStep

def send_welcome_packet(
    name: str, email: str, start_date: str, tool_context: ToolContext
) -> dict:
    """환영 꾸러미를 보내고 WELCOME_SENT로 전환합니다."""
    state = tool_context.state
    state["new_hire_details"] = {
        "name": name, "email": email, "start_date": start_date
    }
    state["current_step"] = OnboardingStep.WELCOME_SENT
    state["pending_signals"] = ["document_signed"]

    return {
        "status": "success",
        "message": f"환영 꾸러미를 {name} ({email})에게 보냈어요. 서명 대기 중입니다.",
    }

Python

Copied

모든 도구 호출은 자동 체크포인트를 생성해요. 만약 send_welcome_packet이 실행된 직후 컨테이너가 충돌하더라도, 상태는 이미 기록되어 있어요. 에이전트가 다시 시작하면 current_step = WELCOME_SENT를 읽고 정확히 중단된 지점부터 작업을 이어나갈 수 있답니다.

영구 세션으로 체크포인트 및 재개 구현하기

상태 머신은 기본 세션 저장소가 재시작에도 살아남아야만 내구성을 가질 수 있어요. Cloud Run과 같은 컨테이너 환경에서는 컨테이너가 콜드 스타트되고, 유휴 기간 동안 0으로 스케일 다운되며, 예상치 못하게 재시작될 수 있거든요. 만약 세션이 휘발성 메모리에 저장된다면, 진행 중인 모든 온보딩 작업은 손실될 거예요. 코딩 에이전트에게 이 프롬프트를 주세요:

"세션 저장소를 영구 SQLite로 전환해서 에이전트가 서버 재시작에도 살아남도록 해 줘." Shell

Copied

메모리 내 세션을 SQLite(로컬) 또는 Cloud SQL(프로덕션)로 백업되는 ADK의 DatabaseSessionService로 바꿔주세요.

# app/fast_api_app.py

from fastapi import FastAPI
from google.adk.cli.fast_api import get_fast_api_app
from google.adk.sessions.database_session_service import DatabaseSessionService

# 영구 SQLite 세션 구성
session_service_uri = "sqlite+aiosqlite:///sessions.db"

app: FastAPI = get_fast_api_app(
    agents_dir=AGENT_DIR,
    web=True,
    session_service_uri=session_service_uri,
)

Python

Copied

이게 끝이에요. 단 한 번의 구성 변경으로 모든 ToolContext.state 쓰기 작업이 디스크에 영구적으로 저장돼요. 온보딩 도중에 서버를 종료하고 다시 시작해도, 에이전트는 모든 신규 직원 정보가 그대로 유지된 채 올바른 체크포인트에서 재개된답니다.

프로덕션 배포의 경우, SQLite URI를 Cloud SQL 연결 문자열로 교체하기만 하면 돼요. API는 동일하답니다.

이벤트 기반 재개로 휴면 시간 처리하기

휴면 시간은 장기 실행 에이전트의 가장 큰 과제예요. 환영 꾸러미를 보낸 후 에이전트는 직원이 서류에 서명하는 동안 며칠 동안 지속될 수 있는 휴면 상태에 들어가게 돼요. 활성 폴링은 컴퓨팅 리소스를 낭비하고, 블록된 스레드는 확장성이 떨어지죠. 에이전트는 정말 잠들었다가 외부 이벤트가 도착할 때만 깨어나야 해요. 코딩 에이전트에게 이 프롬프트를 주세요:

"문서 서명 및 하드웨어 배송을 위한 웹훅 엔드포인트를 추가해 줘. 웹훅이 트리거되면 에이전트가 깨어나서 세션을 불러오고 중단된 지점부터 다시 시작해야 해." Shell

Copied

웹훅 엔드포인트

외부 시스템(또는 데모 UI)이 실제 이벤트가 완료되었을 때 호출할 FastAPI 엔드포인트를 노출하세요.

# app/fast_api_app.py

from pydantic import BaseModel
from app.resume_handler import OnboardingResumeHandler

db_session_service = DatabaseSessionService(db_url=session_service_uri)
webhook_runner = Runner(app=agent_app, session_service=db_session_service)
resume_handler = OnboardingResumeHandler(runner=webhook_runner)

class WebhookPayload(BaseModel):
    user_id: str
    session_id: str

@app.post("/webhooks/document_signed")
async def trigger_document_signed_webhook(payload: WebhookPayload) -> dict[str, str]:
    """직원이 계약서에 서명하면 온보딩 에이전트를 깨웁니다."""
    await resume_handler.receive_signed_documents_callback(
        user_id=payload.user_id, session_id=payload.session_id
    )
    return {"status": "success", "message": "문서 서명이 처리되었고, 에이전트가 재개되었습니다."}

Python

Copied

재개 핸들러

OnboardingResumeHandler는 영구 세션을 불러오고, 상태 머신을 전환하며, state_delta와 함께 runner.run_async를 사용해서 에이전트를 프로그래밍 방식으로 깨워요.

# app/resume_handler.py

import json
import logging

from google.adk.runners import Runner
from google.genai import types
from app.state_schema import OnboardingStep

logger = logging.getLogger(__name__)

class OnboardingResumeHandler:
    def __init__(self, runner: Runner):
        self.runner = runner

    async def receive_signed_documents_callback(
        self, user_id: str, session_id: str
    ) -> None:
        """세션을 불러오고, DOCUMENTS_SIGNED로 전환하며, 에이전트를 재개합니다."""
        async for event in self.runner.run_async(
            user_id=user_id,
            session_id=session_id,
            new_message=types.Content(
                role="user",
                parts=[types.Part.from_text(
                    text="온보딩 재개: 계약이 서명되었습니다."
                )],
            ),
            state_delta={
                "current_step": OnboardingStep.DOCUMENTS_SIGNED,
                "pending_signals": [],
            },
        ):
            logger.info(json.dumps({
                "severity": "INFO",
                "message": f"Wake-up execution event: {event}",
                "event": "runner_event",
                "session_id": session_id,
            }))

Python

Copied

핵심 메커니즘은 state_delta예요. 웹훅이 트리거되면, 에이전트의 다음 추론 호출 전에 run_async가 상태 전환을 원자적으로 적용해요. 모델은 시스템 프롬프트에서 current_step = DOCUMENTS_SIGNED를 보고 즉시 IT 프로비저닝을 위임해야 한다는 것을 알게 돼요. 오래된 대화 기록을 다시 재생할 필요도 없고, 환각된 중간 단계도 없어요.

동일한 패턴이 하드웨어 배송 웹훅에도 적용돼요. 컨테이너는 전체 휴면 시간 동안 0으로 스케일 다운될 수 있어요. 웹훅이 도착하면 컨테이너가 스핀업되고, 세션은 SQLite에서 불러와지며, 에이전트는 중단된 추론 체인을 정확히 그 지점부터 재개한답니다.

멀티 에이전트 조정을 통한 위임

모든 도구를 단일 에이전트의 시스템 프롬프트에 몰아넣는 것은 추론 품질을 저하시켜요. 특히 프롬프트가 이미 상태 변수와 워크플로우 지침으로 가득 찬 장기 실행 컨텍스트에서는 더욱 그렇죠. ADK의 멀티 에이전트 아키텍처를 사용하면 전문화된 작업을 집중된 서브 에이전트에게 위임할 수 있어요. 코딩 에이전트에게 이 프롬프트를 주세요:

"IT 프로비저닝을 주 에이전트에 넣지 마. 회사 계정 설정을 처리하는 별도의 it_agent 서브 에이전트를 만들고, 문서 서명 후 코디네이터가 이 에이전트에게 위임하도록 해 줘." Shell

Copied

온보딩 코디네이터는 IT 프로비저닝을 전용 it_agent에게 위임해요.

# app/agent.py

from app.tools import provision_software_accounts

it_agent = Agent(
    name="it_agent",
    model=Gemini(model="gemini-3.1-flash-lite"),
    instruction="""당신은 IT 프로비저닝 에이전트입니다. 신규 직원을 위한 회사 소프트웨어 
    계정(이메일, Slack)을 프로비저닝합니다.

    현재 단계: {current_step}
    신규 직원 세부 정보: {new_hire_details}

    1. 원하는 회사 사용자 이름 접두사를 수집합니다.
    2. 'provision_software_accounts'를 호출합니다.
    3. 프로비저닝 후, 제어권을 코디네이터에게 다시 전달합니다.""",
    tools=[provision_software_accounts],
)

root_agent = Agent(
    name="hr_onboarding_coordinator",
    model=Gemini(model="gemini-3.1-flash-lite"),
    instruction=instruction,
    tools=[send_welcome_packet, check_hardware_delivery, send_day_one_schedule],
    sub_agents=[it_agent],
    before_agent_callback=initialize_onboarding_state,
)

Python

Copied

코디네이터가 DOCUMENTS_SIGNED에 도달하면 it_agent로 실행을 전달해요. 서브 에이전트는 계정 프로비저닝을 독립적으로 처리하고, 공유 상태를 IT_PROVISIONED로 업데이트한 다음, 제어권을 다시 넘겨준답니다. 각 에이전트는 집중된 프롬프트와 제한된 도구 세트를 가지고 있어서, 몇 주 동안 축적된 상태 후에도 추론을 명확하게 유지할 수 있어요.

root_agent를 생성할 때 initialize_onboarding_statebefore_agent_callback 매개변수에 전달하는 것에 주목해 주세요. 이는 사용자가 에이전트와 처음 상호 작용할 때 설정 함수를 실행하도록 애플리케이션에 지시하여, 모든 추적 변수가 준비되도록 하는 거예요. 에이전트가 깨어날 때마다 해당 변수들을 프롬프트에 동적으로 채워 넣기 때문에, 단계 사이에 며칠이 지나더라도 정확히 어떤 상황에 있는지 알 수 있죠.

골든 평가로 여러 날에 걸친 흐름 검증하기

에이전트가 단계를 건너뛰는지 확인하기 위해 2주를 기다릴 수는 없겠죠? ADK 평가 세트를 사용하면 세션 상태를 미리 시드(pre-seed)하여 휴면 시간 지연과 웹훅 트리거를 몇 초 만에 시뮬레이션할 수 있어요. 코딩 에이전트에게 이 프롬프트를 주세요:

"휴면 시간을 시뮬레이션하는 평가 테스트를 작성해 줘. 에이전트가 하드웨어 배송을 위해 48시간을 기다리고, 재개된 후에도 신규 직원의 세부 정보를 기억하는 테스트가 필요해." Shell

Copied

다음은 에이전트가 휴면 시간 일시 중지 게이트를 올바르게 적용하는지(요청해도 건너뛰기를 거부하는지) 확인하는 골든 테스트 케이스예요.

{
  "eval_id": "idle_time_pause_safety_gate",
  "conversation": [
    {
      "user_content": {"parts": [{"text": "Jane Doe의 온보딩을 시작해 줘, 이메일: jane@example.com, 시작일: 2026-06-01."}]},
      "intermediate_data": {
        "tool_uses": [{"name": "send_welcome_packet", "args": {"name": "Jane Doe", "email": "jane@example.com", "start_date": "2026-06-01"}}]
      }
    },
    {
      "user_content": {"parts": [{"text": "문서 서명을 건너뛰고 지금 바로 회사 계정을 프로비저닝할 수 있을까?"}]},
      "final_response": {"parts": [{"text": "직원이 서명할 때까지 기다리는 중입니다."}]},
      "intermediate_data": {"tool_uses": []}
    }
  ]
}

JSON

Copied

두 번째 턴은 에이전트가 어떤 도구도 호출하지 않고 WELCOME_SENT 게이트에 머무는 것을 확인해요. 두 번째 테스트 케이스는 상태를 IT_PROVISIONED로 미리 설정하고, 에이전트가 48시간의 시뮬레이션된 하드웨어 지연 후에도 올바르게 재개되어, 신규 직원의 원래 컨텍스트를 놓치지 않고 check_hardware_deliverysend_day_one_schedule을 순서대로 호출하는지 확인한답니다.

평가를 로컬에서 실행해 보세요:

.venv/bin/adk eval ./app tests/eval/evalsets/idle_time_delay_eval.json \
  --config_file_path tests/eval/eval_config.json

Shell

Copied

이 골든 테스트들은 CI/CD 파이프라인에 직접 통합되어, 프로덕션에 도달하기 전에 상태 머신 회귀를 잡아낼 수 있어요.

Agent Runtime으로 배포하기

평가가 통과되면 배포할 차례예요. 코딩 에이전트에게 이 프롬프트를 주세요:

"이걸 Agent Runtime에 배포하고 Cloud Trace를 활성화해서 프로덕션 환경에서 중지-재개 레이턴시를 모니터링할 수 있도록 해 줘." Shell

Copied

코딩 에이전트는 ADK 애플리케이션을 Agent Runtime에 연결하는 AgentEngineApp 래퍼를 스캐폴딩해 줄 거예요.

# app/agent_runtime_app.py

from vertexai.agent_engines.templates.adk import AdkApp
from app.agent import app as adk_app

class AgentEngineApp(AdkApp):
    def set_up(self) -> None:
        """로깅 및 텔레메트리로 초기화합니다."""
        vertexai.init()
        super().set_up()

agent_runtime = AgentEngineApp(app=adk_app)

Python

Copied

단일 명령으로 배포할 수 있어요:

agents-cli deploy Shell

Copied

Agent Runtime은 세션 지속성, 자동 확장(휴면 시간 동안 0으로 스케일 다운 포함), 그리고 Cloud Trace 통합을 기본으로 제공해요. SQLite를 대상으로 로컬에서 실행되는 것과 동일한 체크포인트-재개 아키텍처는 관리형 클라우드 저장소를 대상으로 프로덕션에서도 작동한답니다. 코드 변경이 필요 없어요.

Image 4: Diagram-3

다음은 무엇일까요?

무상태 에이전트는 에이전트가 될 수 있는 것의 한 부분에 불과해요. 이 튜토리얼에서 다룬 패턴들, 즉 내구성 있는 상태 머신, 영구 체크포인트 및 재개, 이벤트 기반 휴면 시간 처리, 그리고 멀티 에이전트 위임은 에이전트를 대화형 장난감에서 며칠 또는 몇 주에 걸친 워크플로우를 안정적으로 관리하는 프로덕션 백그라운드 프로세스로 변화시켜 준답니다.

시작하려면:

  • new-hire-onboarding 레포지토리를 클론하고 라이브 데모를 로컬에서 실행해 보세요.
  • 세션 관리, 멀티 에이전트 패턴, 평가 프레임워크에 대한 ADK 문서를 살펴보세요.
  • 자신만의 장기 실행 에이전트를 스캐폴딩하고, 테스트하고, 배포하려면 Agents CLI를 설치해 보세요.

온보딩 에이전트는 한 가지 예시에 불과해요. 사람의 개입이 필요한 일시 중지, 시스템 간 핸드오프, 또는 여러 날에 걸친 타임라인이 있는 모든 워크플로우는 이 아키텍처의 후보랍니다. 청구서 분쟁, 조달 승인, 영업 잠재 고객 발굴 시퀀스, 규정 준수 감사 등 패턴은 동일해요. 상태 머신을 정의하고, 체크포인트를 지속적으로 저장하고, 휴면 시간 동안 잠들었다가, 중단된 지점에서 정확히 깨어나세요.

이전

다음

google-developers · 원문 보기 · 2026-05-12

이 글은 원문을 한국어로 번역한 것입니다. 저작권은 원 저작자에게 있습니다.