Membuat dan men-deploy agen dengan Agent CLI dan Agent Identity

Panduan ini menunjukkan cara membuat dan men-deploy agen di Agent Runtime di Gemini Enterprise Agent Platform dengan Identitas Agen diaktifkan.

Identitas Agen menetapkan identitas SPIFFE yang aman ke agen yang di-deploy. Agen menggunakan identitas ini untuk mengautentikasi ke Google Cloud layanan dan mengambil kredensial dari pengelola autentikasi Identitas Agen.

Sebelum memulai

  1. Aktifkan Agent Identity API, Agent Platform API, Agent Registry API, dan App Hub API.

    Peran yang diperlukan untuk mengaktifkan API

    Untuk mengaktifkan API, Anda memerlukan izin serviceusage.services.enable. Jika Anda membuat project, kemungkinan Anda sudah memiliki izin ini melalui peran Pemilik (roles/owner). Jika tidak, Anda bisa mendapatkan izin ini melalui peran Admin Service Usage (roles/serviceusage.serviceUsageAdmin). Pelajari cara memberikan peran.

    Aktifkan API

  2. Pastikan Anda memiliki peran Pengguna Agent Platform (roles/aiplatform.user) di project Anda.

Membuat dan men-deploy agen

Buat agen contoh menggunakan google-agents-cli dan deploy dengan Identitas Agen:

  1. Instal uv, lalu jalankan penyiapan google-agents-cli:

    pip install uv
uvx google-agents-cli setup

  2. Buat project agen menggunakan template prototipe:

    uvx google-agents-cli create AGENT_PROJECT --prototype --yes

    Ganti AGENT_PROJECT dengan nama untuk direktori project agen baru Anda (misalnya, maps-agent).

    Perintah ini menghasilkan struktur direktori project berikut:

    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. Ganti nama folder aplikasi default (app) agar sesuai dengan nama agen Anda (AGENT_NAME, misalnya, maps_agent). Nama agen harus berupa ID Python yang valid: harus diawali dengan huruf, dan hanya berisi huruf, angka, dan garis bawah.

    cd AGENT_PROJECT
mv app AGENT_NAME

  4. Perbarui file konfigurasi agent.py untuk mencerminkan nama baru:

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

  5. Pilih model yang akan digunakan, berdasarkan ketersediaan regionalnya. Perbarui nilai untuk MODEL di agent.py agar sesuai dengan model yang Anda pilih.

    Solusi untuk model yang hanya tersedia di global region

    Untuk menggunakan model yang hanya tersedia di global region, Anda harus mengubah agent.py agar agen Anda dapat mengaksesnya.

    1. Tambahkan impor berikut:

      from functools import cached_property
from google.genai import Client

    2. Tambahkan subkelas berikut setelah impor:

      class GlobalGemini(Gemini):
    @cached_property
    def api_client(self) -> Client:
        return Client(enterprise=True, location="global")

    3. Temukan kode berikut:

      root_agent = Agent(
    name="root_agent",
    model=Gemini(

      Ubah kode tersebut untuk mereferensikan subkelas baru:

      root_agent = Agent(
    name="root_agent",
    model=GlobalGemini(

  6. Aktifkan Identitas Agen dengan membuat file konfigurasi:

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

  7. Buat file requirements.txt untuk dependensi deployment:

    uv export \
    --no-emit-workspace \
    --no-hashes \
    --format requirements.txt \
    --output-file AGENT_NAME/requirements.txt

  8. Verifikasi struktur direktori project:

    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

  9. Uji agen Anda secara lokal:

    uv run adk web . --port 8501 --reload_agents

    Untuk memvalidasi agen Anda, lakukan hal berikut:

    1. Buka http://localhost:8501. Atau, jika Anda menggunakan Cloud Shell, klik link yang disediakan oleh output server web.

    2. Di antarmuka chat, kirim perintah pengujian untuk memverifikasi respons.

  10. Hentikan server dengan CTRL+C.

  11. Deploy agen Anda ke Google Cloud:

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

    Ganti kode berikut:

    • PROJECT_ID: ID Google Cloud project Anda.

    • LOCATION: Region yang didukung tempat Anda ingin men-deploy agen (misalnya, us-west1).

    Deployment dapat memerlukan waktu beberapa menit untuk diselesaikan. Setelah selesai, CLI akan menampilkan pesan konfirmasi dan link ke playground agen Anda di konsol Google Cloud .

  12. Ambil ID SPIFFE agen Anda (Identitas Agen):

    1. Di Google Cloud konsol, buka halaman Deployment.

      Buka Deployment

    2. Untuk menyalin ID SPIFFE agen Anda ke papan klip, temukan baris tempat agen yang di-deploy berada, lalu di kolom Identitas baris tersebut, klik Salin ke papan klip. Identitasnya terlihat mirip dengan berikut: principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID.

Langkah berikutnya