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 Identity Agen diaktifkan.

Identitas Agen menetapkan identitas SPIFFE yang aman ke agen yang di-deploy. Agen menggunakan identitas ini untuk melakukan autentikasi ke layanan Google Cloud 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, jika ada yang belum diaktifkan.

    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 Penggunaan Layanan (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 Agent Identity:

  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 Anda 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 wilayah global

    Untuk menggunakan model yang hanya tersedia di region global, 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 subclass 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 untuk mereferensikan subclass 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. Menguji 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 diberikan oleh output server web.

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

  10. Hentikan server dengan CTRL+C.

  11. Men-deploy agen Anda ke Google Cloud:

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

    Ganti kode berikut:

    • PROJECT_ID: Project ID Google Cloud Anda.

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

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

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

    1. Di konsol Google Cloud , buka halaman Deployments.

      Buka Deployment

    2. Untuk menyalin SPIFFE ID agen ke papan klip, temukan baris tempat agen yang di-deploy berada, lalu di kolom Identity pada baris tersebut, klik Copy to clipboard. Identitasnya akan terlihat seperti berikut: principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID.

Langkah berikutnya