이 문서에서는 에이전트 런타임의 환경을 설정할 때 발생할 수 있는 오류를 해결하는 방법을 설명합니다. 패키지 가져오기 문제의 문제 해결 단계를 다룹니다.
Agent Platform SDK를 가져올 때 발생하는 오류
Agent Platform SDK for Python을 가져올 수 없는 경우 다음 문제 중 하나가 원인일 수 있습니다.
오래된 버전의 Agent Platform SDK for Python
문제:
다음과 유사한 오류 메시지가 표시됩니다.
ImportError: cannot import name 'reasoning_engines' from 'vertexai.preview'
또는
ImportError: cannot import name 'agent_angines' from 'vertexai'
가능한 원인:
google-cloud-aiplatform 패키지 버전이 1.82.0(agent_engines의 경우) 또는 1.47.0(reasoning_engines의 경우) 이전 버전이면 이러한 오류가 발생할 수 있습니다. google-cloud-aiplatform 패키지 버전을 확인하려면 터미널에서 다음 명령어를 실행합니다.
pip show google-cloud-aiplatform추천 솔루션:
터미널에서 다음 명령어를 실행하여 google-cloud-aiplatform 패키지를 업데이트합니다.
pip install google-cloud-aiplatform --upgrade다음 명령어를 실행하여 업데이트된 버전이 1.82.0 이상인지 확인합니다.
pip show google-cloud-aiplatform노트북 인스턴스(예: Jupyter, Colab 또는 Workbench)를 사용하는 경우 업데이트된 패키지를 사용하려면 런타임을 다시 시작해야 할 수 있습니다.
401 승인 오류
문제:
다음과 유사한 오류 메시지가 표시됩니다.
Error Code: "401"
Error Details: "Context-Aware Access requirements are not met"
또는
Agent Engine Error: An error occurred during invocation. Exception: API request failed with status 401:
Request had invalid authentication credentials. Expected OAuth 2 access token, login cookie or other valid authentication credential.
가능한 원인:
기본적으로 에이전트 런타임과 함께 에이전트 ID를 사용하면 토큰 도용을 방지하기 위해 인증에 인증서 바인딩 액세스 토큰이 사용됩니다. 401 오류는 다음 두 가지 시나리오 중 하나에서 런타임에 발생할 수 있습니다.
- 발급된 컨텍스트 외부에서 액세스 토큰을 사용하려고 시도하는 사용자 또는 상담사(예: 상담사 간에 토큰을 전달하는 경우)
- 에이전트가 telemetry.mtls.googleapis.com 대신 telemetry.googleapis.com과 같은 mTLS 호환이 아닌 API 엔드포인트를 호출합니다.
추천 솔루션:
시나리오 1의 경우 에이전트 간에 토큰을 공유해야 하는 정당한 이유가 있다면 기본 컨텍스트 인식 액세스 (CAA) 정책을 선택 해제할 수 있습니다. 이 작업은 에이전트가 사용자 인증 정보 도난에 취약해지므로 권장되지 않습니다.
Agent Runtime 인스턴스를 만들 때 다음 환경 변수를 설정하여 기본 CAA 정책을 선택 해제합니다.
config={
"env_vars": {
"GOOGLE_API_PREVENT_AGENT_TOKEN_SHARING_FOR_GCP_SERVICES": False,
}
}
시나리오 2의 경우 에이전트가 비-mTLS API 엔드포인트를 임시 해결 방법으로 사용할 수 있도록 GOOGLE_API_PREVENT_AGENT_TOKEN_SHARING_FOR_GCP_SERVICES 변수를 False로 설정할 수 있습니다. 이 경우 근본적인 문제는 ADK의 알려진 문제일 수 있습니다.