From 4e011730293ef8e8796e02614b4991eea20e4a9f Mon Sep 17 00:00:00 2001 From: ShubhamSaboo Date: Fri, 4 Jul 2025 21:15:11 -0500 Subject: [PATCH] feat: added google ADK tutorial --- .../structured_output_agent/README.md | 78 +++++++++++++++++++ .../email_generator_agent/.env.example | 3 + .../email_generator_agent/__init__.py | 1 + .../email_generator_agent/agent.py | 29 +++++++ .../structured_output_agent/requirements.txt | 2 + 5 files changed, 113 insertions(+) create mode 100644 google_adk_tutorials/structured_output_agent/README.md create mode 100644 google_adk_tutorials/structured_output_agent/email_generator_agent/.env.example create mode 100644 google_adk_tutorials/structured_output_agent/email_generator_agent/__init__.py create mode 100644 google_adk_tutorials/structured_output_agent/email_generator_agent/agent.py create mode 100644 google_adk_tutorials/structured_output_agent/requirements.txt diff --git a/google_adk_tutorials/structured_output_agent/README.md b/google_adk_tutorials/structured_output_agent/README.md new file mode 100644 index 0000000..a1fcafe --- /dev/null +++ b/google_adk_tutorials/structured_output_agent/README.md @@ -0,0 +1,78 @@ +# 📧 Structured Output in Google ADK + +A tutorial demonstrating how to implement structured output using Google's ADK (Agent Development Kit) framework. This example uses an email generator agent to show how to create type-safe, structured responses with Pydantic schemas and Gemini 2.5 Flash model. + +## Tutorial Features + +- 📝 **Structured Output Implementation**: + - Learn how to use Pydantic schemas for type-safe output + - Understand how to define structured response formats + - See how Google ADK handles structured responses + +- 🎯 **Email Generator Example**: + - Practical example using email generation as the use case + - Shows how to create professional email content with proper structure + - Demonstrates real-world application of structured output + +- 🔧 **Google ADK Best Practices**: + - Simple agent definition with clear instructions + - Proper use of output schemas for reliable results + - Minimal codebase demonstrating core concepts + +## How to Run + +1. **Setup Environment** + ```bash + # Clone the repository + git clone https://github.com/Shubhamsaboo/awesome-llm-apps.git + cd awesome-llm-apps/google_adk_tutorials/structured_output_agent/email_generator_agent + + # Install dependencies + pip install -r requirements.txt + ``` + +2. **Configure API Keys** + - Get Google AI API key from [Google AI Studio](https://aistudio.google.com/) + - Set up your API credentials for Gemini access + +3. **Run the Agent** + ```bash + # Start the ADK web interface from the root folder + cd google_adk_tutorials/structured_output_agent + adk web + ``` + Then: + 1. Open the web interface in your browser + 2. Select the "email_generator_agent" + 3. Enter your email request (e.g. "Write a professional email to schedule a meeting with a client") + 4. The response will be a structured JSON with subject and body fields + +## Tutorial Overview + +This tutorial demonstrates structured output implementation in Google ADK: + +1. **Agent Definition**: Learn how to create a `LlmAgent` with Gemini 2.5 Flash +2. **Output Schema**: Understand how to use Pydantic models for structured responses +3. **Instructions**: See how to write clear prompts for structured output +4. **Structured Response**: Learn how to handle JSON responses with defined schemas + +## Code Structure + +- `agent.py`: Contains the main agent definition and Pydantic schema +- `__init__.py`: Module initialization for easy imports + +## Dependencies + +- `google-adk`: Google's Agent Development Kit +- `pydantic`: Data validation and settings management + +## How Structured Output Works + +This tutorial shows how Google ADK handles structured output: + +1. **Input Processing**: Takes natural language requests and processes them through the agent +2. **Content Generation**: Uses Gemini 2.5 Flash to generate content based on instructions +3. **Output Structuring**: Automatically formats responses according to the Pydantic schema +4. **Response Validation**: Ensures the output matches the defined structure and types + +This approach demonstrates how to create reliable, type-safe responses in Google ADK applications. \ No newline at end of file diff --git a/google_adk_tutorials/structured_output_agent/email_generator_agent/.env.example b/google_adk_tutorials/structured_output_agent/email_generator_agent/.env.example new file mode 100644 index 0000000..f5cfcfb --- /dev/null +++ b/google_adk_tutorials/structured_output_agent/email_generator_agent/.env.example @@ -0,0 +1,3 @@ +# If using Gemini via Google AI Studio +GOOGLE_GENAI_USE_VERTEXAI=False +GOOGLE_API_KEY="your-api-key" \ No newline at end of file diff --git a/google_adk_tutorials/structured_output_agent/email_generator_agent/__init__.py b/google_adk_tutorials/structured_output_agent/email_generator_agent/__init__.py new file mode 100644 index 0000000..02c597e --- /dev/null +++ b/google_adk_tutorials/structured_output_agent/email_generator_agent/__init__.py @@ -0,0 +1 @@ +from . import agent diff --git a/google_adk_tutorials/structured_output_agent/email_generator_agent/agent.py b/google_adk_tutorials/structured_output_agent/email_generator_agent/agent.py new file mode 100644 index 0000000..b86ceeb --- /dev/null +++ b/google_adk_tutorials/structured_output_agent/email_generator_agent/agent.py @@ -0,0 +1,29 @@ +from google.adk.agents import LlmAgent +from pydantic import BaseModel, Field + +class EmailContent(BaseModel): + """Schema for email content with subject and body.""" + + subject: str = Field( + description="The subject line of the email. Should be concise and descriptive." + ) + body: str = Field( + description="The main content of the email. Should be well-formatted with proper greeting, paragraphs, and signature." + ) + +root_agent = LlmAgent( + name="email_generator_agent", + model="gemini-2.5-flash", + description="Professional email generator that creates structured email content", + instruction=""" + You are a professional email writing assistant. + + IMPORTANT: Your response must be a JSON object with exactly these fields: + - "subject": A concise, relevant subject line + - "body": Well-formatted email content with greeting, main content, and closing + + Format your response as valid JSON only. + """, + output_schema=EmailContent, # This is where the magic happens + output_key="generated_email" +) \ No newline at end of file diff --git a/google_adk_tutorials/structured_output_agent/requirements.txt b/google_adk_tutorials/structured_output_agent/requirements.txt new file mode 100644 index 0000000..53c77a2 --- /dev/null +++ b/google_adk_tutorials/structured_output_agent/requirements.txt @@ -0,0 +1,2 @@ +google-adk>=1.5.0 +pydantic>=2.0.0 \ No newline at end of file