Create an agent application

This guide takes you through the steps to create a basic agent application. You will create a weather application. This agent application contains:

  • Root agent for orchestration.
  • Sub-agents for specific tasks.
  • Tools to retrieve weather information.

Before you begin

Be sure to complete setup instructions before following this guide.

Create an agent application

Create an agent application and root agent:

  1. Open the Gemini Enterprise for CX console.
  2. Select your project.
  3. Click Create agent or New agent.
  4. Provide "weather app" as the agent name.
  5. Click Create. If this is the first agent application you have created for the project, creation may take 1-2 minutes. The agent builder is shown and, a root agent is created for you.

Create a greeting tool

In this step, you create a greeting tool, which is used to greet the user. For the sake of this guide, this tool has a simple response for the user. In a real application, your tools can access external resources to look up user information.

Create the greeting tool:

  1. Click the tools button on the right side of the agent builder.
  2. Click Create a tool.
  3. Click Python code execution.
  4. Enter "greet_user" for the tool name.

  5. Paste the following code:

    def greet_user(name: str) -> str:
  """Provides a simple greeting. If a name is provided, it will be used.

  Args:
    name (str, optional): The name of the person to greet.

  Returns:
    str: A friendly greeting message.
  """
  if name:
    greeting = f"Hello, {name}!"
  else:
    greeting = "Hello there!"
  return greeting

  6. Click Create.

Add the greeting tool to the root agent

Now, you need to add this tool to the agent:

  1. Hover over the root agent on the agent builder.
  2. Click the plus button in the top right corner.
  3. Click Add resources -> Add tool.
  4. Select the greeting tool.

Create root agent instructions

Each agent has a set of instructions which define what the agent should do. Create instructions for the root agent:

  1. Hover over the root agent on the agent builder.
  2. Click the plus button in the top right corner.
  3. Click Add resources -> Add instructions.

  4. Enter the following instructions:

    Your job is to greet the user.
Use the 'greet_user' tool to get a greeting message.

  5. Click Create.

Update root agent settings

For better agent transitions, you should update the name and description of the root agent:

  1. Click the title bar of the root agent.
  2. Change the name to "greeting_agent".
  3. Enter the description: "Handles simple greetings and hellos".
  4. Click Save, then close the settings panel.

Test the agent

Your agent application is now ready for interactions using the simulator:

  1. In the bottom left corner of the console screen, click the Preview agent bar to expand the window.
  2. Type "hello", then press enter. The agent responds with a generic greeting.
  3. Type "my name is fred", then press enter. The agent responds with a greeting including "fred".

Add a weather sub-agent

So far, your agent application contains a single agent. This works well for basic applications, but as your application becomes more complex, you should create additional sub-agents for specific tasks. This improves modularity, specialization, scalablity, and efficiency in your application.

In this section you will create a weather tool and weather agent. The tool uses mocked weather data for simplicity. In a real application, your tools will typically access external services for information like this.

Create a weather sub-agent:

  1. Similar to steps above, create a Python weather tool called "get_weather". Use the following tool code:

    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}'."}

  2. Create a weather sub-agent:

    1. Hover over the root agent on the agent builder.
    2. Click the plus button at the bottom of the agent.
    3. Click Add new sub-agent.
    4. Click the title bar for the newly created agent. The agent settings panel opens.
    5. Change the name to "weather_agent".
    6. Enter the description: "Handles any weather related questions from the user".
    7. Click Save, then close the agent settings panel.

  3. Similar to steps above, add the weather tool to the weather agent.

  4. Similar to steps above, create instructions for the weather agent. Use the following instructions:

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

Add a farewell sub-agent

Create a farewell sub-agent to handle farewell messages:

  1. Similar to steps above, create a Python weather tool called "farewell_user". Use the following tool code:

    def farewell_user() -> str:
  """Provides a simple farewell message to conclude the conversation."""
  return "Goodbye! Have a great day."

  2. Create a farewell sub-agent:

    1. Hover over the root agent on the agent builder.
    2. Click the plus button at the bottom of the agent.
    3. Click Add new sub-agent.
    4. Click the title bar for the newly created agent. The agent settings panel opens.
    5. Change the name to "farewell_agent".
    6. Enter the description: "Handles user farewells and goodbyes".
    7. Click Save, then close the agent settings panel.

  3. Similar to steps above, add the farewell tool to the farewell agent.

  4. Similar to steps above, create instructions for the farewell agent. Use the following instructions:

    You are the Farewell Agent.
Your ONLY task is to provide a polite goodbye message.
Use the 'farewell_user' tool when the user indicates they are leaving
or ending the conversation (e.g., using words like 'bye', 'goodbye',
'thanks bye', 'see you').
Do not perform any other actions.

Update root agent instructions

Update the instructions for the root agent (greeting agent) to mention the new sub-agents:

You are a helpful weather application.
Your job is to greet the user and delegate to other sub-agents as needed.
For greeting messages,
use the 'greet_user' tool.
When the user asks for the weather,
delegate to the 'weather_agent' agent.
When the user is ending the conversation,
delegate to the 'farewell_agent'.
Handle only weather requests, greetings, and farewells.

Structure instructions

To improve agent behavior, you can structure all of the agent instructions in an XML format that is optimal for model processing. Perform the following for each of your agents:

  1. Open the instructions panel for an agent.
  2. Click the Structure button at the top right.
  3. Click Save.

Test the agent again

You have now added three agents to your application. Similar to steps above, you can have a conversation with the agent using the Preview agent simulator panel.

Open the Preview agent panel, then click the Start new conversation button in the title bar to clear any prior conversations.

Now try the following messages:

  • hello
  • my name is fred
  • what is the weather in new york
  • what is the weather in toledo
  • good bye

Deploy

Once you have a working agent, you have multiple deployment options.