Membuat aplikasi agen

Panduan ini akan memandu Anda melalui langkah-langkah untuk membuat aplikasi agen dasar yang dapat menjawab kueri pengguna tentang cuaca.

Sebelum memulai

Pastikan untuk menyelesaikan petunjuk penyiapan sebelum mengikuti panduan ini.

Membuat aplikasi agen

Buat aplikasi agen dan agen root:

  1. Buka konsol CX Agent Studio.
  2. Pilih project Anda.
  3. Klik Create agent atau New agent.
  4. Berikan "weather app" sebagai nama agen.
  5. Klik Create. Jika ini adalah aplikasi agen pertama yang Anda buat untuk project, pembuatan mungkin memerlukan waktu 1-2 menit. Agent builder akan ditampilkan dan agen root akan dibuat untuk Anda.

Membuat hierarki agen

Aplikasi agen ini akan menggunakan tiga agen:

  • Agen root untuk menyapa pengguna dan mendelegasikan ke sub-agen lainnya.
  • Agen cuaca untuk menjawab pertanyaan terkait cuaca.
  • Agen perpisahan untuk menyelesaikan percakapan.

Agen root sudah dibuat, tetapi Anda harus memperbarui setelan untuk agen ini:

  1. Klik kolom judul agen root.
  2. Anda dapat mengubah nama agen jika mau.
  3. Masukkan deskripsi: "Handles simple greetings and delegates to other agents".
  4. Klik Save, lalu tutup panel setelan.

Buat agen cuaca:

  1. Klik tombol + di bagian bawah agen root.
  2. Klik Add new sub-agent.
  3. Klik kolom judul agen baru.
  4. Ubah nama menjadi "Weather agent".
  5. Masukkan deskripsi: "Handles any weather related questions from the user".
  6. Klik Save, lalu tutup panel setelan.

Dengan cara yang sama, buat sub-agen lain dari agen root yang disebut "Farewell agent" dengan deskripsi "Handles user farewells and goodbyes".

screenshot hierarki agen

Membuat alat cuaca

Alat digunakan untuk menghubungkan agen Anda ke sistem eksternal atau kode inline yang disediakan untuk agen. Hal ini memungkinkan agen Anda berinteraksi dengan sistem lain untuk mengambil, memperbarui, memformat, atau menganalisis informasi.

Pada langkah ini, Anda akan membuat alat cuaca, yang digunakan untuk mengambil informasi cuaca. Untuk panduan ini, alat ini memiliki respons tiruan untuk pengguna. Dalam aplikasi cuaca yang sebenarnya, alat ini akan mengakses server eksternal untuk mendapatkan informasi.

Buat alat cuaca:

  1. Klik tombol alat di sisi kanan pembuat agen.
  2. Klik + untuk membuat alat baru bagi aplikasi agen.
  3. Klik Python code.

  4. Tempelkan kode berikut:

    def get_weather(city: str) -> dict:
  """Retrieves the current weather report for a specified city.

  Args:
    city (str): The name of the city.

  Returns:
    dict: A dictionary containing the weather information.
          Includes a 'status' key ('success' or 'error').
          If 'success', includes a 'report' key with weather details.
          If 'error', includes an 'error_message' key.
  """
  city_normalized = city.lower().replace(" ", "")

  mock_weather_db = {
    "newyork": {"status": "success",
      "report": "The weather in New York is sunny and 25°C."},
    "london": {"status": "success",
      "report": "It's cloudy in London and  15°C."},
    "tokyo": {"status": "success",
      "report": "Tokyo is experiencing light rain and 18°C."},
  }
  if city_normalized in mock_weather_db:
    return mock_weather_db[city_normalized]
  else:
    return {"status": "error",
      "error_message": f"No weather information for '{city}'."}

  5. Klik Create.

Sekarang, Anda harus menambahkan alat ini ke agen cuaca:

  1. Klik tombol + di kolom judul agen cuaca.
  2. Klik Add tool.
  3. Pilih alat cuaca.

Membuat petunjuk agen

Setiap agen memiliki serangkaian petunjuk yang menentukan apa yang harus dilakukan agen.

Saat memberikan petunjuk yang mereferensikan agen, gunakan sintaksis {@AGENT: Agent name}. Untuk mereferensikan alat, gunakan {@TOOL: tool_name}.

Buat petunjuk untuk setiap agen:

  1. Klik tombol + di kolom judul agen root.
  2. Klik Add instructions.

  3. Masukkan petunjuk berikut:

    You are a helpful weather application.
Your job is to greet the user and delegate to other sub-agents as needed.
When greeting the user, describe how you can help them.
When the user asks for the weather, delegate to {@AGENT: Weather agent}.
When the user is ending the conversation,
delegate to {@AGENT: Farewell agent}.
Handle only weather requests, greetings, and farewells.

  4. Klik Create.

  5. Dengan cara yang sama, tambahkan petunjuk berikut untuk agen cuaca:

    You are a helpful weather agent.
When the user asks for the weather in a specific city,
use {@TOOL: get_weather} to find the information.
If the tool returns an error, inform the user politely.
If the tool is successful, present the weather report clearly.

  6. Dengan cara yang sama, tambahkan petunjuk berikut untuk agen perpisahan:

    You are the Farewell Agent.
Your ONLY task is to provide a polite goodbye message.

Menguji agen

Aplikasi agen Anda kini siap untuk interaksi menggunakan simulator:

  1. Di sudut kiri bawah layar konsol, klik kolom Preview agent untuk memperluas jendela jika belum diperluas.
  2. Ketik "hello", lalu tekan enter. Agen akan merespons dengan sapaan umum.
  3. Ketik "what is the weather in new york?", lalu tekan enter. Agen akan merespons dengan informasi cuaca.
  4. Ketik "goodbye", lalu tekan enter. Agen akan mengakhiri percakapan.

Menggunakan variabel

Variabel digunakan untuk menyimpan dan mengambil data percakapan runtime. Hal ini memungkinkan agen mengingat informasi di seluruh giliran percakapan, sehingga menghasilkan interaksi yang lebih kontekstual. Untuk agen ini, Anda akan membuat variabel yang menangkap nama pengguna.

Untuk membuat variabel:

  1. Klik tombol variabel di sisi kanan pembuat agen.
  2. Klik Create a variable atau +.
  3. Ketik "username" sebagai nama variabel.
  4. Biarkan jenisnya sebagai Text.
  5. Klik Create.

Setelah menentukan variabel, Anda harus menentukan alat yang memungkinkan agen memperbarui variabel:

  1. Klik tombol alat di sisi kanan pembuat agen.
  2. Klik + untuk membuat alat baru bagi aplikasi agen.
  3. Klik Python code.

  4. Tempelkan kode berikut:

    from typing import Optional

def update_username(username: str) -> Optional[str]:
  """Updates the current user's name"""
  set_variable("username", username)

  5. Klik Create.

Tambahkan alat ini ke agen root:

  1. Klik tombol + di kolom judul agen root.
  2. Klik Add tool.
  3. Pilih alat update_username.

Tambahkan kalimat berikut ke petunjuk agen root, yang mereferensikan variabel menggunakan sintaksis {variable_name}:

If provided, the current user is {username},
and you should address them with this name.
You can use {@TOOL: update_username} to update the user's name if they provide
it.

Anda dapat menguji agen lagi untuk memverifikasi penggunaan variabel:

  1. Klik Start new conversation di kolom judul simulator.
  2. Masukkan "Hello, my name is Frank".
  3. Masukkan "How accurate is your information?".

Perhatikan bahwa agen kini merespons menggunakan nama Anda untuk setiap respons. Anda juga dapat memperluas bagian Steps dari percakapan simulator, tempat Anda dapat memverifikasi eksekusi alat dan hal lainnya.

Mengontrol cara mengakhiri sesi

Secara default, setiap agen Anda dikonfigurasi untuk menggunakan end_session alat sistem, tetapi, Anda dapat meningkatkan keandalan dan kontrol cara mengakhiri sesi dengan membuat petunjuk eksplisit.

Hapus alat end_session dari agen root dan cuaca dengan mengklik x di samping alat di setiap agen. Hal ini memastikan bahwa hanya agen perpisahan Anda yang akan mengakhiri sesi.

Tambahkan hal berikut ke petunjuk agen perpisahan Anda:

After providing the goodbye message and confirming the user has no more
questions, execute the tool {@TOOL: end_session}(reason="success").

Menggunakan callback untuk menerapkan pesan statis di akhir sesi

Callback menyediakan mekanisme untuk terhubung ke proses eksekusi agen tertentu menggunakan kode Python. Callback memungkinkan Anda mengamati, menyesuaikan, dan bahkan mengontrol perilaku agen pada titik tertentu yang telah ditentukan.

Ada berbagai jenis callback yang dapat Anda gunakan, dengan setiap jenis callback dieksekusi pada titik tertentu dalam giliran percakapan.

Untuk tutorial ini, tambahkan pesan statis ke respons model saat mengakhiri sesi:

  1. Klik kolom judul agen perpisahan.
  2. Klik Add callback.
  3. Pilih After LLM.

  4. Masukkan kode berikut:

    SURVEY_MESSAGE = "Click here to take our post call survey."

def after_model_callback(
    callback_context: CallbackContext,
    llm_response: LlmResponse
) -> Optional[LlmResponse]:
  for index, part in enumerate(llm_response.content.parts):
    if part.has_function_call('end_session'):
      return LlmResponse.from_parts(parts=[
        *llm_response.content.parts,
        Part.from_text(SURVEY_MESSAGE)

    ])
  return None

  5. Klik Done.

  6. Klik Save.

Anda dapat menguji agen lagi untuk memverifikasi perilaku akhir sesi:

  1. Klik Start new conversation di kolom judul simulator.
  2. Masukkan "Hello".
  3. Masukkan "Goodbye".

Perhatikan bahwa agen kini merespons menggunakan pesan yang Anda tambahkan.

Menyusun petunjuk

Untuk meningkatkan perilaku agen, Anda dapat menyusun semua petunjuk agen dalam format XML bentuk bebas yang optimal untuk pemrosesan model. Lakukan hal berikut untuk setiap agen Anda:

  1. Buka panel petunjuk untuk agen.
  2. Klik tombol Structure di kanan atas.
  3. Klik Save.

Deploy

Setelah memiliki agen yang berfungsi, Anda memiliki beberapa opsi deployment.