Next ‘26 Developer Keynote: Membangun Agen ADK dengan Keterampilan dan Alat

1. Pengantar

Dalam codelab ini, Anda akan membangun Agen Perencana Maraton canggih menggunakan Agent Development Kit (ADK). Anda akan memeriksa kemampuan agen secara progresif, mulai dari perintah sistem yang terstruktur dengan baik hingga pemetaan alat MCP dan pemuatan keterampilan dinamis. Terakhir, Anda akan menguji agen secara lokal dan men-deploy-nya ke Agent Runtime (Agent Engine).

Yang akan Anda lakukan

  • Lakukan inisialisasi project agen ADK baru
  • Menyusun perintah sistem yang efektif menggunakan builder terstruktur
  • Menambahkan alat MCP Google Maps untuk konteks lokasi di dunia nyata
  • Memuat skill secara dinamis ke dalam toolset agen
  • Menguji eksekusi agen secara lokal
  • Deploy agen ke Agent Engine (Cloud Run)

Yang Anda butuhkan

  • Browser web seperti Chrome
  • Project Google Cloud yang mengaktifkan penagihan
  • Pemahaman dasar tentang Python

Codelab ini ditujukan bagi developer tingkat menengah yang ingin membangun agen AI generatif khusus.

Perkiraan durasi: 45 menit

Resource yang dibuat dalam codelab ini seharusnya berbiaya kurang dari $2.

2. Sebelum memulai

Buat Project Google Cloud

  1. Di Konsol Google Cloud, di halaman pemilih project, pilih atau buat project Google Cloud.
  2. Pastikan penagihan diaktifkan untuk project Cloud Anda. Pelajari cara memeriksa apakah penagihan telah diaktifkan pada suatu project.

Mulai Cloud Shell

Cloud Shell adalah lingkungan command line yang berjalan di Google Cloud yang telah dilengkapi dengan alat yang diperlukan.

  1. Klik Activate Cloud Shell di bagian atas konsol Google Cloud.
  2. Setelah terhubung ke Cloud Shell, verifikasi autentikasi Anda:
    gcloud auth list
  3. Pastikan project Anda dikonfigurasi:
    gcloud config get project
  4. Jika project Anda tidak ditetapkan seperti yang diharapkan, tetapkan project:
    export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project $PROJECT_ID

Verifikasi autentikasi:

gcloud auth list

Konfirmasi project Anda:

gcloud config get project

Tetapkan jika perlu:

export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project $PROJECT_ID

Mengaktifkan API

Jalankan perintah ini untuk mengaktifkan semua API yang diperlukan:

gcloud services enable \
  aiplatform.googleapis.com \
  run.googleapis.com \
  secretmanager.googleapis.com \
  mapstools.googleapis.com \
  storage.googleapis.com \
  cloudresourcemanager.googleapis.com \
  serviceusage.googleapis.com

Membuat Kunci API Google Maps

Untuk menggunakan alat MCP Google Maps, Anda perlu membuat kunci Maps API.

  1. Di Konsol Google Cloud, gunakan kotak penelusuran untuk membuka Google Maps Platform > Credentials.
  2. Jika diminta, konfirmasi project Google Cloud Anda.
  3. Klik Create Credentials, lalu pilih API key.
  4. Salin kunci API yang dibuat. Anda akan membutuhkan alamat itu pada langkah berikutnya.

3. Menyiapkan lingkungan Anda

Untuk codelab ini, kode dihosting di GitHub. Anda akan meng-clone repositori, yang berisi struktur direktori dan sub-komponen yang diperlukan (seperti direktori skills/).

  1. Clone repositori dan buka folder project:
git clone https://github.com/GoogleCloudPlatform/next-26-keynotes
cd next-26-keynotes/devkey/demo-1
  1. Siapkan lingkungan virtual Python dan instal ADK:
uv venv
source .venv/bin/activate
uv sync
  1. Tetapkan kunci Maps API Anda. Aplikasi membacanya dari variabel lingkungan:
export GOOGLE_MAPS_API_KEY="<YOUR_MAPS_API_KEY>"

Mengonfigurasi Variabel Lingkungan

Agen Simulator menggunakan file .env untuk konfigurasi. Salin file sampel dan perbarui dengan Project ID Anda.

  1. Salin file lingkungan contoh:
cp planner_agent/sample.env planner_agent/.env
  1. Buka planner_agent/.env dan perbarui kolom GOOGLE_CLOUD_PROJECT dengan ID Project Google Cloud Anda yang sebenarnya, lalu perbarui kolom GOOGLE_MAPS_API_KEY dengan kunci Google Maps API yang Anda buat.

File-nya akan terlihat seperti ini:

GOOGLE_GENAI_USE_VERTEXAI=1
GOOGLE_CLOUD_PROJECT=<YOUR_PROJECT_ID>
GOOGLE_CLOUD_LOCATION=us-west1
GOOGLE_MAPS_API_KEY=<YOUR_MAPS_API_KEY>
GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY=true
OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED=true
OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true
ADK_CAPTURE_MESSAGE_CONTENT_IN_SPANS=true

4. Membuat agen ADK baru

Pelajari file inti yang menentukan agen: planner_agent/agent.py.

Di repositori build-agents-with-skills, agen diinisialisasi menggunakan class Agent ADK. Modul ini menentukan model pokok, nama identitas, dan menarik petunjuk serta alat yang ditentukan dalam modul lain.

Buka planner_agent/agent.py untuk memeriksa kode inisialisasi:

instruction="Answer user questions to the best of your knowledge"
description="A helpful assistant for user questions."
tools=[]

# ...

root_agent = Agent(
    model='gemini-3-flash-preview',
    name='planner_agent',
    description=description,
    instruction=instruction,
    tools=tools
)

Class Agent mengabstraksi histori pesan, orkestrasi alat, dan komunikasi LLM, sehingga Anda dapat berfokus pada perilaku agen.

Saat ini, agennya sangat umum. Anda dapat berinteraksi dengannya seperti LLM lainnya.

uv run adk run planner_agent

Perintah ini akan memulai percakapan dengan agen. Aplikasi ini menggunakan gemini-3-flash-preview sebagai modelnya dan dapat menjawab pertanyaan dasar.

Running agent planner_agent, type exit to exit.
[user]: What is the length of a Marathon
[planner_agent]: The official length of a marathon is **26.2 miles**, which is
equivalent to **42.195 kilometers**.

Agen sudah mengetahui beberapa fakta tentang maraton. Namun, hal ini tidak cukup untuk merencanakan maraton yang tepat dengan aturan dan perencanaan rute.

5. Membuat perintah sistem

Perintah sistem (petunjuk) menentukan perilaku agen. Alih-alih menggunakan satu string besar, project ini menggunakan PromptBuilder (planner_agent/utils.py) untuk menyusun petunjuk secara dinamis.

Buka planner_agent/prompts.py untuk melihat cara perintah disusun ke dalam bagian logis:

from collections import OrderedDict
from .utils import PromptBuilder

ROLE = """\
...
"""

RULES = """\
...
"""

WORKFLOW = """\
...
"""

###

# Planner instructions with no tools mentioned
PLANNER_INSTRUCTION_NO_TOOLS = PromptBuilder(
    OrderedDict(
        role=ROLE,
        rules=RULES,
        tools=TOOLS_PROMPT_ONLY,
        workflow=WORKFLOW_PROMPT_ONLY,
    )
).build()

# Planner instruction with skills and tools defined
PLANNER_INSTRUCTION = PromptBuilder(
    OrderedDict(
        role=ROLE,
        rules=RULES,
        skills=SKILLS,
        tools=TOOLS,
        workflow=WORKFLOW,
    )
).build()

Kembali di planner_agent/agent.py, ini sudah diimpor.

Temukan bagian dengan TODO: Replace Instruction and Description dan hapus komentar penetapan ulang variabel instruction dan description.

Bagian kode tersebut akan terlihat seperti ini:

instruction=PLANNER_INSTRUCTION_NO_TOOLS
description="Expert GIS analyst for marathon route and event planning."

Anda mengimpor versi perintah untuk agen yang tidak mereferensikan alat apa pun. Anda akan menambahkan alat di langkah selanjutnya.

Anda dapat menguji versi agen ini:

uv run adk run planner_agent

Di jendela percakapan, kirim perintah berikut:

Plan a marathon for 10000 participants in Las Vegas on April 24, 2027 in the
evening timeframe

Setelah beberapa saat, Anda akan menerima respons yang mirip dengan ini:

Running agent planner_agent, type exit to exit.
[user]: Plan a marathon for 10000 participants in Las Vegas on April 24, 2027 in the evening timeframe
[planner_agent]: Here is the comprehensive marathon plan for Las Vegas.

As requested, I have designed this event for an evening start on April 24, 2027. Because certain parameters (theme and budget) were not specified, I have applied pragmatic defaults: this will be a "Neon Nights" scenic theme to capitalize on the evening Strip, operating on a moderate-to-high budget given the infrastructure needed to secure major Las Vegas corridors.

### 1. Intent Alignment
*   **City & Theme:** Las Vegas, Nevada. Theme: "Neon Nights" an evening race maximizing the visual impact of the illuminated city.
*   **Date & Time:** Saturday, April 24, 2027. Late April evenings in Las Vegas offer optimal running weather (temperatures dropping from ~70°F at sunset to ~60°F). Race start is 6:30 PM (sunset is approx. 7:20 PM).
...
...

Dengan perintah yang jelas, outputnya sudah jauh lebih mendekati hasil yang diharapkan. Pada langkah berikutnya, Anda akan menambahkan alat untuk meningkatkan kualitas agen.

6. Menambahkan keterampilan dan alat

Untuk mengaktifkan keterampilan dan alat di planner_agent/agent.py, temukan bagian dengan TODO: Replaces Tools dan hapus komentar dua baris berikutnya. Kode Anda akan terlihat seperti berikut:

instruction=PLANNER_INSTRUCTION
tools=get_tools()

Itulah satu-satunya perubahan kode yang diperlukan pada langkah ini. Bagian selanjutnya menjelaskan konsep di balik keterampilan dan alat.

Keahlian

Keahlian agen adalah unit fungsi mandiri yang dapat digunakan agen ADK untuk melakukan tugas tertentu. Keahlian agen mencakup petunjuk, resource, dan alat yang diperlukan untuk suatu tugas, berdasarkan spesifikasi Keahlian Agen. Struktur Skill memungkinkan Skill dimuat secara inkremental untuk meminimalkan dampak pada jendela konteks operasi agen.

Untuk agen perencanaan maraton, ada 3 keterampilan yang ditentukan:

  1. gis-spatial-engineering - Bertanggung jawab untuk memproses data GeoJSON guna membuat rute maraton.
  2. pemetaan - Gunakan alat Google Maps untuk menelusuri tempat dan info cuaca.
  3. race-director - Memvalidasi rute maraton mengikuti pedoman perencanaan.

Keterampilan dapat memiliki skrip, aset tambahan, dan referensi.

Aplikasi memuat semua keterampilan dan menyediakannya sebagai alat di planner_agent/tools.py. Perhatikan cara melakukannya dalam fungsi get_tools():

def get_tools() -> list:
    """Build the planner's tool list with lazy-loaded skills."""
    from google.adk.code_executors.unsafe_local_code_executor import UnsafeLocalCodeExecutor

    skills_dir = pathlib.Path(__file__).parent / "skills"

    skills = []
    if skills_dir.exists():
        skills = [
            load_skill_from_dir(d)
            for d in sorted(skills_dir.iterdir())
            if d.is_dir() and not d.name.startswith("_") and (d / "SKILL.md").exists()
        ]

    additional_tools = _load_additional_tools(skills_dir)

    skill_toolset = SkillToolset(
        skills=skills,
        code_executor=UnsafeLocalCodeExecutor(),
        additional_tools=additional_tools,
    )

    tools = [
        skill_toolset,
        PreloadMemoryTool(),
    ]

    tools.extend(get_maps_tools())

    return tools

Bagian yang paling menarik adalah metode load_skill_from_dir dari ADK. Ada cara lain untuk membuat skill di ADK, yaitu inline. Meskipun tidak digunakan dalam codelab ini, tampilannya akan seperti ini:

from google.adk.skills import models

greeting_skill = models.Skill(
    frontmatter=models.Frontmatter(
        name="greeting-skill",
        description=(
            "A friendly greeting skill that can say hello to a specific person."
        ),
    ),
    instructions=(
        "Step 1: Read the 'references/hello_world.txt' file to understand how"
        " to greet the user. Step 2: Return a greeting based on the reference."
    ),
    resources=models.Resources(
        references={
            "hello_world.txt": "Hello! So glad to have you here!",
            "example.md": "This is an example reference.",
        },
    ),
)

Menambahkan alat pemetaan

Perencana maraton memerlukan konteks spasial untuk membuat rute. Anda dapat menyediakannya dengan mengintegrasikan server MCP (Model Context Protocol) Google Maps.

Di planner_agent/tools.py, perhatikan cara server MCP didaftarkan dengan alat ApiRegistry:

from google.adk.integrations.api_registry import ApiRegistry

class MapsApiRegistry(ApiRegistry):
    """ApiRegistry subclass that strips ADC headers to force API key auth."""

    def get_toolset(self, *args, **kwargs):  # noqa: ANN002, ANN003
        toolset = super().get_toolset(*args, **kwargs)
        conn = getattr(toolset, "_connection_params", None)
        headers = getattr(conn, "headers", None) if conn else None
        if headers:
            headers.pop("Authorization", None)  # type: ignore[union-attr]
            headers.pop("x-goog-user-project", None)  # type: ignore[union-attr]
        return toolset

def get_maps_tools() -> list:
    """Return Maps MCP toolset if configured."""
    project_id = os.getenv("GOOGLE_CLOUD_PROJECT", "").strip()
    maps_key = _resolve_maps_key()

    if not project_id or not maps_key:
        return []

    # Map the MCP server location on Google Cloud
    mcp_server_name = f"projects/{project_id}/locations/global/mcpServers/google-mapstools.googleapis.com-mcp"
    
    # Initialize the custom API registry that supports header injection
    api_registry = MapsApiRegistry(
        api_registry_project_id=project_id,
        header_provider=header_provider,
    )
    return [api_registry.get_toolset(mcp_server_name=mcp_server_name)]

Dengan menambahkan set alat MCP, agen akan otomatis mendapatkan kemampuan untuk mengkueri Google Maps terkait perutean, elevasi, dan detail lokasi.

7. Menjalankan agen secara lokal

Setelah agen, perintah, dan alat terhubung, jalankan agen secara lokal. Kali ini, Anda akan menggunakan adk web sehingga Anda dapat melihat peristiwa Pemuatan Keterampilan dan Panggilan Alat.

uv run adk web

Anda akan melihat sesuatu yang serupa

INFO:     Started server process [99665]
INFO:     Waiting for application startup.

+-----------------------------------------------------------------------------+
| ADK Web Server started                                                      |
|                                                                             |
| For local testing, access at http://127.0.0.1:8000.                         |
+-----------------------------------------------------------------------------+

INFO:     Application startup complete.
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
  1. Buka browser Anda, lalu buka URL yang ditampilkan di terminal (biasanya http://localhost:8000).
  2. Di drop-down kiri atas, pilih planner_agent.
  3. Di jendela percakapan, kirim perintah berikut:
Plan a marathon for 10000 participants in Las Vegas on April 24, 2027 in the
evening timeframe

Anda akan melihat keterampilan dimuat dan alat dipanggil. Setelah beberapa saat, agen akan membuat rencana maraton.

UI Anda akan terlihat seperti ini:

UI Web ADK

8. Men-deploy agen

Setelah puas dengan performa agen secara lokal, Anda dapat men-deploy-nya ke Agent Engine, yang menghosting agen di Cloud Run secara aman.

Untuk men-deploy agen, gunakan perintah deployment ADK CLI:

uv run adk deploy agent_engine \
  --env_file planner_agent/.env \
  planner_agent

Setelah deployment selesai, CLI akan menghasilkan endpoint yang dihosting dengan aman untuk agen Anda. Sekarang Anda dapat mengintegrasikan endpoint ini ke dalam aplikasi frontend, chatbot, atau sistem backend lainnya. Anda juga dapat menggunakan Agent Runtime Playground untuk menguji agen.

Outputnya akan terlihat seperti berikut:

Files and dependencies resolved
Deploying to agent engine...
✅ Created agent engine: projects/<PROJECT_ID>/locations/us-west1/reasoningEngines/<AGENT_ID>

Anda dapat menggunakan skrip Python yang disediakan untuk berkomunikasi dengan agen.

  1. Salin file lingkungan contoh:
cp sample.env .env
  1. Buka .env dan perbarui kolom GOOGLE_CLOUD_PROJECT dengan ID Project Google Cloud Anda yang sebenarnya.

File tersebut akan terlihat seperti berikut:

GOOGLE_CLOUD_PROJECT=<YOUR_PROJECT_ID>
GOOGLE_CLOUD_LOCATION=us-west1
  1. Anda dapat mencantumkan agen dalam project Anda.
python main.py list

Anda akan melihat sesuatu yang serupa

Listing deployed agents...

ID: <AGENT_ID> | Display Name: planner_agent

Setelah memiliki ID Agen yang di-deploy, Anda dapat mengirim perintah:

export AGENT_ID=<AGENT_ID>

python main.py prompt --agent-id ${AGENT_ID} --message "Plan a marathon for
10000 participants in Las Vegas on April 24, 2027 in the evening timeframe"

Anda akan mendapatkan output yang terlihat seperti berikut:

Streaming response from agent <AGENT_ID>:

{'model_version': 'gemini-3-flash-preview', 'content': {'parts': [{'text': 'Here is a comprehensive
...
...
...

9. Pembersihan

Untuk menghindari biaya berkelanjutan pada akun Google Cloud Anda, hapus resource yang dibuat selama codelab ini.

Hapus layanan Cloud Run yang dibuat oleh deployment:

python main.py delete --agent-id ${AGENT_ID}

Jika Anda menyimpan kunci Maps API di Secret Manager, hapus secret:

gcloud secrets delete maps-api-key --project=$PROJECT_ID

Jika Anda membuat project Google Cloud baru untuk codelab ini, Anda dapat menghapus seluruh project untuk menghapus semua resource dan API yang terkait dengannya:

gcloud projects delete $PROJECT_ID

10. Selamat

Selamat! Anda telah membangun Agen Perencana Maraton yang canggih menggunakan ADK.

Yang telah Anda pelajari

  • Menginisialisasi project Agent Development Kit (ADK)
  • Memanfaatkan PromptBuilder untuk perintah sistem modular
  • Mengintegrasikan kemampuan pemetaan menggunakan alat MCP dan ApiRegistry
  • Memuat keterampilan secara kondisional menggunakan SkillToolset
  • Menguji secara lokal dan men-deploy ke Agent Engine

Dokumen referensi