Mengembangkan agen Agent Development Kit

Halaman ini menunjukkan cara mengembangkan agen menggunakan template Agent Development Kit (class AdkApp di Vertex AI SDK untuk Python). Agen menampilkan nilai tukar antara dua mata uang pada tanggal tertentu.

Ikuti langkah-langkah berikut:

1. Menentukan dan mengonfigurasi model
2. (Opsional) Tentukan dan gunakan alat
3. (Opsional) Mengelola sesi
4. (Opsional) Mengelola kenangan

Sebelum memulai

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

Menentukan dan mengonfigurasi model

Tentukan versi model:

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

Saat menentukan fungsi, penting untuk 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 Anda menggunakannya di agen, jalankan perintah berikut:

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

Responsnya akan mirip dengan berikut ini:

{'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. 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 Vertex AI Agent Engine. Bagian ini menjelaskan cara mengonfigurasi agen ADK agar berfungsi dengan sesi terkelola.

(Opsional) Menyesuaikan database sesi

Catatan: Jika Anda menggunakan layanan sesi dalam memori kustom, sesi mungkin tidak tetap disinkronkan saat Anda men-deploy agen ke Vertex AI Agent Engine. 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:

Buat sesi untuk agen Anda:

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

Sesi dibuat sebagai representasi kamus dari objek sesi ADK.

Mencantumkan sesi yang terkait dengan agen Anda:

await app.async_list_sessions(user_id="USER_ID")

Mendapatkan sesi tertentu:

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.

Kueri AdkApp menggunakan sesi:

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 agen dalam memori saat berjalan secara lokal dan menggunakan Bank Memori Mesin Agen Vertex AI setelah Anda men-deploy agen ke Mesin Agen Vertex AI.

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 import adk
from vertexai.agent_engines import AdkApp

agent = adk.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=[adk.tools.preload_memory_tool.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 Vertex AI Agent Engine. Sebaiknya sesuaikan layanan memori hanya jika Anda dapat menyinkronkan kenangan 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 sebagai 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 mungkin merespons dengan "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 dapat 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

• Ringkasan sesi
• Ringkasan Memory Bank
• Gunakan agen Agent Development Kit.
• Mengevaluasi agen.
• Men-deploy agen.
• Memecahkan masalah pengembangan agen.
• Dapatkan dukungan.