Your First AI Agent System: Study Buddy & First Steps

In the ever-evolving landscape of Artificial Intelligence, "AI agents" have become a hot topic. But what exactly are they? In simple terms, an AI agent is a piece of software that can perceive its environment, make decisions, and take actions to achieve specific goals. Think of them as autonomous entities that can perform tasks on your behalf.

Unlike traditional programs that follow a rigid set of instructions, AI agents possess a degree of intelligence that allows them to be more flexible and adaptive. They can learn from their interactions, reason about complex situations, and even collaborate with other agents.

In this blog post, we'll guide you through creating your very first AI agent — a "Study Buddy" — using the Google Agent Development Kit (ADK).

Prerequisites

• Python 3.11 or higher
• Terminal/Command Line Access
• pip Installed — update via python -m pip install --upgrade pip
• Internet Connection
• Google Credentials — Vertex AI or direct API key from Google AI Studio
• Basic Knowledge of Python and command line

Setting up Your Project with uv

We'll use uv — a fast, modern Python package manager — to set up our project. Follow these steps:

Step 1: Install uv

pip install uv

Step 2: Create and enter the project directory

mkdir school_agents && cd school_agents

Step 3: Initialize the project

uv init

After running uv init, your directory will look like this:

school_agents/
├── .python-version
├── README.md
├── main.py
└── pyproject.toml

Step 4: Create and activate a virtual environment

uv venv

Step 5: Activate the virtual environment

source .venv/bin/activate

.venv\Scripts\activate

Step 6: Install dependencies

uv add google-adk

Step 7: Create the agent directory structure

mkdir -p src/agents && cd src/agents

Creating Your Agent with adk create

ADK provides a convenient CLI command to scaffold a new agent. From within the src/agents directory, run:

adk create studdy_buddy

This command generates the boilerplate files for your agent, including the configuration and prompt templates.

Project Structure

After setting everything up, your complete project should look like this:

school_agents/
├── .venv/
├── src/
│   └── agents/
│       └── study_buddy/
│           ├── __init__.py
│           ├── agent.py
│           ├── agent_config.yml
│           └── prompts/
│               └── study_buddy_prompt.md
├── pyproject.toml
└── uv.lock

Each file serves a specific purpose: agent.py contains the agent logic, agent_config.yml holds the configuration, and the prompts/ directory stores your agent's personality and instructions.

Configuring Your Agent

Before your agent can communicate with a language model, you need to set up your credentials. Create a .env file at the project root (school_agents/.env).

For Vertex AI:

GOOGLE_CLOUD_PROJECT="your-google-cloud-project-id"

Then authenticate via the CLI:

gcloud auth application-default login

Using GOOGLE_API_KEY Instead of Vertex AI

If you prefer using a direct API key from Google AI Studio, your .env file should contain:

GOOGLE_API_KEY="your-google-api-key"

agent_config.yml

This YAML file defines your agent's core settings — its name, description, model, and the path to its prompt file:

agent:
  name: "study_buddy"
  description: "A friendly and knowledgeable study assistant that helps students learn effectively."
  model: "gemini-2.0-flash"
  prompt_file: "prompts/study_buddy_prompt.md"

prompts/study_buddy_prompt.md

The prompt is where you define your agent's personality, capabilities, and constraints. Good prompt engineering follows several key principles:

• Role — Clearly define who the agent is.
• Responsibilities — Outline what the agent should do.
• Specifications — Detail how the agent should behave.
• Limitations — Set clear boundaries.
• Tonality — Define the agent's communication style.
• Response Instructions — Guide the format and structure of outputs.

Here's the full Study Buddy prompt:

# Study Buddy Agent Prompt

## Identity & Purpose
You are **Study Buddy**, a friendly, patient, and encouraging AI study assistant.
Your primary goal is to help students understand concepts, prepare for exams,
and develop effective study habits. You are NOT a replacement for a teacher —
you are a supportive companion on the student's learning journey.

## Capabilities

### Subject Expertise
- Help with a wide range of academic subjects including Math, Science,
  History, English, and more.
- Explain complex concepts in simple, easy-to-understand language.
- Provide examples and analogies to reinforce understanding.

### Homework Guidance
- Guide students through homework problems step-by-step.
- Ask leading questions to help students arrive at answers themselves.
- Never provide direct answers — always teach the process.

### Exam Preparation
- Create practice questions and quizzes on requested topics.
- Suggest effective study strategies and techniques.
- Help students create study schedules and plans.

### Motivation & Support
- Celebrate student achievements and progress.
- Provide encouragement when students are struggling.
- Maintain a positive and uplifting tone at all times.

## Behavior Guidelines
- Always be patient — never express frustration or impatience.
- Use age-appropriate language and examples.
- Break down complex topics into manageable chunks.
- Encourage curiosity and critical thinking.
- Ask clarifying questions when a student's request is unclear.
- Use markdown formatting for clear, structured responses.
- Include relevant emojis to keep the tone friendly and engaging.

## Critical Constraints

### Academic Integrity
- **NEVER** provide direct answers to homework or test questions.
- Always guide students through the problem-solving process.
- If a student asks for a direct answer, redirect them with
  guiding questions and hints.

### Response to Direct Answer Requests
When a student asks "What is the answer to X?", respond with:
1. Acknowledge the question.
2. Break it down into smaller, understandable parts.
3. Ask guiding questions to lead them to the answer.
4. Provide hints if they are stuck.
5. Celebrate when they arrive at the correct answer.

### Technical Requirements
- Use proper mathematical notation when discussing formulas.
- Cite reliable sources when presenting factual information.
- Clearly distinguish between facts and opinions.

### Boundaries
- Do NOT provide personal, medical, or mental health advice.
- Do NOT engage in non-academic conversations.
- If asked about topics outside your scope, politely redirect
  the conversation back to academics.
- Do NOT share or generate inappropriate content of any kind.

## Core Mission
Your core mission is to empower students to become independent learners.
Every interaction should leave the student feeling more confident,
more knowledgeable, and more motivated to continue learning.

Why External Configuration and Prompts?

You might wonder why we use separate files instead of hardcoding everything in Python. There are several important reasons:

• Modularity — Each component has a single responsibility. The code handles logic, the config handles settings, and the prompt handles personality.
• Readability — Long prompts are much easier to read and edit in a dedicated markdown file than embedded in Python strings.
• Separation of Concerns — Non-developers (like content writers or domain experts) can modify the prompt without touching any code.
• Reusability — The same agent code can be reused with different configurations and prompts to create entirely different agents.

Bringing Your Agent to Life: The Code

Now for the main event — the agent.py file that ties everything together. This is the brain of your Study Buddy:

import os
from pathlib import Path
import yaml
from google.adk import Agent

def load_agent_config(config_path: str) -> dict:
    """Load agent configuration from YAML file."""
    with open(config_path, 'r', encoding='utf-8') as f:
        return yaml.safe_load(f)

def load_prompt(prompt_path: str) -> str:
    """Load prompt content from markdown file."""
    with open(prompt_path, 'r', encoding='utf-8') as f:
        return f.read().strip()

def create_study_buddy_agent() -> Agent:
    """Create and configure the Study Buddy agent."""
    current_dir = Path(__file__).parent
    config_path = current_dir / 'agent_config.yml'
    config = load_agent_config(config_path)

    prompt_path = current_dir / config['agent']['prompt_file']
    instruction = load_prompt(prompt_path)

    agent = Agent(
        name=config['agent']['name'],
        description=config['agent']['description'],
        model=config['agent']['model'],
        instruction=instruction
    )

    return agent

root_agent = create_study_buddy_agent()

Let's break down what's happening:

• load_agent_config() reads the YAML configuration file and returns it as a Python dictionary.
• load_prompt() reads the markdown prompt file and returns it as a clean string.
• create_study_buddy_agent() wires everything together — it loads the config, loads the prompt, and creates an Agent instance with all the settings.
• root_agent is the entry point that ADK looks for when running your agent.

Running Your Agent with adk web

It's time to see your Study Buddy in action. Navigate to the agent directory and start the web interface:

cd src/agents/studdy_buddy
adk web

This starts a local web server with a built-in chat interface. Open the URL displayed in your terminal (usually http://localhost:8000) and start chatting with your Study Buddy. Try asking it to help you understand a topic — you'll see it guide you with questions rather than giving direct answers, just as we instructed in the prompt.

Conclusion

Congratulations! You've just built your first AI agent from scratch. Let's recap what you've accomplished:

• Learned what AI agents are and how they differ from traditional programs.
• Set up a professional Python project using uv.
• Scaffolded an agent using adk create.
• Configured your agent with external YAML and environment variables.
• Crafted a detailed prompt that defines your agent's personality and constraints.
• Wrote the Python code to bring your agent to life.
• Ran and tested your agent using adk web.

Experiment and Iterate

The best way to learn is by doing. Here are some things you can try:

• Change Models — Try switching from gemini-2.0-flash to other available models and observe the differences in response quality and speed.
• Modify Prompts — Tweak the Study Buddy prompt to change its personality or focus area. What happens if you make it more formal? Or focused on a single subject?
• Customize Code — Add logging, error handling, or additional configuration options to the agent code.
• Test Variations — Try different types of questions and observe how the agent handles edge cases based on your prompt instructions.

What's Next: Advancing Your AI Agent Skills

This is just the beginning of your AI agent journey. In upcoming posts, we'll explore:

• Integrating with Tools, MCP, and APIs — Give your agent the ability to search the web, run code, and interact with external services.
• Deployment — Take your agent from local development to production-ready deployment.
• Multi-Agent Systems — Build systems where multiple specialized agents collaborate to solve complex problems.

Stay tuned and keep building!