에이전트 CLI 및 에이전트 ID로 에이전트 만들기 및 배포

이 가이드는 Agent Identity가 사용 설정된 Gemini Enterprise Agent Platform 의 Agent Runtime에서 에이전트를 만들고 배포하는 방법을 보여줍니다.

Agent Identity는 배포된 에이전트에 안전한 SPIFFE ID를 할당합니다. 에이전트는 이 ID를 사용하여 서비스에 인증하고 Agent Identity 인증 관리자에서 사용자 인증 정보를 가져옵니다. Google Cloud

시작하기 전에

  1. Agent Identity Connector API를 사용 설정합니다.

    API 사용 설정에 필요한 역할

    API를 사용 설정하려면 serviceusage.services.enable 권한이 포함된 서비스 사용량 관리자 IAM 역할(roles/serviceusage.serviceUsageAdmin)이 필요합니다. 역할 부여 방법 알아보기

    API 사용 설정하기

  2. 프로젝트에 Vertex AI 사용자 (roles/aiplatform.user) 역할이 있는지 확인합니다.

에이전트 만들기 및 배포

agents-cli를 사용하여 샘플 에이전트를 만들고 Agent Identity로 배포합니다.

  1. google-agents-cli 및 uv를 설치한 후 설정을 실행합니다.

    pip install google-agents-cli uv
agents-cli setup

  2. 프로토타입 템플릿을 사용하여 새 에이전트 프로젝트를 만듭니다.

    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

  3. 기본 애플리케이션 폴더 (app)의 이름을 에이전트 이름(AGENT_NAME, 예: maps_agent)과 일치하도록 바꿉니다.

    mv app AGENT_NAME

    그런 다음 새 이름을 반영하도록 agent.py 구성 파일을 업데이트합니다.

    # In AGENT_PROJECT/AGENT_NAME/agent.py
app = App(
    root_agent=root_agent,
    name="AGENT_NAME",
)

  4. 구성 파일을 만들어 Agent Identity를 사용 설정합니다.

    echo '{ "identity_type": "AGENT_IDENTITY" }' > .agent_engine_config.json

  5. 배포 종속 항목의 requirements.txt 파일을 만듭니다.

    echo "httpx" > requirements.txt
echo "google-auth" >> requirements.txt
echo "google-adk[agent_engines,agent-identity]" >> requirements.txt
echo "google-cloud-aiplatform[agent_engines,adk]>=1.153.1" >> requirements.txt

  6. 프로젝트 디렉터리 구조를 확인합니다.

    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

    에이전트를 검증하려면 다음 단계를 따르세요.

    1. http://localhost:8501로 이동합니다.
    2. 채팅 인터페이스에서 테스트 프롬프트를 전송하여 응답을 확인합니다.

  7. 에이전트를 다음 위치에 배포합니다. Google Cloud

    uv run adk deploy agent_engine AGENT_NAME \
    --project="PROJECT_ID" \
    --region="LOCATION"

    다음을 바꿉니다.

    • PROJECT_ID: 프로젝트 ID입니다. Google Cloud
    • LOCATION: 에이전트를 배포할 리전 (예: us-west1)입니다.

    배포가 완료되면 CLI는 확인 메시지와 콘솔의 에이전트 플레이그라운드 링크를 출력합니다. Google Cloud

  8. 콘솔에서 에이전트의 SPIFFE ID (Agent Identity)를 가져옵니다. Google Cloud

    1. 콘솔에서 Agent Platform 페이지로 이동합니다. Google Cloud
    2. 배포 탭을 클릭하고 배포된 에이전트를 선택합니다.
    3. Agent Identity 값 (예: principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID)을 복사합니다.

다음 단계