Create adk-docs dir

ADK-Crash-Course/1-basic-agent/README.md

@@ -0,0 +1,124 @@
+# Basic ADK Agent Example
+
+## What is an ADK Agent?
+
+The `LlmAgent` (often aliased simply as `Agent`) is a core component in ADK that acts as the "thinking" part of your application. It leverages the power of a Large Language Model (LLM) for:
+- Reasoning
+- Understanding natural language
+- Making decisions
+- Generating responses
+- Interacting with tools
+
+Unlike deterministic workflow agents that follow predefined paths, an `LlmAgent`'s behavior is non-deterministic. It uses the LLM to interpret instructions and context, deciding dynamically how to proceed, which tools to use (if any), or whether to transfer control to another agent.
+
+## Required Agent Structure
+
+For ADK to discover and run your agents properly (especially with `adk web`), your project must follow a specific structure:
+
+```
+parent_folder/
+    agent_folder/         # This is your agent's package directory
+        __init__.py       # Must import agent.py
+        agent.py          # Must define root_agent
+        .env              # Environment variables
+```
+
+### Essential Components:
+
+1. **`__init__.py`**
+   - Must import the agent module: `from . import agent`
+   - This makes your agent discoverable by ADK
+
+2. **`agent.py`**
+   - Must define a variable named `root_agent`
+   - This is the entry point that ADK uses to find your agent
+
+3. **Command Location**
+   - Always run `adk` commands from the parent directory, not from inside the agent directory
+   - Example: Run `adk web` from the parent folder that contains your agent folder
+
+This structure ensures that ADK can automatically discover and load your agent when running commands like `adk web` or `adk run`.
+
+## Key Components
+
+### 1. Identity (`name` and `description`)
+- **name** (Required): A unique string identifier for your agent
+- **description** (Optional, but recommended): A concise summary of the agent's capabilities. Used for other agents to determine if they should route a task to this agent.
+
+### 2. Model (`model`)
+- Specifies which LLM powers the agent (e.g., "gemini-2.0-flash")
+- Affects the agent's capabilities, cost, and performance
+
+### 3. Instructions (`instruction`)
+The most critical parameter for shaping your agent's behavior. It defines:
+- Core task or goal
+- Personality or persona
+- Behavioral constraints
+- How to use available tools
+- Desired output format
+
+### 4. Tools (`tools`)
+Optional capabilities beyond the LLM's built-in knowledge, allowing the agent to:
+- Interact with external systems
+- Perform calculations
+- Fetch real-time data
+- Execute specific actions
+
+## Getting Started
+
+This example uses the same virtual environment created in the root directory. Make sure you have:
+
+1. Activated the virtual environment from the root directory:
+```bash
+# macOS/Linux:
+source ../.venv/bin/activate
+# Windows CMD:
+..\.venv\Scripts\activate.bat
+# Windows PowerShell:
+..\.venv\Scripts\Activate.ps1
+```
+
+2. Set up your API key:
+   - Rename `.env.example` to `.env` in the greeting_agent folder
+   - Add your Google API key to the `GOOGLE_API_KEY` variable in the `.env` file
+
+## Running the Example
+
+To run this basic agent example, you'll use the ADK CLI tool which provides several ways to interact with your agent:
+
+1. Navigate to the 1-basic-agent directory containing your agent folder.
+2. Start the interactive web UI:
+```bash
+adk web
+```
+
+3. Access the web UI by opening the URL shown in your terminal (typically http://localhost:8000)
+
+4. Select your agent from the dropdown menu in the top-left corner of the UI
+
+5. Start chatting with your agent in the textbox at the bottom of the screen
+
+### Troubleshooting
+
+If your agent doesn't appear in the dropdown menu:
+- Make sure you're running `adk web` from the parent directory (1-basic-agent), not from inside the agent directory
+- Check that your `__init__.py` properly imports the agent module
+- Verify that `agent.py` defines a variable named `root_agent`
+
+### Alternative Run Methods
+
+The ADK CLI tool provides several options:
+
+- **`adk web`**: Launches an interactive web UI for testing your agent with a chat interface
+- **`adk run [agent_name]`**: Runs your agent directly in the terminal
+- **`adk api_server`**: Starts a FastAPI server to test API requests to your agent
+
+### Example Prompts to Try
+
+- "How do you say hello in Spanish?"
+- "What's a formal greeting in Japanese?"
+- "Tell me how to greet someone in French"
+
+You can exit the conversation or stop the server by pressing `Ctrl+C` in your terminal.
+
+This example demonstrates a simple agent that responds to greeting-related queries, showing the fundamentals of agent creation with ADK.

ADK-Crash-Course/1-basic-agent/greeting_agent/__init__.py

@@ -0,0 +1 @@
+from . import agent

ADK-Crash-Course/1-basic-agent/greeting_agent/agent.py

@@ -0,0 +1,12 @@
+from google.adk.agents import Agent
+
+root_agent = Agent(
+    name="greeting_agent",
+    # https://ai.google.dev/gemini-api/docs/models
+    model= "gemini-2.0-flash-exp",# "gemini-2.0-flash-live-preview-04-09",  #"gemini-2.0-flash-exp", 
+    description="Greeting agent",
+    instruction="""
+    You are an interesting and engaging conversationalist. you will ask the users name and instegate a conversation with 
+    user.
+    """,
+)

ADK-Crash-Course/10-sequential-agent/README.md

@@ -0,0 +1,140 @@
+# Sequential Agents in ADK
+
+This example demonstrates how to implement a Sequential Agent in the Agent Development Kit (ADK). The main agent in this example, `lead_qualification_agent`, is a Sequential Agent that executes sub-agents in a predefined order, with each agent's output feeding into the next agent in the sequence.
+
+## What are Sequential Agents?
+
+Sequential Agents are workflow agents in ADK that:
+
+1. **Execute in a Fixed Order**: Sub-agents run one after another in the exact sequence they are specified
+2. **Pass Data Between Agents**: Using state management to pass information from one sub-agent to the next
+3. **Create Processing Pipelines**: Perfect for scenarios where each step depends on the previous step's output
+
+Use Sequential Agents when you need a deterministic, step-by-step workflow where the execution order matters.
+
+## Lead Qualification Pipeline Example
+
+In this example, we've created `lead_qualification_agent` as a Sequential Agent that implements a lead qualification pipeline for sales teams. This Sequential Agent orchestrates three specialized sub-agents:
+
+1. **Lead Validator Agent**: Checks if the lead information is complete enough for qualification
+   - Validates for required information like contact details and interest
+   - Outputs a simple "valid" or "invalid" with a reason
+
+2. **Lead Scorer Agent**: Scores valid leads on a scale of 1-10
+   - Analyzes factors like urgency, decision-making authority, budget, and timeline
+   - Provides a numeric score with a brief justification
+
+3. **Action Recommender Agent**: Suggests next steps based on the validation and score
+   - For invalid leads: Recommends what information to gather
+   - For low-scoring leads (1-3): Suggests nurturing actions
+   - For medium-scoring leads (4-7): Suggests qualifying actions
+   - For high-scoring leads (8-10): Suggests sales actions
+
+### How It Works
+
+The `lead_qualification_agent` Sequential Agent orchestrates this process by:
+
+1. Running the Validator first to determine if the lead is complete
+2. Running the Scorer next (which can access validation results via state)
+3. Running the Recommender last (which can access both validation and scoring results)
+
+The output of each sub-agent is stored in the session state using the `output_key` parameter:
+- `validation_status`
+- `lead_score`
+- `action_recommendation`
+
+## Project Structure
+
+```
+9-sequential-agent/
+│
+├── lead_qualification_agent/       # Main Sequential Agent package
+│   ├── __init__.py                 # Package initialization
+│   ├── agent.py                    # Sequential Agent definition (root_agent)
+│   │
+│   └── subagents/                  # Sub-agents folder
+│       ├── __init__.py             # Sub-agents initialization
+│       │
+│       ├── validator/              # Lead validation agent
+│       │   ├── __init__.py
+│       │   └── agent.py
+│       │
+│       ├── scorer/                 # Lead scoring agent
+│       │   ├── __init__.py
+│       │   └── agent.py
+│       │
+│       └── recommender/            # Action recommendation agent
+│           ├── __init__.py
+│           └── agent.py
+│
+├── .env.example                    # Environment variables example
+└── README.md                       # This documentation
+```
+
+## Getting Started
+
+### Setup
+
+1. Activate the virtual environment from the root directory:
+```bash
+# macOS/Linux:
+source ../.venv/bin/activate
+# Windows CMD:
+..\.venv\Scripts\activate.bat
+# Windows PowerShell:
+..\.venv\Scripts\Activate.ps1
+```
+
+2. Copy the `.env.example` file to `.env` and add your Google API key:
+```
+GOOGLE_API_KEY=your_api_key_here
+```
+
+### Running the Example
+
+```bash
+cd 9-sequential-agent
+adk web
+```
+
+Then select "lead_qualification_agent" from the dropdown menu in the web UI.
+
+## Example Interactions
+
+Try these example interactions:
+
+### Qualified Lead Example:
+```
+Lead Information:
+Name: Sarah Johnson
+Email: [email protected]
+Phone: 555-123-4567
+Company: Tech Innovate Solutions
+Position: CTO
+Interest: Looking for an AI solution to automate customer support
+Budget: $50K-100K available for the right solution
+Timeline: Hoping to implement within next quarter
+Notes: Currently using a competitor's product but unhappy with performance
+```
+
+### Unqualified Lead Example:
+```
+Lead Information:
+Name: John Doe
+Email: [email protected]
+Interest: Something with AI maybe
+Notes: Met at conference, seemed interested but was vague about needs
+```
+
+## How Sequential Agents Compare to Other Workflow Agents
+
+ADK offers different types of workflow agents for different needs:
+
+- **Sequential Agents**: For strict, ordered execution (like this example)
+- **Loop Agents**: For repeated execution of sub-agents based on conditions
+- **Parallel Agents**: For concurrent execution of independent sub-agents
+
+## Additional Resources
+
+- [ADK Sequential Agents Documentation](https://google.github.io/adk-docs/agents/workflow-agents/sequential-agents/)
+- [Full Code Development Pipeline Example](https://google.github.io/adk-docs/agents/workflow-agents/sequential-agents/#full-example-code-development-pipeline) 

ADK-Crash-Course/10-sequential-agent/lead_qualification_agent/.env.example

@@ -0,0 +1,2 @@
+GOOGLE_GENAI_USE_VERTEXAI=FALSE
+GOOGLE_API_KEY=your_api_key_here 

ADK-Crash-Course/10-sequential-agent/lead_qualification_agent/__init__.py

@@ -0,0 +1 @@
+from . import agent

ADK-Crash-Course/10-sequential-agent/lead_qualification_agent/agent.py

@@ -0,0 +1,21 @@
+"""
+Sequential Agent with a Minimal Callback
+
+This example demonstrates a lead qualification pipeline with a minimal
+before_agent_callback that only initializes state once at the beginning.
+"""
+
+from google.adk.agents import SequentialAgent
+
+from .subagents.recommender import action_recommender_agent
+from .subagents.scorer import lead_scorer_agent
+
+# Import the subagents
+from .subagents.validator import lead_validator_agent
+
+# Create the sequential agent with minimal callback
+root_agent = SequentialAgent(
+    name="LeadQualificationPipeline",
+    sub_agents=[lead_validator_agent, lead_scorer_agent, action_recommender_agent],
+    description="A pipeline that validates, scores, and recommends actions for sales leads",
+)

ADK-Crash-Course/10-sequential-agent/lead_qualification_agent/subagents/__init__.py

@@ -0,0 +1,3 @@
+"""Subagents for the lead qualification pipeline."""
+
+from . import recommender, scorer, validator

ADK-Crash-Course/10-sequential-agent/lead_qualification_agent/subagents/recommender/__init__.py

@@ -0,0 +1,3 @@
+"""Recommender agent for lead qualification."""
+
+from .agent import action_recommender_agent

ADK-Crash-Course/10-sequential-agent/lead_qualification_agent/subagents/recommender/agent.py

@@ -0,0 +1,36 @@
+"""
+Action Recommender Agent
+
+This agent is responsible for recommending appropriate next actions
+based on the lead validation and scoring results.
+"""
+
+from google.adk.agents import LlmAgent
+
+# --- Constants ---
+GEMINI_MODEL = "gemini-2.0-flash"
+
+# Create the recommender agent
+action_recommender_agent = LlmAgent(
+    name="ActionRecommenderAgent",
+    model=GEMINI_MODEL,
+    instruction="""You are an Action Recommendation AI.
+
+    Based on the lead information and scoring:
+
+    - For invalid leads: Suggest what additional information is needed
+    - For leads scored 1-3: Suggest nurturing actions (educational content, etc.)
+    - For leads scored 4-7: Suggest qualifying actions (discovery call, needs assessment)
+    - For leads scored 8-10: Suggest sales actions (demo, proposal, etc.)
+
+    Format your response as a complete recommendation to the sales team.
+
+    Lead Score:
+    {lead_score}
+
+    Lead Validation Status:
+    {validation_status}
+    """,
+    description="Recommends next actions based on lead qualification.",
+    output_key="action_recommendation",
+)

ADK-Crash-Course/10-sequential-agent/lead_qualification_agent/subagents/scorer/__init__.py

@@ -0,0 +1,3 @@
+"""Scorer agent for lead qualification."""
+
+from .agent import lead_scorer_agent

ADK-Crash-Course/10-sequential-agent/lead_qualification_agent/subagents/scorer/agent.py

@@ -0,0 +1,32 @@
+"""
+Lead Scorer Agent
+
+This agent is responsible for scoring a lead's qualification level
+based on various criteria.
+"""
+
+from google.adk.agents import LlmAgent
+
+# --- Constants ---
+GEMINI_MODEL = "gemini-2.0-flash"
+
+# Create the scorer agent
+lead_scorer_agent = LlmAgent(
+    name="LeadScorerAgent",
+    model=GEMINI_MODEL,
+    instruction="""You are a Lead Scoring AI.
+
+    Analyze the lead information and assign a qualification score from 1-10 based on:
+    - Expressed need (urgency/clarity of problem)
+    - Decision-making authority
+    - Budget indicators
+    - Timeline indicators
+
+    Output ONLY a numeric score and ONE sentence justification.
+
+    Example output: '8: Decision maker with clear budget and immediate need'
+    Example output: '3: Vague interest with no timeline or budget mentioned'
+    """,
+    description="Scores qualified leads on a scale of 1-10.",
+    output_key="lead_score",
+)

ADK-Crash-Course/10-sequential-agent/lead_qualification_agent/subagents/validator/__init__.py

@@ -0,0 +1,3 @@
+"""Validator agent for lead qualification."""
+
+from .agent import lead_validator_agent