이 가이드에서는 에이전트 아이덴티티가 사용 설정된 Gemini Enterprise Agent Platform의 Agent Runtime에서 에이전트를 만들고 배포하는 방법을 보여줍니다.
에이전트 아이덴티티는 배포된 에이전트에 안전한 SPIFFE ID를 할당합니다. 에이전트는 이 ID를 사용하여 Google Cloud 서비스에 인증하고 에이전트 ID 인증 관리자에서 사용자 인증 정보를 가져옵니다.
시작하기 전에
아직 사용 설정되지 않은 API가 있는 경우 에이전트 아이덴티티 API, Agent Platform API, Agent Registry API, App Hub API를 사용 설정합니다.
API 사용 설정에 필요한 역할
API를 사용 설정하려면
serviceusage.services.enable권한이 필요합니다. 프로젝트를 만든 경우 소유자 역할 (roles/owner)을 통해 이 권한이 이미 있을 수 있습니다. 그렇지 않으면 서비스 사용량 관리자 역할 (roles/serviceusage.serviceUsageAdmin)을 통해 이 권한을 얻을 수 있습니다. 역할을 부여하는 방법 알아보기프로젝트에 Agent Platform 사용자 (
roles/aiplatform.user) 역할이 있는지 확인합니다.
에이전트 만들기 및 배포
google-agents-cli를 사용하여 샘플 에이전트를 만들고 에이전트 ID로 배포합니다.
uv을 설치한 후google-agents-cli설정을 실행합니다.pip install uv uvx google-agents-cli setup
프로토타입 템플릿을 사용하여 에이전트 프로젝트를 만듭니다.
uvx google-agents-cli create AGENT_PROJECT --prototype --yes
AGENT_PROJECT을 새 에이전트 프로젝트 디렉터리의 이름 (예:maps-agent)으로 바꿉니다.이 명령어는 다음 프로젝트 디렉터리 구조를 생성합니다.
AGENT_PROJECT/ ├── app/ # Core agent code │ ├── agent.py # Main agent logic │ ├── fast_api_app.py # Client application logic │ └── app_utils/ # App utilities and helpers ├── tests/ # Unit and integration tests ├── GEMINI.md # Development guide └── pyproject.toml # Project dependencies
기본 애플리케이션 폴더 (
app)를 에이전트 이름(예:AGENT_NAME,maps_agent)과 일치하도록 이름을 바꿉니다. 에이전트 이름은 유효한 Python 식별자여야 합니다. 문자로 시작해야 하며 문자, 숫자, 밑줄만 포함해야 합니다.cd AGENT_PROJECT mv app AGENT_NAME
새 이름을 반영하도록
agent.py구성 파일을 업데이트합니다.# In AGENT_PROJECT/AGENT_NAME/agent.py app = App( root_agent=root_agent, name="
AGENT_NAME", )지역별 가용성에 따라 사용할 모델을 선택합니다. 선택한 모델과 일치하도록
agent.py의MODEL값을 업데이트합니다.global지역에서만 사용할 수 있는 모델의 해결 방법global리전에서만 사용할 수 있는 모델을 사용하려면 에이전트가 액세스할 수 있도록agent.py를 수정해야 합니다.-
다음 가져오기를 추가합니다.
from functools import cached_property from google.genai import Client
-
가져오기 뒤에 다음 하위 클래스를 추가합니다.
class GlobalGemini(Gemini): @cached_property def api_client(self) -> Client: return Client(enterprise=True, location="global")
-
다음 코드를 찾습니다.
root_agent = Agent( name="root_agent", model=Gemini(
새 하위 클래스를 참조하도록 변경합니다.
root_agent = Agent( name="root_agent", model=GlobalGemini(
-
구성 파일을 만들어 에이전트 아이덴티티를 사용 설정합니다.
echo '{ "identity_type": "AGENT_IDENTITY" }' > AGENT_NAME/.agent_engine_config.json
배포 종속 항목의
requirements.txt파일을 만듭니다.uv export \ --no-emit-workspace \ --no-hashes \ --format requirements.txt \ --output-file AGENT_NAME/requirements.txt
프로젝트 디렉터리 구조를 확인합니다.
AGENT_PROJECT/ ├── AGENT_NAME/ # Agent application folder │ ├── .agent_engine_config.json # Agent Identity configuration │ ├── agent.py # Main agent logic │ ├── fast_api_app.py # Client application logic │ ├── requirements.txt # Deployment dependencies │ └── app_utils/ # App helpers ├── tests/ # Tests ├── GEMINI.md # Development guide └── pyproject.toml # Project dependencies
로컬에서 에이전트를 테스트합니다.
uv run adk web . --port 8501 --reload_agents
에이전트를 검증하려면 다음 단계를 따르세요.
http://localhost:8501페이지로 이동합니다. 또는 Cloud Shell을 사용하는 경우 웹 서버 출력에서 제공하는 링크를 클릭합니다.채팅 인터페이스에서 테스트 프롬프트를 보내 응답을 확인합니다.
CTRL+C로 서버를 종료합니다.Google Cloud에 에이전트를 배포합니다.
uv run adk deploy agent_engine AGENT_NAME \ --project="PROJECT_ID" \ --region="LOCATION"
다음을 바꿉니다.
PROJECT_ID: Google Cloud 프로젝트 ID입니다.LOCATION: 에이전트를 배포할 지원되는 지역입니다 (예:us-west1).
배포를 완료하는 데 몇 분 정도 걸릴 수 있습니다. 완료되면 CLI에서 확인 메시지와 Google Cloud 콘솔의 에이전트 그라운드 링크를 출력합니다.
에이전트의 SPIFFE ID (에이전트 아이덴티티)를 가져옵니다.
Google Cloud 콘솔에서 배포 페이지로 이동합니다.
에이전트의 SPIFFE ID를 클립보드에 복사하려면 배포된 에이전트가 있는 행을 찾아 해당 행의 ID 열에서 클립보드에 복사를 클릭합니다. ID는 다음과 유사합니다.
principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID
다음 단계
- 에이전트 ID 개요
- 에이전트 ID 인증 관리자 개요
- 인증 관리자로 3-legged OAuth를 사용하여 인증
- 인증 관리자로 2-legged OAuth를 사용하여 인증
- 인증 관리자로 API 키를 사용하여 인증
- 에이전트 ID 인증 제공업체 관리