Google Gen AI SDK를 사용하여 장기 실행 AI 에이전트(Long-Running AI Agents)를 구축하는 방법

🚀 기술 브리핑 (Technical Briefing): 이 튜토리얼은 Gate of AI의 에이전트 워크플로우 (Agentic Workflows) 심층 분석 시리즈의 일부입니다. 전체 기술 분석, 대화형 코드 샌드박스 및 네이티브 아랍어 번역을 보려면 여기에서 원문 기사를 방문하세요.

<span>튜토리얼 (Tutorial)</span>
<span>고급 (Advanced)</span>
<span>⏱ 읽기 시간 45분</span>
...

표준 채팅 API (Chat APIs)에서 벗어나십시오. 새로운 Gemini Enterprise Unified Inbox에서 영감을 받은, 장기 실행이 가능하고 상태를 유지하는 자율 에이전트 (Autonomous Agents)를 구축하기 위한 기초 아키텍처 (Architecture)를 배워보세요.

사전 요구 사항 (Prerequisites)

• Python 3.10 이상
• Google Gen AI SDK 접근 권한 (Gemini 1.5 Pro 이상)
• 결제가 활성화된 Google Cloud 프로젝트
• 비동기 Python (asyncio) 및 상태 관리 (State Management)에 대한 고급 이해

우리가 구축할 것 (What We're Building)

Gemini Enterprise에서 장기 실행 에이전트 (Long-Running Agents)를 발표함에 따라, 개발 패러다임이 공식적으로 변화했습니다. 이 튜토리얼에서는 이러한 에이전트를 구축하는 데 필요한 기초적인 "일시 중지 및 재개 (pause-and-resume)" 아키텍처를 구축할 것입니다.

우리는 단순히 챗봇을 만드는 것이 아닙니다. 다단계 작업을 실행하고, 시뮬레이션된 인간의 승인이 필요할 때 의도적으로 "일시 중지"하며 (Unified Inbox를 모방), 확인 시 재개하는 상태 유지형 비동기 Python 워커 (Stateful, Asynchronous Python Worker)를 구축할 것입니다.

설정 및 설치 (Setup and Installation)

우리는 공식 Google Gen AI SDK와 환경 변수를 위한 python-dotenv를 사용할 것입니다.

pip install google-genai python-dotenv asyncio

.env 파일에 API 자격 증명을 안전하게 보관하세요.

    # .env 파일
    GEMINI_API_KEY=your_gemini_api_key_here
...

1단계: 상태 유지형 클라이언트 설계 (Step 1: Architecting the Stateful Client)

쿼리 사이의 데이터를 잊어버리는 표준 챗봇과 달리, 장기 실행 에이전트는 엄격한 상태 딕셔너리 (State Dictionary)를 유지해야 합니다. 우리는 공식 genai.Client를 초기화하고 상태 관리자 (State Manager)를 설정합니다.

import os
import asyncio
...

2단계: "일시 중지 및 재개(Pause-and-Resume)" HITL 로직 구축

Gemini의 새로운 업데이트에서 핵심적인 혁신은 Human-in-the-Loop (HITL) 인박스(Inbox)입니다. 여기에서는 에이전트가 제한된 작업(restricted action)에 부딪혔을 때 실행을 일시 중지할 수 있도록 하는 비동기 로직을 구축합니다.

    async def request_human_approval(self, task_description):
        """Unified Inbox로 작업을 푸시하는 것을 시뮬레이션합니다"""
...

3단계: 비동기 워크플로 (Asynchronous Workflow) 실행

이제 모든 것을 하나로 연결합니다. 데이터를 처리하기 위해 client.models.generate_content 메서드를 사용하되, 이를 우리의 비동기 실행 루프(async execution loop)로 감싸서 실행할 것입니다.

    async def run_multi_day_workflow(self, initial_prompt):
        self.state["status"] = "running"
...

⚠️ 전문가 팁: 프로덕션 환경에서는 상태를 유지하기 위해 asyncio.sleep을 사용하지 마십시오. self.state 딕셔너리를 영구적인 데이터베이스(Redis 또는 PostgreSQL 등)에 직렬화(serialize)해야 합니다. 인박스(Inbox)로부터 웹훅(webhook)이 도착하면, 상태를 검색하여 에이전트를 다시 초기화해야 합니다.

통합 인박스(Unified Inbox) 아키텍처 테스트

이를 실행하기 위해, 인간이 인박스를 확인하는 상황을 시뮬레이션하는 동안 백그라운드에서 에이전트를 실행하도록 Python의 asyncio.gather를 사용하겠습니다.

async def main():
    agent = LongRunningAgent()
...

다음에 구축할 것

• 에이전트의 상태를 PostgreSQL 데이터베이스에 저장하여 시뮬레이션된 대기 루프를 교체하십시오.
• 에이전트의 재개를 위해 웹훅을 트리거하는 React/Next.js 기반의 "통합 인박스(Unified Inbox)" 프론트엔드 UI를 구축하십시오.
• 승인 후 에이전트가 실제로 작업을 실행할 수 있도록 공식 genai.types.Tool 설정을 구현하십시오.