Halaman ini menjelaskan cara menghubungkan agen Agent Development Kit (ADK) dengan Sesi Platform Agen dan menggunakan sesi terkelola di lingkungan lokal dan produksi.
Sebelum memulai
Petunjuk ini menggunakan struktur file project dasar berikut untuk menentukan agen ADK serta kode runner dan deployment pendukungnya:
my_agent/
agent.py # main agent code
runner.py # code for interacting with the agent
deploy.py # code for deploying the agent to Google Cloud
Pastikan lingkungan Anda disiapkan dengan mengikuti langkah-langkah Mendapatkan peran yang diperlukan dan Autentikasi di Menyiapkan lingkungan Anda.
Menetapkan variabel lingkungan
Untuk menggunakan ADK, tetapkan variabel lingkungan Anda:
import os
os.environ["GOOGLE_GENAI_USE_ENTERPRISE"] = "TRUE"
os.environ["GOOGLE_CLOUD_PROJECT"] = "PROJECT_ID"
os.environ["GOOGLE_CLOUD_LOCATION"] = "LOCATION"
Ganti kode berikut:
- PROJECT_ID: Project ID Anda.
- LOCATION: Region Anda. Lihat wilayah yang didukung untuk Sesi.
Membuat instance Agent Runtime
Untuk mengakses Sesi Agent Platform, Anda harus menggunakan instance Agent Runtime terlebih dahulu. Anda tidak perlu men-deploy kode apa pun untuk mulai menggunakan Sesi. Jika Anda pernah menggunakan Agent Runtime sebelumnya, pembuatan instance Agent Runtime hanya memerlukan beberapa detik tanpa deployment kode. Proses ini mungkin memerlukan waktu lebih lama jika ini adalah pertama kalinya Anda menggunakan Agent Runtime.
Project Google Cloud
import agentplatform
client = agentplatform.Client(
project="PROJECT_ID",
location="LOCATION"
)
# If you don't have an Agent Runtime instance already, create an instance.
remote_agent = client.runtimes.create(
config={
"display_name": "My Session Store",
}
)
# Print the runtime ID, you will need it in the later steps to initialize
# the ADK `VertexAiSessionService`.
print(remote_agent.api_resource.name.split("/")[-1])
Ganti kode berikut:
PROJECT_ID: Project ID Anda.
LOCATION: Region Anda. Lihat wilayah yang didukung untuk Sesi.
Mengembangkan agen ADK Anda
Untuk membuat agen ADK, ikuti petunjuk di Agent Development Kit, atau gunakan kode berikut untuk membuat agen yang menyapa pengguna dengan ucapan tetap. Simpan kode ini dalam file bernama agent.py.
# file: my_agent/agent.py
from google import adk
def greetings(query: str):
"""Tool to greet user."""
if 'hello' in query.lower():
return {"greeting": "Hello, world"}
else:
return {"greeting": "Goodbye, world"}
# Define an ADK agent
root_agent = adk.Agent(
model="gemini-2.0-flash",
name='my_agent',
instruction="You are an Agent that greet users, always use greetings tool to respond.",
tools=[greetings]
)
Menyiapkan runner ADK
ADK Runtime mengatur eksekusi agen, alat, dan callback Anda, serta mengatur panggilan untuk membaca dan menulis sesi. Lakukan inisialisasi Runner dengan VertexAiSessionService, yang terhubung dengan Sesi Agent Platform. Simpan kode ini dalam file bernama runner.py.
Project Google Cloud
# file: my_agent/runner.py
import agent # Import from your agent.py
from google.adk import Runner
from google.adk.sessions import VertexAiSessionService
from google.genai import types
app_name="APP_NAME"
user_id="USER_ID"
# Create the ADK runner with VertexAiSessionService
session_service = VertexAiSessionService(
project="PROJECT_ID",
location="LOCATION",
agent_engine_id="AGENT_ENGINE_ID"
)
runner = Runner(
agent=agent.root_agent,
app_name=app_name,
session_service=session_service)
# Helper method to send query to the runner
async def call_agent(query, session_id, user_id):
content = types.Content(role='user', parts=[types.Part(text=query)])
async for event in runner.run_async(
user_id=user_id, session_id=session_id, new_message=content):
if event.is_final_response():
final_response = event.content.parts[0].text
print("Agent Response: ", final_response)
Ganti kode berikut:
APP_NAME: Nama aplikasi agen Anda.
USER_ID: Pilih ID pengguna Anda sendiri dengan batas karakter 128. Contoh,
user-123.AGENT_ENGINE_ID: ID resource instance Agent Runtime.
Untuk agen yang di-deploy, ID resource dicantumkan sebagai variabel lingkungan
GOOGLE_CLOUD_AGENT_ENGINE_IDUntuk agen lokal, Anda dapat mengambil ID resource menggunakan
remote_agent.api_resource.name.split("/")[-1].
Berinteraksi dengan agen Anda
Setelah menentukan agen dan menyiapkan Sesi Agent Platform, Anda dapat berinteraksi dengan agen untuk memeriksa apakah histori dan status sesi tetap ada.
UI ADK
Untuk menguji agen Anda dengan antarmuka pengguna ADK dan terhubung ke Sesi Agent Platform, jalankan perintah adk web di terminal Anda.
Meskipun adk web biasanya membaca variabel lingkungan dari file .env, akan mengabaikan file ini saat Anda menggunakan
flag --session_service_uri. Sebagai gantinya, Anda harus menetapkan variabel lingkungan GOOGLE_CLOUD_PROJECT dan GOOGLE_CLOUD_LOCATION di sesi terminal sebelum menjalankan perintah.
export GOOGLE_CLOUD_PROJECT="PROJECT_ID"export GOOGLE_CLOUD_LOCATION="LOCATION"adk web --session_service_uri=agentengine://AGENT_ENGINE_ID
# Sample output
+-----------------------------------------------------------------------------+
| ADK Web Server started |
| |
| For local testing, access at http://localhost:8000. |
+-----------------------------------------------------------------------------+
INFO: Application startup complete.
INFO: Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)

Python
Gunakan kode Python ADK untuk mengelola sesi dan status. Tambahkan kode berikut ke akhir file runner.py Anda untuk berinteraksi dengan agen.
Cuplikan berikut berisi panggilan await tingkat teratas agar lebih ringkas. Untuk menjalankan kode ini sebagai skrip Python, tempatkan cuplikan di dalam fungsi async dan gunakan asyncio.run() untuk mengeksekusinya, seperti yang ditunjukkan dalam contoh ini:
import asyncio
async def main():
# Place one or more snippets here.
# For example:
session = await session_service.create_session(
app_name=app_name,
user_id=user_id)
await call_agent("Hello!", session.id, user_id)
asyncio.run(main())
Membuat sesi dan mengkueri agen
Gunakan kode berikut untuk membuat sesi dan mengirim kueri ke agen Anda. Tentukan ID sesi kustom untuk mengatur sesi menggunakan skema penamaan Anda sendiri atau untuk beralih dengan cepat dari layanan lain. Jika Anda tidak menentukan ID sesi, Agent Platform akan otomatis membuatnya.
# file: my_agent/runner.py
# Create a session
session = await session_service.create_session(
app_name=app_name,
user_id=user_id,
session_id=session_id)
await call_agent("Hello!", session.id, user_id)
# Agent response: "Hello, world"
await call_agent("Thanks!", session.id, user_id)
# Agent response: "Goodbye, world"
Untuk ID sesi kustom, pertimbangkan batasan berikut untuk mencegah konflik dengan ID yang dibuat sistem:
- Jika karakter pertama adalah huruf, ID dapat berisi hingga 63 karakter. Karakter yang valid adalah huruf kecil, angka, dan tanda hubung
(
[a-z0-9-]). Karakter terakhir harus berupa huruf atau angka. - Jika karakter pertama adalah angka, ID dapat memiliki panjang hingga 9 karakter. Karakter yang valid adalah angka (
[0-9]) tanpa angka nol di depannya.
Setelah sesi dibuat dan diteruskan ke runner, ADK menggunakan sesi untuk menyimpan peristiwa dari interaksi saat ini. Anda juga dapat melanjutkan sesi sebelumnya dengan memberikan ID untuk sesi tersebut.
Mengonfigurasi time to live (TTL) sesi
Semua sesi harus memiliki waktu habis masa berlaku. Anda dapat menentukan waktu habis masa berlaku ini saat membuat atau memperbarui sesi. Sesi dan peristiwa turunannya akan otomatis dihapus setelah waktu habis masa berlaku berlalu. Anda dapat menyetel waktu habis masa berlaku (expire_time) secara langsung atau menyetel waktu aktif (ttl) dalam detik. Jika tidak ada yang ditentukan, sistem akan menerapkan TTL default 365 hari.
Time to live (TTL)
Jika Anda menetapkan time to live (TTL), server akan menghitung waktu habis masa berlaku sebagai create_time + ttl untuk sesi yang baru dibuat atau update_time + ttl untuk sesi yang diperbarui.
session = await session_service.create_session(
app_name=app_name,
user_id=user_id,
# Session will be deleted 10 days after creation time.
ttl=f"{24 * 60 * 60 * 10}s"
)
```
Waktu habis masa berlaku
import datetime
expire_time = datetime.datetime.now(
tz=datetime.timezone.utc) + datetime.timedelta(seconds=24 * 60 * 60 * 10)
session = await session_service.create_session(
app_name=app_name,
user_id=user_id,
# Session will be deleted at the provided time (10 days after current time).
expire_time=expire_time.isoformat()
)
Mencantumkan sesi yang ada
Mencantumkan semua sesi yang ada yang terkait dengan ID pengguna tertentu.
# List sessions
sessions = await session_service.list_sessions(app_name=app_name,user_id=user_id)
print(sessions)
# ListSessionsResponse(session_ids=['1122334455', '9988776655'])
Mengelola status sesi
Status menyimpan informasi yang dibutuhkan agen untuk percakapan. Anda dapat memberikan status awal sebagai kamus saat membuat sesi:
# Create a session with state
session = await session_service.create_session(
app_name=app_name,
user_id=user_id,
state={'key': 'value'})
print(session.state['key'])
# value
Untuk memperbarui status sesi di luar runner, tambahkan peristiwa baru ke sesi menggunakan state_delta:
# file: my_agent/runner.py
from google.adk.events import Event, EventActions
import time
# Define state changes
state_changes = {'key': 'new_value'}
# Create event with actions
actions_with_update = EventActions(state_delta=state_changes)
system_event = Event(
invocation_id="invocation_id",
author="system", # Or 'agent', 'tool' etc.
actions=actions_with_update,
timestamp=time.time()
)
# Append the event
await session_service.append_event(session, system_event)
# Check updated state
updated_session = await session_service.get_session(
app_name=app_name,
user_id=user_id,
session_id=session.id)
# State is updated to new value
print(updated_session.state['key'])
# new_value
Kolom kustom untuk acara
ADK mendukung skema peristiwa yang fleksibel sehingga Anda dapat menyertakan data arbitrer dalam peristiwa sesi. Hal ini berguna untuk interoperabilitas dengan framework agen lain atau untuk menyimpan data peristiwa kustom.
Saat Anda menambahkan peristiwa dengan kolom kustom, ADK akan melakukan serialisasi data peristiwa
ke dalam kolom raw_event dari peristiwa sesi yang disimpan.
# Create an event with custom fields
custom_event = Event(
invocation_id="invocation_id",
author="user",
timestamp=time.time(),
custom_field="custom_value",
another_field={"nested_key": "nested_value"}
)
# Append the event
await session_service.append_event(session, custom_event)
Saat Anda mengambil sesi, peristiwa yang diambil akan mempertahankan kolom kustom ini.
Menghapus sesi
Menghapus sesi tertentu yang terkait dengan ID pengguna:
await session_service.delete_session(app_name=app_name, user_id=user_id, session_id=session.id)
Men-deploy agen Anda ke Agent Platform
Setelah menguji agen secara lokal, Anda dapat men-deploy agen ke produksi dengan memperbarui instance Agent Platform menggunakan parameter:
Project Google Cloud
client.runtimes.update(
resource_name=remote_agent.api_resource.name,
agent=AGENT,
config={
"display_name": DISPLAY_NAME, # Optional.
"requirements": REQUIREMENTS, # Optional.
"staging_bucket": STAGING_BUCKET, # Required.
},
)
Ganti kode berikut:
AGENT: Aplikasi yang menerapkan metode
query / stream_query(misalnya,AdkAppuntuk agen ADK).DISPLAY_NAME: Nama yang mudah digunakan untuk agen Anda.
REQUIREMENTS: Daftar paket pip yang diperlukan oleh agen Anda. Contoh,
["google-cloud-storage", "google-cloud-agentplatform[runtimes,adk]"].STAGING_BUCKET: Bucket Cloud Storage yang diawali dengan
gs://.
Pembersihan
Untuk menghapus semua resource yang digunakan dalam project ini, Anda dapat menghapus instance Agent Runtime beserta resource turunannya:
remote_agent.delete(force=True)