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 di Menyiapkan lingkungan Anda.
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 menjalankan di lingkungan interaktif, seperti terminal atau
notebook Colab, Anda dapat menjalankan kueri menggunakan
AdkApp.async_stream_query
metode 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.
Misalnya,
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 sepenuhnya dan jelas menjelaskan parameter fungsi, fungsi yang dilakukan, dan fungsi yang ditampilkan. Informasi ini digunakan oleh model untuk menentukan fungsi 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 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 bagian 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 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. Misalnya, 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
Jika ingin mengganti layanan sesi terkelola default dengan database Anda sendiri, Anda dapat menentukan
session_service_builder fungsi
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
AdkApp.async_create_session
metode:
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
AdkApp.async_list_sessions
metode:
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. Misalnya,
user-123.SESSION_ID adalah ID untuk sesi tertentu yang ingin Anda ambil.
Untuk membuat kueri 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 memori
Secara default, AdkApp
menggunakan implementasi memori agentic 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. Contoh agen berikut selalu mengambil memori pada 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
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
Uji agen ADK Anda dengan memori:
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 "What is your preferred temperature?" 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 merespons dengan respons seperti "Setting the temperature to 71 degrees Fahrenheit. Temperature successfully changed." Respons agen dapat bervariasi bergantung pada model yang Anda gunakan.
Buat memori 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)Uji apakah agen telah menyimpan 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 akan merespons seperti "setting temperature to 71 degrees. Is that correct?" Respons agen dapat bervariasi bergantung pada model dan penyedia layanan memori yang Anda gunakan.
Gunakan metode
async_search_memoryuntuk menampilkan memori agen:response = await app.async_search_memory( user_id="USER_ID", query="Fix the temperature!", ) print(response)
Langkah berikutnya
Men-deploy agen
Pelajari lima cara men-deploy agen di Agent Platform Runtime berdasarkan kebutuhan pengembangan Anda.
Ringkasan sesi
Pelajari cara menggunakan sesi untuk mempertahankan status percakapan dengan agen Anda.
Ringkasan Memory Bank
Pelajari cara menggunakan Memory Bank untuk menyimpan preferensi dan fakta pengguna jangka panjang.
Menggunakan agen Agent Development Kit
Gunakan agen Agent Development Kit (ADK) dengan Agent Platform Runtime.
Mengevaluasi agen Anda
Buat dan deploy agen dasar, lalu gunakan layanan evaluasi AI Generatif untuk mengevaluasi agen
Memecahkan masalah pembuatan agen
Pelajari cara mengatasi error umum saat membuat agen kustom.