Panduan memulai: Mem-build agen dengan Agent Development Kit

Panduan memulai ini memandu Anda dalam menyiapkan project Google Cloud , menginstal Agent Development Kit (ADK), menyiapkan agen dasar, dan menjalankan antarmuka pengguna developer-nya.

Panduan memulai ini mengasumsikan Anda menggunakan IDE lokal (VS Code, PyCharm, dll.) dengan Python 3.10+ dan akses terminal. Agen berjalan sepenuhnya di mesin Anda, yang direkomendasikan untuk pengembangan aplikasi lokal.

Sebelum memulai

Selesaikan langkah-langkah berikut:

Menyiapkan project Google Cloud

Siapkan Google Cloud project Anda dan aktifkan Vertex AI API.

  1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. Enable the Vertex AI API.

    Enable the API

  5. Make sure that you have the following role or roles on the project: Vertex AI User

    Check for the roles

    1. In the Google Cloud console, go to the IAM page.

      Go to IAM
    2. Select the project.

    3. In the Principal column, find all rows that identify you or a group that you're included in. To learn which groups you're included in, contact your administrator.

    4. For all rows that specify or include you, check the Role column to see whether the list of roles includes the required roles.

    Grant the roles

    1. In the Google Cloud console, go to the IAM page.

      Buka IAM
    2. Pilih project.
    3. Klik Berikan akses.

    4. Di kolom Akun utama baru, masukkan ID pengguna Anda. Biasanya berupa alamat email untuk Akun Google.

    5. Di daftar Pilih peran, pilih peran.
    6. Untuk memberikan peran tambahan, klik Tambahkan peran lain, lalu tambahkan setiap peran tambahan.
    7. Klik Simpan.

  6. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Go to project selector

  7. Verify that billing is enabled for your Google Cloud project.

  8. Enable the Vertex AI API.

    Enable the API

  9. Make sure that you have the following role or roles on the project: Vertex AI User

    Check for the roles

    1. In the Google Cloud console, go to the IAM page.

      Go to IAM
    2. Select the project.

    3. In the Principal column, find all rows that identify you or a group that you're included in. To learn which groups you're included in, contact your administrator.

    4. For all rows that specify or include you, check the Role column to see whether the list of roles includes the required roles.

    Grant the roles

    1. In the Google Cloud console, go to the IAM page.

      Buka IAM
    2. Pilih project.
    3. Klik Berikan akses.

    4. Di kolom Akun utama baru, masukkan ID pengguna Anda. Biasanya berupa alamat email untuk Akun Google.

    5. Di daftar Pilih peran, pilih peran.
    6. Untuk memberikan peran tambahan, klik Tambahkan peran lain, lalu tambahkan setiap peran tambahan.
    7. Klik Simpan.

    10. Menyiapkan kredensial

    Di terminal lokal, siapkan dan lakukan autentikasi dengan Google Cloud CLI. Jika Anda sudah memahami Gemini API di Google AI Studio, perhatikan bahwa Gemini API di Vertex AI menggunakan Identity and Access Management, bukan kunci API, untuk mengelola akses.

    1. Instal dan lakukan inisialisasiGoogle Cloud CLI.

    2. Jika sebelumnya Anda telah menginstal gcloud CLI, pastikan komponen gcloud Anda diupdate dengan menjalankan perintah ini.

      gcloud components update

    3. Jalankan perintah berikut untuk membuat file Kredensial Default Aplikasi (ADC) lokal. Agen Anda akan menggunakan kredensial ini untuk mengakses Vertex AI selama pengembangan aplikasi lokal.

      gcloud auth application-default login

      Untuk mengetahui informasi selengkapnya, lihat Menyiapkan Kredensial Default Aplikasi.

    Menyiapkan lingkungan virtual dan menginstal ADK

    • Buat dan aktifkan lingkungan virtual (Direkomendasikan):

      # Create
python -m venv .venv
# Activate (uncomment the line relevant to your environment)
# macOS/Linux: source .venv/bin/activate
# Windows CMD: .venv\Scripts\activate.bat
# Windows PowerShell: .venv\Scripts\Activate.ps1

    • Instal ADK:

      pip install google-adk

    Buat agen

    Menggunakan terminal, buat struktur folder:

    mkdir multi_tool_agent/
touch \
multi_tool_agent/__init__.py \
multi_tool_agent/agent.py \
multi_tool_agent/.env

    Struktur Anda:

    parent_folder/
    multi_tool_agent/
        __init__.py
        agent.py
        .env

    Salin dan tempel kode berikut ke dalam tiga file yang Anda buat:

    • \_\_init\_\_.py

      from . import agent

    • .env

      # If using Gemini via Vertex AI on Google CLoud
GOOGLE_CLOUD_PROJECT="your-project-id"
GOOGLE_CLOUD_LOCATION="your-location" #e.g. us-central1
GOOGLE_GENAI_USE_VERTEXAI="True"

    • agent.py

      from google.adk.agents import Agent

def get_weather(city: str) -> dict:
    """Retrieves the current weather report for a specified city.

    Returns:
        dict: A dictionary containing the weather information with a 'status' key ('success' or 'error') and a 'report' key with the weather details if successful, or an 'error_message' if an error occurred.
    """
    if city.lower() == "new york":
        return {"status": "success",
                "report": "The weather in New York is sunny with a temperature of 25 degrees Celsius (77 degrees Fahrenheit)."}
    else:
        return {"status": "error",
                "error_message": f"Weather information for '{city}' is not available."}

def get_current_time(city:str) -> dict:
    """Returns the current time in a specified city.

    Args:
        dict: A dictionary containing the current time for a specified city information with a 'status' key ('success' or 'error') and a 'report' key with the current time details in a city if successful, or an 'error_message' if an error occurred.
    """
    import datetime
    from zoneinfo import ZoneInfo

    if city.lower() == "new york":
        tz_identifier = "America/New_York"
    else:
        return {"status": "error",
                "error_message": f"Sorry, I don't have timezone information for {city}."}

    tz = ZoneInfo(tz_identifier)
    now = datetime.datetime.now(tz)
    return {"status": "success",
            "report": f"""The current time in {city} is {now.strftime("%Y-%m-%d %H:%M:%S %Z%z")}"""}

root_agent = Agent(
    name="weather_time_agent",
    model="gemini-2.0-flash",
    description="Agent to answer questions about the time and weather in a city.",
    instruction="I can answer your questions about the time and weather in a city.",
    tools=[get_weather, get_current_time]
)

    Agen dilengkapi dengan dua alat fungsi dengan penerapan tiruan.

    Menjalankan dan menguji agen Anda

    1. Di terminal, buka direktori induk agen (misalnya, menggunakan cd ..):

      parent_folder/      <-- navigate to this directory
    multi_tool_agent/
        __init__.py
        agent.py
        .env

    2. Jalankan perintah berikut untuk meluncurkan UI Web developer.

      adk web

      Buka URL yang diberikan (biasanya http://localhost:8000 atau http://127.0.0.1:8000) di browser Anda. Koneksi ini sepenuhnya berada di komputer lokal Anda. Pilih multi_tool_agent dan berinteraksi dengan agen.

    Contoh perintah yang dapat dicoba

    Anda dapat mencoba perintah berikut:

    • Bagaimana cuaca di New York?
    • Sekarang jam berapa di New York?
    • Bagaimana cuaca di Bandung?
    • Jam berapa sekarang di Paris?

    Langkah berikutnya