diff --git a/python/agents/youtube-analyst/.env.example b/python/agents/youtube-analyst/.env.example new file mode 100644 index 000000000..f88f36b1a --- /dev/null +++ b/python/agents/youtube-analyst/.env.example @@ -0,0 +1,9 @@ +# Copy to `.env` in this directory and fill in values. See README for setup. + +# Vertex AI / Gemini (used when GOOGLE_GENAI_USE_VERTEXAI=1) +GOOGLE_CLOUD_PROJECT=YOUR_PROJECT_ID +GOOGLE_CLOUD_LOCATION=global +GOOGLE_GENAI_USE_VERTEXAI=1 + +# YouTube Data API v3 — create a key in Google Cloud Console and enable YouTube Data API v3 +YOUTUBE_API_KEY=YOUR_YOUTUBE_DATA_API_KEY diff --git a/python/agents/youtube-analyst/README.md b/python/agents/youtube-analyst/README.md index 7552891a0..01697febb 100644 --- a/python/agents/youtube-analyst/README.md +++ b/python/agents/youtube-analyst/README.md @@ -78,45 +78,107 @@ youtube-analyst/ ### Prerequisites - Python 3.11+ -- [uv](https://github.com/astral-sh/uv) (for dependency management) -- Google Cloud Project (with Vertex AI enabled) -- [YouTube Data API Key](https://developers.google.com/youtube/v3/getting-started) - -### Installation - -1. **Clone the repository and navigate to the agent:** - ```bash - cd python/agents/youtube-analyst - ``` - -2. **Install dependencies:** - ```bash - uv sync - ``` - -3. **Configure Environment:** - Create a `.env` file in the `youtube-analyst` directory: - ```bash - GOOGLE_CLOUD_PROJECT=your-project-id - GOOGLE_CLOUD_LOCATION=global - GOOGLE_GENAI_USE_VERTEXAI=1 - YOUTUBE_API_KEY=your-youtube-data-api-key - ``` - -## Usage - -### Running in CLI -Interact with the agent directly in your terminal: +- [uv](https://docs.astral.sh/uv/) for dependency management and packaging + - See the official [uv website](https://docs.astral.sh/uv/) for installation. + + ```bash + curl -LsSf https://astral.sh/uv/install.sh | sh + ``` + +- Google Cloud project (with Vertex AI enabled) +- [YouTube Data API key](https://developers.google.com/youtube/v3/getting-started) with YouTube Data API v3 enabled +- A local `.env` file (copy from `.env.example`) with your runtime credentials + +## Agent Starter Pack (recommended) + +Use the [Agent Starter Pack](https://goo.gle/agent-starter-pack) to scaffold a production-ready project and choose your deployment target ([Vertex AI Agent Engine](https://cloud.google.com/vertex-ai/generative-ai/docs/agent-engine/overview) or [Cloud Run](https://cloud.google.com/run)), with CI/CD and other production features. The easiest way is with [uv](https://docs.astral.sh/uv/) (one command, no venv or pip install needed): + ```bash +uvx agent-starter-pack create my-youtube-analyst -a adk@youtube-analyst +``` + +If you don't have uv yet: `curl -LsSf https://astral.sh/uv/install.sh | sh` + +The starter pack will prompt you to select deployment options and set up your Google Cloud project. + +
+Alternative: Using pip + virtual environment + +```bash +python -m venv .venv && source .venv/bin/activate # Windows: .venv\Scripts\activate +pip install --upgrade agent-starter-pack +agent-starter-pack create my-youtube-analyst -a adk@youtube-analyst +``` + +
+ +From your newly created project directory (e.g. `my-youtube-analyst`), copy the env template and configure credentials: + +```bash +cp .env.example .env +``` + +Set `GOOGLE_CLOUD_PROJECT`, `GOOGLE_CLOUD_LOCATION=global`, `GOOGLE_GENAI_USE_VERTEXAI=1`, and `YOUTUBE_API_KEY`, then run: + +```bash +cd my-youtube-analyst +uv sync --dev uv run adk run youtube_analyst ``` -### Running with Web UI -For a richer experience with interactive charts: +For the Web UI (recommended for interactive charts): + ```bash uv run adk web ``` -*Select `youtube_analyst` from the dropdown menu.* + +Then select `youtube_analyst` from the dropdown menu. + +--- + +
+Alternative: Local development (run from this sample repo) + +### Clone and install + +```bash +git clone https://github.com/google/adk-samples.git +cd adk-samples/python/agents/youtube-analyst +``` + +Stay in `python/agents/youtube-analyst` for the steps below. + +```bash +uv sync +``` + +### Configuration + +Copy the environment template and edit values: + +```bash +cp .env.example .env +``` + +Set `GOOGLE_CLOUD_PROJECT`, `GOOGLE_CLOUD_LOCATION=global`, `GOOGLE_GENAI_USE_VERTEXAI=1`, and `YOUTUBE_API_KEY`. + +### Running the agent locally + +**CLI:** + +```bash +adk run . +``` + +**ADK web UI:** + +```bash +adk web +``` + +Then select `youtube_analyst` from the dropdown. + +
## Example Interactions diff --git a/python/agents/youtube-analyst/pyproject.toml b/python/agents/youtube-analyst/pyproject.toml index b00fd22bc..559a5bf78 100644 --- a/python/agents/youtube-analyst/pyproject.toml +++ b/python/agents/youtube-analyst/pyproject.toml @@ -8,7 +8,7 @@ authors = [ { name = "Kun Wang", email = "kunwk@google.com" }, ] readme = "README.md" -requires-python = ">=3.10" +requires-python = ">=3.10,<3.13" dependencies = [ "google-adk>=0.1.0", "google-genai>=0.2.0", @@ -23,7 +23,9 @@ dependencies = [ [dependency-groups] dev = [ "pytest", + "pytest-asyncio>=0.23.0", "ruff>=0.4.6", + "agent-starter-pack>=0.14.1", ] [tool.ruff] @@ -33,5 +35,14 @@ extend = "../../../pyproject.toml" known-first-party = ["youtube_analyst"] [build-system] -requires = ["hatchling"] -build-backend = "hatchling.build" +requires = ["uv_build>=0.8.14,<0.9.0"] +build-backend = "uv_build" + +[tool.uv.build-backend] +module-root = "" + +[tool.agent-starter-pack] +example_question = "Find the top 5 videos about 'Generative AI' from the last month and plot their view counts." + +[tool.agent-starter-pack.settings] +agent_directory = "youtube_analyst" \ No newline at end of file diff --git a/python/agents/youtube-analyst/youtube_analyst/__init__.py b/python/agents/youtube-analyst/youtube_analyst/__init__.py index 636f50780..7788585d1 100644 --- a/python/agents/youtube-analyst/youtube_analyst/__init__.py +++ b/python/agents/youtube-analyst/youtube_analyst/__init__.py @@ -1,5 +1,27 @@ +# Copyright 2026 Google LLC +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. """YouTube Analyst Agent package.""" -from .agent import root_agent +import os + +import google.auth + +_, project_id = google.auth.default() +os.environ.setdefault("GOOGLE_CLOUD_PROJECT", project_id) +os.environ.setdefault("GOOGLE_CLOUD_LOCATION", "global") +os.environ.setdefault("GOOGLE_GENAI_USE_VERTEXAI", "True") + +from .agent import root_agent # noqa: E402 __all__ = ["root_agent"] diff --git a/python/agents/youtube-analyst/youtube_analyst/agent.py b/python/agents/youtube-analyst/youtube_analyst/agent.py index 2bbf1a566..fa9914e31 100644 --- a/python/agents/youtube-analyst/youtube_analyst/agent.py +++ b/python/agents/youtube-analyst/youtube_analyst/agent.py @@ -2,7 +2,6 @@ from google import genai from google.adk.agents import Agent -from google.adk.tools import load_artifacts from .common.llm import GeminiWithLocation from .config import config @@ -44,7 +43,6 @@ get_current_date_time, get_date_range, render_html, - load_artifacts, ], generate_content_config=genai.types.GenerateContentConfig( max_output_tokens=config.YOUTUBE_AGENT_MAX_OUTPUT_TOKENS,