에이전트 개발 키트 (ADK) 에이전트는 외부 서비스와 상호작용합니다 Google Cloud. 에이전트 ID와 Identity and Access Management (IAM)를 모두 사용하면 서비스로 인증할 수 있습니다. Google Cloud하지만 Google의 ID 제휴를 지원하지 않는 외부 플랫폼에는 ID를 증명할 수 없습니다.
ADK 에이전트는 MCP 서비스, ADK 도구, API와 같은 외부 항목과 상호작용하기 위해 다양한 사용자 인증 정보에 액세스해야 합니다. 일반적인 예는 다음과 같습니다.
- 결제 처리 플랫폼용 API 키
- 기존 온프레미스 데이터베이스의 사용자 이름 및 비밀번호 조합
- 상호 TLS (mTLS) 연결의 비공개 키
google.adk.integrations.secret_manager.secret_client 패키지 내에서 SecretManagerClient 모듈을 제공합니다. 이 모듈은 에이전트가 런타임에 Secret Manager에서 보안 비밀을 가져올 수 있는 표준 인터페이스를 제공합니다.
이 문서에서는 Secret Manager를 사용하여 ADK에서 외부 서비스의 보안 비밀을 관리하는 방법을 설명합니다.
ADK에서 Secret Manager를 사용하는 이점
수동 보안 비밀 관리는 보안 위험을 초래하고 개발자의 반복 업무를 증가시킬 수 있습니다. Secret Manager는 다음을 통해 이러한 문제를 해결하는 데 도움이 될 수 있습니다.
- 보안 비밀을 에이전트 코드에 삽입하면 심각한 보안 위험이 발생합니다. 이 관행은 무단 액세스로 이어질 수 있습니다. Secret Manager를 사용하면 소스 코드에서 민감한 정보가 삭제됩니다. 이렇게 하면 애플리케이션의 보안을 강화할 수 있습니다.
- 환경 변수를 통해 정적 보안 비밀을 삽입하면 사용자 인증 정보 순환이 복잡해집니다. 업데이트를 적용하려면 배포 컨테이너를 다시 시작해야 합니다. Secret Manager는 런타임에 사용자 인증 정보를 동적으로 가져오므로 시스템 다운타임 없이 업데이트할 수 있습니다.
- 모든 도구에 대해 커스텀
SecretManagerServiceClient상용구 코드를 작성하면 개발자의 반복 업무와 오류 위험이 증가합니다. 표준화된 ADK 통합은 사용자 인증 정보를 가져오는 깔끔하고 재사용 가능한 접근 방식을 제공합니다.
시작하기 전에
Secret Manager를 ADK와 통합하기 전에 다음 단계를 완료하세요.
- ADK를 사용하여 에이전트를 설정합니다. 이 기능을 사용하려면 Python용 ADK 버전 1.29 이상이 필요합니다.
- 에이전트
ID에
Secret Manager Secret AccessorIAM 역할을 부여합니다. 이 역할을 사용하면 에이전트가 런타임에 보안 비밀을 가져올 수 있습니다. - Secret Manager에서 보안 비밀을 만들고 API 키와 같은 보안 비밀 버전을 추가합니다.
ADK 에이전트가 런타임에 보안 비밀을 가져오는 방법
secret_client.SecretManagerClient 모듈은 런타임에 사용자 인증 정보를 Python 에이전트 코드 로직으로 가져옵니다. 에이전트 조정 로직은 실행할 도구를 결정하기 위해 대규모 언어 모델 (LLM)에 프롬프트를 전송하지만 시스템은 보안 비밀을 LLM에 전송하지 않습니다.
에이전트는 런타임 단계에서 다음 단계를 실행합니다.
- ADK 에이전트가 서드 파티 도구를 호출하기 전에 에이전트는
SecretManagerClient모듈을 초기화하고get_secret()함수를 호출합니다. - ADK 에이전트는 에이전트 ID를 사용하여 Secret Manager로 인증합니다.
SecretManagerClient모듈은 일반 텍스트 보안 비밀을 ADK 에이전트에 반환합니다.- ADK 에이전트는 보안 비밀을 사용하여 서드 파티 도구에 인증된 호출을 합니다.
런타임에 ADK 에이전트 내에서 보안 비밀 가져오기
다음 코드 샘플은 SecretManagerClient 모듈을 사용하여 ADK 에이전트 내에서 보안 비밀을 안전하게 가져오는 방법을 보여줍니다. 에이전트는 민감한 사용자 인증 정보가 LLM의 컨텍스트 윈도우 또는 대화 기록에 노출되지 않도록 보안 비밀을 내부적으로 가져옵니다.
Python
이 코드를 실행하려면 먼저 Python 개발 환경을 설정하고 Secret Manager Python SDK를 설치합니다. Compute Engine 또는 GKE에서는 cloud-platform 범위로 인증해야 합니다.
다음 단계
- 에이전트 개발 키트를 살펴봅니다.