エージェント アプリケーションを作成する

このガイドでは、天気に関するユーザーのクエリに回答できる基本的なエージェント アプリケーションを作成する手順について説明します。

始める前に

このガイドに沿って操作する前に、設定手順を完了してください。

エージェント アプリケーションを作成する

エージェント アプリケーションとルート エージェントを作成します。

  1. Gemini Enterprise for CX コンソールを開きます。
  2. プロジェクトを選択します。
  3. [エージェントを作成] または [新しいエージェント] をクリックします。
  4. エージェント名に「天気アプリ」と入力します。
  5. [作成] をクリックします。プロジェクトで最初のエージェント アプリケーションを作成する場合は、作成に 1 ～ 2 分かかることがあります。エージェント ビルダーが表示され、ルート エージェントが作成されます。

エージェントの階層を作成する

このエージェント アプリケーションは、次の 3 つのエージェントを使用します。

  • ユーザーに挨拶し、他のサブエージェントに委任するルート エージェント。
  • 天気に関する質問に回答する天気エージェント。
  • 会話を終了するエージェントの挨拶。

ルート エージェントはすでに作成されていますが、このエージェントの設定を更新する必要があります。

  1. ルート エージェントのタイトルバーをクリックします。
  2. 必要に応じて、エージェントの名前を変更できます。
  3. 「Handles simple greetings and delegates to other agents」と説明を入力します。
  4. [保存] をクリックして、設定パネルを閉じます。

天気エージェントを作成します。

  1. ルート エージェントの下部にある [+] ボタンをクリックします。
  2. [新しいサブエージェントを追加] をクリックします。
  3. 新しいエージェントのタイトルバーをクリックします。
  4. 名前を「Weather agent」に変更します。
  5. 「Handles any weather related questions from the user」と入力します。
  6. [保存] をクリックして、設定パネルを閉じます。

同様に、「Farewell agent」という名前のルート エージェントの別のサブエージェントを作成し、「Handles user farewells and goodbyes」という説明を追加します。

エージェントの階層のスクリーンショット

天気ツールを作成する

ツールは、エージェントを外部システムまたはエージェントに提供されたインライン コードに接続するために使用されます。これにより、エージェントは他のシステムとやり取りして、情報を取得、更新、フォーマット、分析できます。

このステップでは、天気情報を取得するために使用される天気ツールを作成します。このガイドでは、このツールにユーザー向けのモック レスポンスがあります。実際の天気アプリでは、このツールは外部サーバーにアクセスして情報を取得します。

天気ツールを作成します。

  1. エージェント ビルダーの右側にあるツールボタンをクリックします。
  2. [+] をクリックして、エージェント アプリケーションの新しいツールを作成します。
  3. [Python コード] をクリックします。

  4. 次のコードを貼り付けます。

    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. [作成] をクリックします。

次に、このツールを天気エージェントに追加する必要があります。

  1. 天気エージェントのタイトルバーにある [+] ボタンをクリックします。
  2. [ツールを追加] をクリックします。
  3. 天気ツールを選択します。

エージェントへの指示を作成する

各エージェントには、エージェントが何をすべきかを定義する一連の指示があります。

エージェントを参照する手順を提供する場合は、{@AGENT: Agent name} 構文を使用します。参照ツールには {@TOOL: tool_name} を使用します。

各エージェントの手順を作成します。

  1. ルート エージェントのタイトルバーにある [+] ボタンをクリックします。
  2. [手順を追加] をクリックします。

  3. 次の指示を入力します。

    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. [作成] をクリックします。

  5. 同様に、天気エージェントに次の手順を追加します。

    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. 同様に、終了エージェントに次の手順を追加します。

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

エージェントをテストする

エージェント アプリケーションは、シミュレータを使用してインタラクションを行う準備ができました。

  1. コンソール画面の左下にある [エージェントをプレビュー] バーをクリックして、ウィンドウがまだ展開されていない場合は展開します。
  2. 「hello」と入力して、Enter キーを押します。エージェントが一般的な挨拶で応答します。
  3. 「ニューヨークの天気は？」と入力して、Enter キーを押します。 エージェントが天気情報を返します。
  4. 「goodbye」と入力して Enter キーを押します。エージェントが会話を終了します。

変数を使用する

変数は、実行時の会話データの保存と取得に使用されます。これにより、エージェントは会話のターンをまたいで情報を記憶できるため、よりコンテキストを考慮したインタラクションが可能になります。このエージェントでは、ユーザーの名前を取得する変数を作成します。

変数を作成するには:

  1. エージェント ビルダーの右側にある変数ボタンをクリックします。
  2. [変数を作成] または [+] をクリックします。
  3. 変数名として「username」と入力します。
  4. タイプは [Text] のままにします。
  5. [作成] をクリックします。

変数を定義したので、エージェントが変数を更新できるようにするツールを定義する必要があります。

  1. エージェント ビルダーの右側にあるツールボタンをクリックします。
  2. [+] をクリックして、エージェント アプリケーションの新しいツールを作成します。
  3. [Python コード] をクリックします。

  4. 次のコードを貼り付けます。

    from typing import Optional

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

  5. [作成] をクリックします。

このツールをルート エージェントに追加します。

  1. ルート エージェントのタイトルバーにある [+] ボタンをクリックします。
  2. [ツールを追加] をクリックします。
  3. update_username ツールを選択します。

次の文をルート エージェントの手順に追加します。この文では、{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.

エージェントをもう一度テストして、変数の使用状況を確認できます。

  1. シミュレータのタイトルバーにある [新しい会話を開始] をクリックします。
  2. 「Hello, my name is Frank」と入力します。
  3. 「あなたの情報の正確性について教えてください」と入力します。

エージェントは、各レスポンスであなたの名前を使用して応答します。シミュレータの会話の [手順] セクションを開いて、ツールの実行などを確認することもできます。

セッションの終了方法を制御する

デフォルトでは、各エージェントは end_session システムツールを使用するように構成されていますが、明示的な手順を作成することで、セッションの終了方法の信頼性と制御を向上させることができます。

各エージェントのツール横にある x をクリックして、ルート エージェントと天気エージェントから end_session ツールを削除します。これにより、終了エージェントのみがセッションを終了できるようになります。

送別会エージェントの指示に以下を追加します。

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

コールバックを使用してセッション終了時に静的メッセージを強制適用する

コールバックは、Python コードを使用して特定のエージェントの実行プロセスにフックするメカニズムを提供します。コールバックを使用すると、特定の事前定義されたポイントでエージェントの動作を観察、カスタマイズ、制御できます。

利用できるコールバック タイプはさまざまです。各コールバック タイプは、会話のターンの特定の時点で実行されます。

このチュートリアルでは、セッションの終了時にモデルのレスポンスに静的メッセージを追加します。

  1. 終了エージェントのタイトルバーをクリックします。
  2. [コールバックを追加] をクリックします。
  3. [After LLM] を選択します。

  4. 次のコードを入力します。

    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. [完了] をクリックします。

  6. [保存] をクリックします。

エージェントを再度テストして、セッション終了の動作を確認できます。

  1. シミュレータのタイトルバーにある [新しい会話を開始] をクリックします。
  2. 「Hello」と入力します。
  3. 「さようなら」と入力します。

エージェントが追加されたメッセージを使用して応答します。

構造の手順

エージェントの動作を改善するには、モデル処理に最適なフリーフォーム XML 形式でエージェントの指示をすべて構造化します。エージェントごとに次の操作を行います。

  1. エージェントの手順パネルを開きます。
  2. 右上の [構造] ボタンをクリックします。
  3. [保存] をクリックします。

デプロイ

動作するエージェントを作成したら、複数のデプロイ オプションを使用できます。