Set Up Your First Basic Agent

The most effective way to learn a new framework is to start building with it. Theory provides direction, but hands-on practice provides real understanding. The goal of this lesson is to move from a new development environment to a working, fully functional AI agent as quickly and efficiently as possible.

We will achieve this by setting up the necessary tools, creating a new project using the ADK built-in command-line interface (CLI), and running the default agent that it generates. This process will ensure that our environment is correctly configured and provide us with a tangible, working foundation for everything we build next.

Setting up the development environment

Before we can build our first agent, we need to prepare our development environment. This involves ensuring we have the correct version of Python, installing the ADK library, and configuring an API key to allow our agent to communicate with Google’s Gemini model.

Installing the agent development kit

The ADK is distributed as a Python package on the Python Package Index (PyPI). We can install it using pip, the standard package installer for Python. This single command installs both the core ADK library (which we will use in our code) and a helpful command-line tool named adk (which we will use in the terminal to manage our projects). Run the following command in the terminal to install the library:

Note: You don’t need to worry about the project setup at Educative platform as we have already installed the necessary libraries for you here. However, understanding this process is essential for any development you do on your local machine.

Configuring the Gemini API key

For our agent to think and respond, it needs access to an LLM. We will be using Google’s Gemini model. To use it, our application must authenticate itself using a unique API key. This key proves to Google’s servers that our application has permission to use the model.

To get your key, follow these steps:

1. Navigate to Google AI Studio.

2. If prompted, sign in with your Google account.

3. Click on the “Get API key” option, typically found on the left-hand navigation menu.

4. Select “Create API key in new project.” A new key will be generated. Copy this key to the clipboard for future use.

Once we have the key, we must make it available to our application. The standard and most secure way to do this is by setting it as an environment variable. The ADK is preconfigured to look for an environment variable named GOOGLE_API_KEY.

Creating and running the agent via CLI

With our environment prepared, we can now use the ADK’s command-line tool to create and run our first agent project. This tool is designed to accelerate development by generating a standardized, ready-to-run project structure for us. Let’s proceed with the hands-on below.

Step 1: Create the agent project

The adk command-line tool includes a powerful scaffolder that generates a complete boilerplate project. This saves us from writing boilerplate code and ensures our project follows best practices from the start.

In the terminal, run the following command:

After running this command, the CLI will launch an interactive setup process to configure our new agent. We will be prompted to provide the following information:

• Choose a model: For now, select the default option, gemini-2.5-flash.

• Choose a backend: Select Google AI. This option uses the API key we configured earlier.

• Enter Google API key: Paste the key we obtained from Google AI Studio and press “Enter.”

The CLI will use these answers to generate the necessary files for our project.

Step 2: Explore the project structure

Now, let’s navigate into our newly created project directory and review the files that were generated.

Note: We use the -a flag with the ls command to ensure we can see all files, including hidden ones like .env.

We will see the following files in the directory:

• .env: This is a file used to store environment variables for our project. The API key we provided during the interactive setup is stored here. The ADK will automatically load this file when we run the agent, making the key available to the application without us needing to expose it in our code. This is a standard and secure practice for managing secrets.

• __init__.py: This is a special file that tells Python to treat the my_first_agent directory as a Python package. The line inside it, from . import agent, makes the root_agent object we defined in agent.py easily importable by other parts of the framework.

• agent.py: This is the core of our application. It contains the main Python code that defines our agent.

Note: While we’ve used the adk create command to generate this project, it’s important to understand the structure it produces. The ADK framework is designed to automatically discover and load agents from standard Python packages. This means we could have created the my_first_agent directory and its files manually. The key takeaway is that adhering to this package structure is essential for the framework to function correctly, whether it’s generated by the CLI or created manually.

Step 3: Run the agent

The project generated by the CLI is fully functional. The adk tool provides a simple command to execute the agent defined in the current project directory. Run the following command in the terminal:

The terminal will display some startup messages, and then we will see a prompt, indicating that the agent is live and waiting for our input. Type a greeting like Hello and press “Enter.” The agent will use the Gemini model to generate a friendly response. We have just had our first conversation with an agent we built.

To stop the agent, we can type “exit” or press “Ctrl+C.”

Try yourself

Note: Before starting the terminal, press the “Edit” button and enter your Google API key. This step will automatically set the GOOGLE_API_KEY environment variable for your terminal session.

Later, when the adk create command prompts you to enter the API key, it will automatically detect the key from this environment variable. At that prompt, you will simply need to press “Enter” to confirm and proceed.

Let’s try creating and running your first agent by using the above commands in the terminal below:

Code walkthrough

Now that we have successfully run our agent, let’s understand the code that made it possible. All the logic for defining our agent is contained within the agent.py file that the CLI generated for us. This simple file demonstrates the fundamental concepts of defining an LLM-powered agent in the ADK.

Here is the complete code from agent.py:

Code explanation:

• Line 1: We are importing the Agent (also known as LlmAgent) class from the google.adk.agents.llm_agent module, which is the explicit class for creating an agent whose reasoning is powered by an LLM.

• Lines 3–8: We are creating an instance of the Agent class and assigning it to a variable named root_agent. This object will serve as the primary entry point for our agent application. Let’s examine the parameters we are passing to its constructor:

  • Line 4: The model parameter specifies which large language model will power this agent’s reasoning. This value was set based on the choice we made during the interactive CLI setup.

  • Line 5: The name parameter provides a unique identifier for this agent. This name is useful for logging and becomes essential for differentiation in multi-agent systems.

  • Line 6: The description parameter gives a concise, human-readable summary of the agent’s purpose. This becomes critical when other agents need to understand what this agent can do.

  • Line 7: The instruction parameter provides the core system prompt that defines the agent’s persona, primary goal, and any constraints on its behavior. This is the main directive that guides the LLM.

The above code made our agent functional, but let’s make it more powerful by giving it a custom capability.

Adding a tool to our agent

Currently, our agent’s response is generated entirely by the LLM based on its general training and the simple instruction we provided. This is powerful, but to build truly robust and predictable applications, we need to give our agents specific, reliable capabilities. We can achieve this by equipping them with tools. A tool is a Python function that an agent can decide to call to perform a specific action.

Let’s enhance our agent by giving it a custom tool. Instead of relying on the LLM to come up with a generic greeting, we will provide a greeting_tool that returns a specific, warm welcome. We will then instruct the agent to use this tool whenever a user greets it. Let’s update our agent.py file with the following code.

Code explanation

This updated code introduces two key changes: the tool function itself and the modification of the Agent to use it. Let’s understand it.

• Lines 3–5: We define a standard Python function named greeting_tool.

  • The function has a descriptive docstring ("""Returns a warm, friendly greeting."""). The ADK uses the docstring to help the LLM understand what the tool does and when to use it.

  • The function returns a simple string. This will be the output that the agent receives after calling the tool.

• Line 11: The instruction parameter has been updated to be more specific. We are now explicitly directing the agent to use our new tool. This is crucial for guiding the agent’s behavior.

• Line 12: We have added the tools parameter to the Agent constructor. This parameter takes a list of all the tool functions that we want to make available to this agent. By including greeting_tool in this list, we are registering it with the agent and empowering it to call this function.

Now that our agent is equipped with a custom tool, let’s try running it to see how it behaves.

Interacting with the web interface

While the terminal is useful for quick tests, the ADK also provides a more visual and user-friendly way to interact with our agents. The framework includes a built-in web server that launches a simple chat interface, which is excellent for demonstrations and more intuitive debugging.

To launch this interface, we use the adk web command. By default, this command starts a server accessible only on our local machine at http://localhost:8000. However, we can customize this by specifying the host with the --host flag and the port using the --port flag.

In the interactive lab below, we will launch the web interface and interact with our agent.

Note: Run the adk web --host 0.0.0.0 --port 8000 command from the parent directory that contains our my_first_agent folder.

After running this command, follow the link after “Your app can be found at” to open the web application in a new tab. Once the interface loads, select the my_first_agent from the drop-down menu in the upper-left corner and start a conversation. You will be able to chat with your agent just as you did in the terminal, but within a clean web UI.

Note: This web interface is a built-in developer tool provided by the Google ADK, designed for interactively testing and debugging agents locally. While we are using it for simple text chat, its more advanced views support observing the agent’s internal events, inspecting its state, and even handling multimodal interactions like voice, video, and file uploads.

Now, we have moved beyond a simple setup to build and enhance our first true AI agent. By leveraging the ADK’s command-line tools, we established a professional project structure and a repeatable workflow. More importantly, by giving the agent a custom tool, we have enabled it to perform specific, reliable actions, which is essential for building sophisticated agentic systems. This complete cycle of creation, enhancement, and interaction is the core development pattern for all the complex agents we will build.