Mengembangkan agen Agent Development Kit

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 mengelola agen yang di-deploy, lihat Mengelola agen yang di-deploy.

Sebelum memulai

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

Menentukan dan mengonfigurasi model

Tentukan model yang ingin Anda gunakan:

model = "gemini-2.0-flash"

Opsional: Konfigurasi 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, Anda harus menyertakan komentar yang sepenuhnya dan jelas menjelaskan parameter fungsi, apa yang dilakukan fungsi, dan apa yang dikembalikan fungsi. Informasi ini digunakan oleh model untuk menentukan fungsi mana yang akan digunakan. Anda juga harus menguji fungsi secara lokal untuk mengonfirmasi 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 bawah 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 melakukan kueri pengujian terhadapnya 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 adalah 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 dijalankan secara lokal dan menggunakan sesi terkelola berbasis cloud setelah Anda men-deploy agen ke Agent Runtime. Bagian ini menjelaskan cara mengonfigurasi agen ADK agar berfungsi dengan sesi terkelola.

Opsional: Sesuaikan database sesi Anda

Catatan: Jika Anda menggunakan layanan sesi dalam memori kustom, sesi mungkin tidak tetap tersinkron saat Anda men-deploy agen ke Agent Runtime. Kami hanya merekomendasikan penyesuaian database 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 memori agentik dalam memori 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 cara memori disertakan dalam perintah. Agen contoh 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: Sesuaikan layanan memori Anda

Catatan: Jika Anda menggunakan layanan memori dalam memori kustom, memori mungkin tidak tetap tersinkron 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

Menguji 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 kenangan 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 dapat memberikan respons seperti "Menyetel suhu ke 71 derajat Fahrenheit. Suhu berhasil diubah." Respons agen dapat berbeda-beda, bergantung pada model yang Anda gunakan.

2. Buat kenangan dari sesi. Untuk menyimpan informasi dari sesi untuk 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 meminta 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 memberikan respons seperti "mengatur suhu ke 22 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 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

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

Resource

Mendapatkan dukungan

Temukan referensi dan dukungan untuk Google Agent Platform.