Mengembangkan agen ADK

Agent Runtime memungkinkan Anda mengembangkan dan men-deploy agen menggunakan template Agent Development Kit (ADK). Dengan menggunakan class AdkApp di Agent Platform SDK untuk Python, Anda dapat membuat agen yang menampilkan nilai tukar dan mengelola interaksi stateful.

Dokumen ini menjelaskan cara mengembangkan agen ADK, termasuk menentukan model, menambahkan alat, serta mengelola sesi dan memori.

Untuk mengetahui informasi selengkapnya tentang cara mengelola agen yang di-deploy, lihat Mengelola agen yang di-deploy.

Sebelum memulai

Pastikan lingkungan Anda disiapkan dengan mengikuti langkah-langkah dalam Menyiapkan lingkungan.

Menentukan dan mengonfigurasi model

Tentukan model yang ingin Anda gunakan:

model = "gemini-2.0-flash"

Opsional: Konfigurasikan setelan keamanan model. Untuk mempelajari lebih lanjut opsi yang tersedia untuk setelan keamanan di Gemini, lihat Mengonfigurasi atribut keamanan. Berikut adalah contoh cara mengonfigurasi setelan keamanan:

from google.genai import types

safety_settings = [
    types.SafetySetting(
        category=types.HarmCategory.HARM_CATEGORY_DANGEROUS_CONTENT,
        threshold=types.HarmBlockThreshold.OFF,
    ),
]

Opsional: Tentukan parameter pembuatan konten:

from google.genai import types

generate_content_config = types.GenerateContentConfig(
   safety_settings=safety_settings,
   temperature=0.28,
   max_output_tokens=1000,
   top_p=0.95,
)

Buat AdkApp menggunakan konfigurasi model:

from google.adk.agents import Agent
from vertexai.agent_engines import AdkApp

agent = Agent(
   model=model,                                      # Required.
   name='currency_exchange_agent',                   # Required.
   generate_content_config=generate_content_config,  # Optional.
)
app = AdkApp(agent=agent)

Jika Anda menjalankan di lingkungan interaktif, seperti terminal atau notebook Colab, Anda dapat menjalankan kueri menggunakan metode AdkApp.async_stream_query sebagai langkah pengujian perantara:

async for event in app.async_stream_query(
   user_id="USER_ID",  # Required
   message="What is the exchange rate from US dollars to Swedish currency?",
):
   print(event)

• USER_ID: Pilih ID pengguna Anda sendiri dengan batas karakter 128. Contoh, user-123.

Responsnya adalah kamus Python yang mirip dengan contoh berikut:

{'actions': {'artifact_delta': {},
             'requested_auth_configs': {},
             'state_delta': {}},
 'author': 'currency_exchange_agent',
 'content': {'parts': [{'text': 'To provide you with the most accurate '
                                'exchange rate, I need to know the specific '
                                'currencies you\'re asking about. "Swedish '
                                'currency" could refer to:\n'
                                '\n'
                                '*   **Swedish Krona (SEK):** This is the '
                                'official currency of Sweden.\n'
                                '\n'
                                "Please confirm if you're interested in the "
                                'exchange rate between USD and SEK. Once you '
                                'confirm, I can fetch the latest exchange rate '
                                'for you.\n'}],
             'role': 'model'},
 'id': 'LYg7wg8G',
 'invocation_id': 'e-113ca547-0f19-4d50-9dde-f76cbc001dce',
 'timestamp': 1744166956.925927}

Opsional: Menentukan dan menggunakan alat

Setelah menentukan model, tentukan alat yang digunakan model Anda untuk penalaran.

Saat menentukan fungsi, penting untuk menyertakan komentar yang menjelaskan parameter fungsi, fungsi yang dijalankan, dan nilai yang ditampilkan fungsi secara lengkap dan jelas. Informasi ini digunakan oleh model untuk menentukan fungsi yang akan digunakan. Anda juga harus menguji fungsi secara lokal untuk memastikan bahwa fungsi tersebut berfungsi.

Gunakan kode berikut untuk menentukan fungsi yang menampilkan nilai tukar:

def get_exchange_rate(
    currency_from: str = "USD",
    currency_to: str = "EUR",
    currency_date: str = "latest",
):
    """Retrieves the exchange rate between two currencies on a specified date.

    Uses the Frankfurter API (https://api.frankfurter.app/) to obtain
    exchange rate data.

    Args:
        currency_from: The base currency (3-letter currency code).
            Defaults to "USD" (US Dollar).
        currency_to: The target currency (3-letter currency code).
            Defaults to "EUR" (Euro).
        currency_date: The date for which to retrieve the exchange rate.
            Defaults to "latest" for the most recent exchange rate data.
            Can be specified in YYYY-MM-DD format for historical rates.

    Returns:
        dict: A dictionary containing the exchange rate information.
            Example: {"amount": 1.0, "base": "USD", "date": "2023-11-24",
                "rates": {"EUR": 0.95534}}
    """
    import requests
    response = requests.get(
        f"https://api.frankfurter.app/{currency_date}",
        params={"from": currency_from, "to": currency_to},
    )
    return response.json()

Untuk menguji fungsi sebelum menggunakannya di agen, jalankan perintah berikut:

get_exchange_rate(currency_from="USD", currency_to="SEK")

Responsnya akan terlihat seperti berikut:

{'amount': 1.0, 'base': 'USD', 'date': '2025-04-03', 'rates': {'SEK': 9.6607}}

Untuk menggunakan alat di dalam AdkApp, tambahkan alat tersebut ke daftar alat di argumen tools=:

from google.adk.agents import Agent

agent = Agent(
    model=model,                     # Required.
    name='currency_exchange_agent',  # Required.
    tools=[get_exchange_rate],       # Optional.
)

Anda dapat menguji agen secara lokal dengan menjalankan kueri pengujian terhadap agen tersebut menggunakan metode AdkApp.async_stream_query. Jalankan perintah berikut untuk menguji agen secara lokal menggunakan dolar AS dan Krona Swedia:

from vertexai.agent_engines import AdkApp

app = AdkApp(agent=agent)
async for event in app.async_stream_query(
    user_id="USER_ID",
    message="What is the exchange rate from US dollars to SEK on 2025-04-03?",
):
    print(event)

dengan USER_ID sebagai ID pengguna yang Anda tentukan. Contoh, user-123.

Responsnya adalah urutan kamus yang mirip dengan berikut ini:

{'author': 'currency_exchange_agent',
 'content': {'parts': [{'function_call': {'args': {'currency_date': '2025-04-03',
                                                   'currency_from': 'USD',
                                                   'currency_to': 'SEK'},
                                          'id': 'adk-e39f3ba2-fa8c-4169-a63a-8e4c62b89818',
                                          'name': 'get_exchange_rate'}}],
             'role': 'model'},
 'id': 'zFyIaaif',
 # ...
}
{'author': 'currency_exchange_agent',
 'content': {'parts': [{'function_response': {'id': 'adk-e39f3ba2-fa8c-4169-a63a-8e4c62b89818',
                                              'name': 'get_exchange_rate',
                                              'response': {'amount': 1.0,
                                                           'base': 'USD',
                                                           'date': '2025-04-03',
                                                           'rates': {'SEK': 9.6607}}}}],
             'role': 'user'},
 'id': 'u2YR4Uom',
 # ...
}
{'author': 'currency_exchange_agent',
 'content': {'parts': [{'text': 'The exchange rate from USD to SEK on '
                                '2025-04-03 is 9.6607.'}],
             'role': 'model'},
 'id': 'q3jWA3wl',
 # ...
}

Opsional: Mengelola sesi

AdkApp menggunakan sesi dalam memori saat berjalan secara lokal dan menggunakan sesi terkelola berbasis cloud setelah Anda men-deploy agen ke Agent Runtime. Bagian ini menjelaskan cara mengonfigurasi agen ADK untuk bekerja dengan sesi terkelola.

Opsional: Menyesuaikan database sesi Anda

Catatan: Jika Anda menggunakan layanan sesi dalam memori kustom, sesi mungkin tidak tetap sinkron saat Anda men-deploy agen ke Agent Runtime. Sebaiknya sesuaikan database hanya jika Anda dapat menyinkronkan status di seluruh sesi dalam lingkungan yang di-deploy.

Jika ingin mengganti layanan sesi terkelola default dengan database Anda sendiri, Anda dapat menentukan fungsi session_service_builder sebagai berikut:

def session_service_builder():
  from google.adk.sessions import InMemorySessionService

  return InMemorySessionService()

Teruskan database Anda ke AdkApp sebagai session_service_builder=:

from vertexai.agent_engines import AdkApp

app = AdkApp(
   agent=agent,                                      # Required.
   session_service_builder=session_service_builder,  # Optional.
)

Menggunakan agen dengan sesi

Saat Anda menjalankan AdkApp secara lokal, petunjuk berikut menggunakan sesi dalam memori.

Untuk membuat sesi bagi agen Anda, gunakan metode AdkApp.async_create_session:

session = await app.async_create_session(user_id="USER_ID")
print(session)

Sesi dibuat sebagai representasi kamus dari objek sesi ADK.

Untuk mencantumkan sesi yang terkait dengan agen Anda, gunakan metode AdkApp.async_list_sessions:

await app.async_list_sessions(user_id="USER_ID")

Untuk mendapatkan sesi tertentu, gunakan metode AdkApp.async_get_session::

session = await app.async_get_session(user_id="USER_ID", session_id="SESSION_ID")

di mana

• USER_ID adalah ID pengguna yang Anda tentukan. Contoh, user-123.

• SESSION_ID adalah ID untuk sesi tertentu yang ingin Anda ambil.

Untuk mengkueri agen secara asinkron, gunakan metode AdkApp.async_stream_query:

async for event in app.async_stream_query(
    user_id="USER_ID",
    session_id=SESSION_ID, # Optional. you can pass in the session_id when querying the agent
    message="What is the exchange rate from US dollars to Swedish currency on 2025-04-03?",
):
    print(event)

Agen mungkin merespons dengan permintaan informasi seperti berikut:

{'author': 'currency_exchange_agent',
 'content': {'parts': [{'text': 'I need to know the Swedish currency code to '
                                'provide you with the exchange rate.'}],
             'role': 'model'},
 'id': 'wIgZAtQ4',
 #...
}

Anda dapat mengirim respons (misalnya, "SEK") atas nama USER_ID dalam sesi yang sesuai dengan session dengan menentukan:

async for event in app.async_stream_query(
    user_id="USER_ID",
    session_id=session.id, # Optional. you can pass in the session_id when querying the agent
    message="SEK",
):
    print(event)

Anda akan menerima kelanjutan percakapan seperti urutan kamus berikut:

{'author': 'currency_exchange_agent',
 'content': {'parts': [{'function_call': {'args': {'currency_date': '2025-04-03',
                                                   'currency_from': 'USD',
                                                   'currency_to': 'SEK'},
                                          'id': 'adk-2b9230a6-4b92-4a1b-9a65-b708ff6c68b6',
                                          'name': 'get_exchange_rate'}}],
             'role': 'model'},
 'id': 'bOPHtzji',
 # ...
}
{'author': 'currency_exchange_agent',
 'content': {'parts': [{'function_response': {'id': 'adk-2b9230a6-4b92-4a1b-9a65-b708ff6c68b6',
                                              'name': 'get_exchange_rate',
                                              'response': {'amount': 1.0,
                                                           'base': 'USD',
                                                           'date': '2025-04-03',
                                                           'rates': {'SEK': 9.6607}}}}],
             'role': 'user'},
 'id': '9AoDFmiL',
 # ...
}
{'author': 'currency_exchange_agent',
 'content': {'parts': [{'text': 'The exchange rate from USD to SEK on '
                                '2025-04-03 is 1 USD to 9.6607 SEK.'}],
             'role': 'model'},
 'id': 'hmle7trT',
 # ...
}

Opsional: Mengelola kenangan

Secara default, AdkApp menggunakan implementasi dalam memori dari memori agentic saat berjalan secara lokal dan menggunakan Agent Platform Memory Bank setelah Anda men-deploy agen ke Agent Runtime.

Saat mengembangkan agen ADK, Anda dapat menyertakan PreloadMemoryTool yang mengontrol kapan agen mengambil memori dan bagaimana memori disertakan dalam perintah. Contoh agen berikut selalu mengambil memori di awal setiap giliran dan menyertakan memori dalam petunjuk sistem:

from google.adk.agents import Agent
from google.adk.tools.preload_memory_tool import PreloadMemoryTool
from vertexai.agent_engines import AdkApp

agent = Agent(
    model="gemini-2.0-flash",
    name='stateful_agent',
    instruction="""You are a Vehicle Voice Agent, designed to assist users with information and in-vehicle actions.

1.  **Direct Action:** If a user requests a specific vehicle function (e.g., "turn on the AC"), execute it immediately using the corresponding tool. You don't have the outcome of the actual tool execution, so provide a hypothetical tool execution outcome.
2.  **Information Retrieval:** Respond concisely to general information requests with your own knowledge (e.g., restaurant recommendation).
3.  **Clarity:** When necessary, try to seek clarification to better understand the user's needs and preference before taking an action.
4.  **Brevity:** Limit responses to under 30 words.
""",
    tools=[PreloadMemoryTool()],
)

app = AdkApp(agent=agent)

Opsional: Menyesuaikan layanan memori Anda

Catatan: Jika Anda menggunakan layanan memori dalam memori kustom, memori mungkin tidak tetap sinkron saat Anda men-deploy agen ke Agent Runtime. Sebaiknya sesuaikan layanan memori hanya jika Anda dapat menyinkronkan memori di seluruh instance dalam setelan terdistribusi saat agen di-deploy.

Jika ingin mengganti layanan memori default, Anda dapat menentukan fungsi memory_service_builder yang menampilkan BaseMemoryService seperti berikut:

def memory_service_builder():
  from google.adk.memory import InMemoryMemoryService

  return InMemoryMemoryService()

Teruskan database Anda ke AdkApp sebagai memory_service_builder=:

from vertexai.agent_engines import AdkApp

app = AdkApp(
   agent=agent,                                    # Required.
   memory_service_builder=memory_service_builder,  # Optional.
)

Menggunakan agen dengan memori

Uji agen ADK Anda dengan memori:

1. Buat sesi dan berinteraksi dengan agen:

   initial_session = await app.async_create_session(user_id="USER_ID")
   
   async for event in app.async_stream_query(
       user_id="USER_ID",
       session_id=initial_session.id,
       message="Can you update the temperature to my preferred temperature?",
   ):
       print(event)
   

   Karena tidak ada memori yang tersedia selama sesi pertama dan agen tidak mengetahui preferensi pengguna, agen dapat membalas dengan respons seperti "Berapa suhu yang Anda inginkan?" Anda dapat merespons dengan perintah berikut:

   async for event in app.async_stream_query(
       user_id="USER_ID",
       session_id=initial_session.id,
       message="I like it at 71 degrees",
   ):
       print(event)
   

   Agen mungkin akan memberikan respons seperti "Menyetel suhu ke 71 derajat Fahrenheit. Suhu berhasil diubah." Respons agen dapat bervariasi bergantung pada model yang Anda gunakan.

2. Buat kenangan dari sesi. Untuk menyimpan informasi dari sesi agar dapat digunakan dalam sesi mendatang, gunakan metode async_add_session_to_memory:

   await app.async_add_session_to_memory(session=initial_session)
   

3. Uji apakah agen telah mempertahankan memori sesi (menggunakan PreloadMemoryTool) dengan membuat sesi baru dan memberikan perintah kepada agen:

   new_session = await app.async_create_session(user_id="USER_ID")
   async for event in app.async_stream_query(
       user_id="USER_ID",
       session_id=initial_session.id,
       message="Fix the temperature!",
   ):
       print(event)
   

   Agen mungkin menampilkan respons seperti "menyetel suhu ke 71 derajat. Apakah itu benar?" Respons agen dapat bervariasi bergantung pada model dan penyedia layanan memori yang Anda gunakan.

4. Gunakan metode async_search_memory untuk menampilkan memori agen:

   response = await app.async_search_memory(
       user_id="USER_ID",
       query="Fix the temperature!",
   )
   print(response)
   

Langkah berikutnya

Panduan

Men-deploy agen

Pelajari lima cara untuk men-deploy agen di Agent Platform Runtime berdasarkan kebutuhan pengembangan Anda.

Ringkasan

Ringkasan sesi

Pelajari cara menggunakan sesi untuk mempertahankan status percakapan dengan agen Anda.

Ringkasan

Ringkasan Memory Bank

Pelajari cara menggunakan Memory Bank untuk menyimpan preferensi dan fakta pengguna jangka panjang.

Panduan

Menggunakan agen Agent Development Kit

Menggunakan agen Agent Development Kit (ADK) dengan Agent Platform Runtime.

Panduan

Mengevaluasi agen Anda

Membuat dan men-deploy agen dasar serta menggunakan layanan evaluasi AI generatif untuk mengevaluasi agen

Pemecahan masalah

Memecahkan masalah pembuatan agen

Pelajari cara mengatasi error umum saat membuat agen kustom.

Referensi

Dapatkan dukungan

Temukan referensi dan dukungan untuk Google Agent Platform.