Mengelola sesi dengan Agent Development Kit

Halaman ini menjelaskan cara menghubungkan agen Agent Development Kit (ADK) dengan Sesi Agent Platform dan menggunakan sesi terkelola di lingkungan lokal dan produksi.

Sebelum memulai

Petunjuk ini menggunakan struktur file project dasar berikut untuk menentukan agen ADK dan kode runner serta 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 Mendapatkan peran yang diperlukan dan Autentikasi langkah-langkah 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:

Membuat instance Vertex AI Agent Engine

Untuk mengakses Sesi Agent Platform, Anda harus menggunakan instance Vertex AI Agent Engine terlebih dahulu. Anda tidak perlu men-deploy kode apa pun untuk mulai menggunakan Sesi. Jika pernah menggunakan Agent Engine sebelumnya, pembuatan instance Vertex AI Agent Engine hanya memerlukan waktu beberapa detik tanpa deployment kode. Proses ini mungkin memerlukan waktu lebih lama jika Anda baru pertama kali menggunakan Agent Engine.

Project Google Cloud 

import vertexai

client = vertexai.Client(
  project="PROJECT_ID",
  location="LOCATION"
)

# If you don't have an Agent Engine instance already, create an instance.
agent_engine = client.agent_engines.create()

# Print the agent engine ID, you will need it in the later steps to initialize
# the ADK `VertexAiSessionService`.
print(agent_engine.api_resource.name.split("/")[-1])

Ganti kode berikut:

Mengembangkan agen ADK

Untuk membuat agen ADK, ikuti petunjuk di Agent Development Kit, atau gunakan kode berikut untuk membuat agen yang menyapa pengguna dengan sapaan 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

Runtime ADK mengatur eksekusi agen, alat, dan callback Anda, serta mengatur panggilan untuk membaca dan menulis sesi. 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. Misalnya, user-123.

  • AGENT_ENGINE_ID: ID resource instance Vertex AI Agent Engine.

  • Untuk agen yang di-deploy, ID resource tercantum sebagai variabel lingkungan GOOGLE_CLOUD_AGENT_ENGINE_ID

  • Untuk agen lokal, Anda dapat mengambil ID resource menggunakan agent_engine.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 dengan antarmuka pengguna ADK dan terhubung ke Sesi Agent Platform, jalankan perintah adk web di terminal.

Meskipun adk web biasanya membaca variabel lingkungan dari file .env, file ini akan diabaikan 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)

UI ADK

Python

Gunakan kode Python ADK untuk mengelola sesi dan status. Tambahkan kode berikut ke bagian akhir file runner.py untuk berinteraksi dengan agen.

Cuplikan berikut berisi panggilan await tingkat atas untuk ringkasnya. Untuk menjalankan kode ini sebagai skrip Python, tempatkan cuplikan di dalam fungsi async dan gunakan asyncio.run() untuk menjalankannya, 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 bertransisi 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 memiliki panjang 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 awal.

Setelah sesi dibuat dan diteruskan ke runner, ADK akan menggunakan sesi tersebut untuk menyimpan peristiwa dari interaksi saat ini. Anda juga dapat melanjutkan sesi sebelumnya dengan memberikan ID untuk sesi tersebut.

Mengonfigurasi waktu aktif sesi (TTL)

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 menetapkan waktu habis masa berlaku (expire_time) secara langsung atau menetapkan time to live (TTL) (ttl) dalam detik. Jika tidak ada yang ditentukan, sistem akan menerapkan TTL default selama 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 dan 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 diperlukan 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 peristiwa

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 membuat 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.agent_engines.update(
    resource_name=agent_engine.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, AdkApp untuk agen ADK). Untuk mengetahui informasi selengkapnya, lihat Pertimbangan deployment.

  • DISPLAY_NAME: Nama yang mudah dibaca pengguna untuk agen Anda.

  • REQUIREMENTS: Daftar paket pip yang diperlukan oleh agen Anda. Misalnya, ["google-cloud-storage", "google-cloud-aiplatform[agent_engines,adk]"].

  • STAGING_BUCKET: Bucket Cloud Storage yang diawali dengan gs://.

Pembersihan

Untuk membersihkan semua resource yang digunakan dalam project ini, Anda dapat menghapus instance Vertex AI Agent Engine beserta resource turunannya:

agent_engine.delete(force=True)

Langkah berikutnya