에이전트 개발 키트 (ADK) 에이전트를 Cloud Storage에 연결하여 에이전트 워크로드에 저장된 데이터와 기본 제공 ADK 도구 모음에 대한 액세스 권한을 부여할 수 있습니다. 이 통합을 통해 장기 실행 태스크의 상태, 메모리, 체크포인트를 유지하고 멀티 에이전트 워크플로 전반에서 중간 파일을 공유할 수 있습니다.
설정 안내와 코드 예시는 ADK 통합 가이드를 참고하세요.
ADK와 Cloud Storage 통합의 이점
Cloud Storage를 에이전트와 통합하면 에이전트가 대용량 파일을 처리하고, 대화 기록을 유지하고, 기존 스토리지 인프라를 재사용할 수 있습니다.
- 동적 컨텍스트 확장: LLM이 한 번에 읽을 수 있는 양에 제한을 받지 않고 에이전트가 대규모 데이터 세트, 설명서 또는 미디어 파일에 액세스할 수 있습니다.
- 지속적인 아티팩트 유지: 임시 파일, 로그 또는 생성된 항목 (예: 보고서 또는 이미지)을 대화 기록 외부에 안정적으로 저장합니다.
- 모든 아티팩트 유형 지원: Cloud Storage를 공유 저장소로 사용하여 텍스트, 이미지, 오디오, 동영상 등 다양한 형식을 처리하고 생성합니다.
- 세분화된 액세스 제어: IAM 역할을 사용하여 Cloud Storage에 대한 에이전트 액세스를 정확하게 제어합니다. ADK는 표준 Google Cloud 인증을 사용하여 에이전트가 데이터에 액세스하거나 작업을 수행하는 데 필요한 최소한의 권한만 갖도록 합니다.
사용 사례
에이전트에 Cloud Storage 기능을 제공하면 다음과 같은 사용 사례를 처리할 수 있습니다.
- 검색 증강 생성 (RAG)이라고도 하는 동적 컨텍스트 검색
- 아티팩트 지속성 및 보관처리
- 대규모 페이로드 처리
- 자동화된 리소스 관리
RAG를 통한 동적 컨텍스트 검색
에이전트는 Cloud Storage에서 문서를 검색하고 읽어 실시간으로 질문에 답변하는 조사자 역할을 할 수 있습니다. 이 접근 방식은 내부 기술 자료 또는 지원 봇에 유용합니다.
- 정책 조회: 에이전트가
compliance-docs버킷의 최신 PDF 설명서를 나열하고 읽어 회사 정책에 관한 사용자 질문에 답변하도록 할 수 있습니다. - 다중 객체 합성: 여러 스토리지 객체에서 정보를 검색하고 결합하여 통합 요약을 합성하는 에이전트를 빌드할 수 있습니다.
아티팩트 지속성 및 보관처리
사람의 검토, 다른 시스템 또는 감사를 위해 에이전트가 생성한 대량의 데이터를 안정적으로 저장합니다.
- 자동 보고: 데이터베이스 측정항목을 분석하고 요약 보고서를 생성하여
reports-archive버킷에 업로드하는 에이전트를 만들 수 있습니다. - 생성된 미디어 저장: 생성된 이미지 또는 오디오 객체를 Cloud Storage에 저장하고 스토리지 URI 또는 서명된 URL만 반환하도록 멀티 에이전트 시스템을 구성할 수 있습니다.
대규모 페이로드 처리
채팅에 전체 파일 콘텐츠를 붙여넣는 대신 스토리지 URI (파일 경로)를 사용하도록 에이전트를 설계합니다. 이렇게 하면 대규모 CSV 또는 코드베이스를 LLM에 전송하는 데 드는 높은 비용과 비효율성을 방지할 수 있습니다.
- 데이터 파이프라인 핸들러: 에이전트가 대규모 CSV를 사용하는 대신 스토리지 URI를 수신하도록 할 수 있습니다. 그러면 에이전트가 청크를 처리하거나 메타데이터를 검사하여 분석을 수행하고 요약 대시보드를 반환할 수 있습니다.
- 분리된 워크플로: Cloud Storage 프리픽스, 폴더 또는 버킷의 스토리지 URI를 수신하는 감독자 역할을 하도록 에이전트를 설계할 수 있습니다. 에이전트는 이 URI를 백엔드 작업자에게 전달하여 객체를 처리하고 최종 결과를 스토리지에 다시 쓸 수 있습니다. 이 패턴은 Cloud Run Functions 또는 Cloud Run과 같은 이벤트 기반 서비스와 호환되어 데이터를 비동기식으로 처리합니다.
자동화된 리소스 관리
에이전트는 스토리지 사용량을 최적화하고, 관리 작업을 자동화하며, 여러 버킷에 거버넌스를 적용하는 데 도움이 될 수 있습니다. 이는 대규모 스토리지 인프라를 관리하는 팀에 특히 유용합니다.
- 인프라 감사: 버킷 구성 (예: 위치 또는 스토리지 클래스)을 스캔하고 최적화를 제안하거나 규정을 준수하지 않는 설정을 식별하는 에이전트를 만들 수 있습니다.
- 리소스 정리: 비어 있거나 오래된 버킷을 식별하고 보관 정책에 따라 정리 프로세스를 자동화하는 에이전트를 빌드할 수 있습니다.
Cloud Storage용 ADK 도구 세트
ADK는 Cloud Storage용 Python에서 다음 도구 모음을 제공합니다. 두 가지를 모두 이해하면 상담사 역할을 정의하고 권한을 제한하는 데 도움이 됩니다.
데이터 관리를 위한 GCSToolset
GCSToolset 도구 모음을 사용하면 에이전트가 기존 버킷 내의 파일을 조작할 수 있습니다. 문서 읽기, 결과 업로드, 임시 객체 삭제와 같은 작업에 사용합니다.
- 객체 읽기:
get_object_data를 사용하여 콘텐츠를 직접 검색합니다. - 콘텐츠 검색:
list_objects를 사용하여 사용 가능한 객체를 나열합니다. - 객체 속성 검사:
get_object_metadata를 사용하여 객체 크기 또는Content-Type메타데이터를 확인합니다. - 업로드 및 저장:
create_object를 사용하여 새 객체를 만듭니다. - 객체 삭제:
delete_objects를 사용하여 임시 객체를 삭제합니다.
인프라용 GCSAdminToolset
GCSAdminToolset 도구 모음을 사용하여 버킷 생성 또는 관리 작업 자동화와 같은 스토리지 인프라를 관리합니다.
- 인프라 탐색:
list_buckets를 사용하여 프로젝트의 버킷을 나열합니다. - 스토리지 프로비저닝:
create_bucket를 사용하여 새 버킷을 만듭니다. - 스토리지 재구성:
update_bucket를 사용하여 구성을 수정합니다. - 스토리지 프로비저닝 해제:
delete_bucket를 사용하여 버킷을 삭제합니다. - 버킷 컨텍스트 검사:
get_bucket를 사용하여 버킷 메타데이터를 가져와 버킷 위치, 스토리지 클래스 또는 액세스 제어를 확인합니다.
권장사항
Cloud Storage와 통합할 때 에이전트 성능과 보안을 최적화하려면 다음 권장사항을 고려하세요.
- 대화 기록에서 대용량 페이로드 분리: 대용량 파일을 에이전트에 직접 전달하지 않습니다. Cloud Storage에 저장하고 파일 참조 (URI)를 대신 전송합니다. 이렇게 하면 토큰 비용이 절감되고 컨텍스트 한도에 도달하는 것을 방지할 수 있습니다.
- 최소 권한의 원칙 적용: 에이전트에게 작업을 수행하는 데 필요한 최소한의 권한만 부여합니다. 인프라를 관리하는 경우가 아니라면
roles/storage.admin와 같은 광범위한 역할은 피하세요. 표준 파일 작업의 경우 특정 버킷으로 제한된roles/storage.objectUser또는roles/storage.objectViewer와 같은 타겟팅된 역할을 사용합니다. - 중앙에서 구성 관리: 에이전트 로직에서 버킷 이름이나 객체 이름 경로를 하드코딩하지 마세요. 환경 변수 또는 구성 관리자를 사용하여 개발, 테스트, 프로덕션 스토리지 환경 간에 전환합니다.
- 효율적인 검색 전략 구현: Cloud Storage를 지식 검색 레이어로 사용하는 경우 대규모 문서 전체를 에이전트의 컨텍스트에 로드하지 마세요. 문서를 사전 처리하고 청크로 나누거나 전용 검색 도구를 사용하여 관련 세그먼트만 검색합니다.
제한사항
Cloud Storage를 ADK와 통합할 때는 다음 제한사항에 유의하세요.
- 변경할 수 없는 객체: Cloud Storage 객체는 변경할 수 없습니다. 기존 객체에 데이터를 추가할 수 없습니다. 에이전트가 단일 파일에 이벤트를 지속적으로 로깅해야 하는 경우 객체를 완전히 덮어쓰거나 여러 개의 작은 객체를 만들고 나중에 객체를 구성해야 합니다.
- 고빈도 상태 관리의 지연 시간: Cloud Storage는 내구성이 우수한 아티팩트 스토리지와 대규모 페이로드에 적합합니다. 하지만 빈도가 높고 지연 시간이 짧은 상태 업데이트에 Cloud Storage를 사용하면 지연 시간이 발생할 수 있습니다. 예를 들어 빠른 대화 교환에서 모든 대화를 추적하는 것은 메모리 캐시나 데이터베이스를 사용하는 것보다 느릴 수 있습니다.
- 다중 객체 원자성 부족: Cloud Storage 작업은 개별 객체에 적용됩니다. 에이전트가 여러 파일에서 동시에 원자적 업데이트를 수행해야 하는 경우 애플리케이션 내에서 조정 로직을 구현해야 합니다.
다음 단계
- Python 애플리케이션에서 Cloud Storage 도구 모음을 초기화하는 자세한 코드 예시, 설정 안내, 매개변수 참조는 ADK 통합 가이드를 참고하세요.
- ADK 에이전트 또는 AI 코딩 지원과 함께 사전 빌드된 에이전트 스킬을 사용하려면 Cloud Storage 에이전트 스킬을 참조하세요.