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 Connector API.

    Peran yang diperlukan untuk mengaktifkan API

    Untuk mengaktifkan API, Anda memerlukan peran IAM Service Usage Admin (roles/serviceusage.serviceUsageAdmin), yang berisi izin serviceusage.services.enable. Pelajari cara memberikan peran.

    Mengaktifkan API

  2. Pastikan Anda memiliki peran Pengguna Vertex AI (roles/aiplatform.user) di project Anda.

Membuat dan men-deploy agen

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

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

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

  2. Buat project agen baru menggunakan template prototipe:

    agents-cli create AGENT_PROJECT --prototype --yes

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

    Perintah ini membuat struktur direktori project berikut:

    (Catatan: Diagram berikut menandai file konfigurasi yang relevan dan mungkin tidak mewakili semua file di direktori Anda.)

    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):

    mv app AGENT_NAME

    Kemudian, 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",
)

  4. Aktifkan Identitas Agen dengan membuat file konfigurasi:

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

  5. Buat file requirements.txt untuk dependensi deployment:

    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. 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

    Verifikasi agen Anda secara lokal:

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

    Untuk memvalidasi agen Anda, lakukan hal berikut:

    1. Buka http://localhost:8501.
    2. Di antarmuka chat, kirim perintah pengujian untuk memverifikasi respons.

  7. 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 tempat Anda ingin men-deploy agen (misalnya, us-west1).

    Setelah deployment selesai, CLI akan menampilkan pesan konfirmasi dan link ke playground agen Anda di Google Cloud konsol.

  8. Ambil ID SPIFFE (Identitas Agen) agen Anda dari Google Cloud konsol:

    1. Di Google Cloud konsol, buka halaman Agent Platform.
    2. Klik tab Deployments , lalu pilih agen yang di-deploy.
    3. Salin nilai Agent Identity (misalnya, principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/aiplatform/projects/PROJECT_NUMBER/locations/LOCATION/reasoningEngines/ENGINE_ID).

Langkah berikutnya