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

Identitas Agen memungkinkan Anda menyediakan identitas terkelola untuk agen yang Anda buat dan deploy di Agent Runtime di Gemini Enterprise Agent Platform menggunakan Agent CLI dan Agent Development Kit (ADK). Agen yang di-deploy kemudian dapat melakukan autentikasi ke layananGoogle Cloud dan mengambil kredensial dari pengelola autentikasi Agent Identity tanpa pengelolaan kredensial manual.

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 Service Usage Admin (roles/serviceusage.serviceUsageAdmin). Pelajari cara memberikan peran.

    Aktifkan API

  2. Pastikan Anda memiliki peran Agent Platform User (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 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 region 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 Agent Identity 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 disediakan 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. Ambil ID SPIFFE agen Anda (Identitas Agen):

    1. Di konsol Google Cloud , buka halaman Deployments.

      Buka Deployment

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

Langkah berikutnya