에이전트 개발 키트 (ADK) 에이전트를 Cloud Storage에 연결할 수 있습니다. 이 연결을 통해 에이전트가 기본 제공 ADK 도구 모음을 사용할 수 있습니다.
AI 개발자는 ADK를 Cloud Storage와 통합하여 에이전트를 저장된 데이터에 연결할 수 있습니다. 이 통합을 통해 에이전트 워크로드를 확장할 수 있습니다. Cloud Storage를 사용하여 장기 실행 작업의 상태, 메모리, 체크포인트를 유지할 수 있습니다. Cloud Storage를 사용하여 여러 에이전트 워크플로에서 중간 파일을 공유할 수도 있습니다.
이 문서에서는 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를 사용하여 사용 가능한 객체를 나열합니다. - 객체 속성 검사: 객체 크기 또는
Content-Type메타데이터를 사용하여get_object_metadata를 확인합니다. - 업로드 및 지속:
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 통합 가이드를 참조하세요.