product catalog ad generation agent update (#815)

Author: tkhouw

python/agents/product-catalog-ad-generation/README.md

@@ -4,7 +4,7 @@
 
 This project is a Personalized Ad Generation Assistant that helps marketing teams generate short-form video ads grounded in their product catalog. The agent pulls product metadata from a catalog (e.g., BigQuery), validates demographic targeting, and generates a video using product imagery and corporate branding standards. A human-in-the-loop feedback mechanism allows for iterative refinement of the generated ad.
 
-The agent is defined in `content_gen_agent/agent.py` and uses the `gemini-2.5-pro` model. It orchestrates a multi-step workflow that includes product selection, storyline generation, image and video creation, and final ad assembly, with opportunities for human feedback at key stages.
+The agent is defined in `content_gen_agent/agent.py` and uses the `gemini-3-flash-preview` model. It orchestrates a multi-step workflow that includes product selection, storyline generation, image and video creation, and final ad assembly, with opportunities for human feedback at key stages.
 
 This project contains default product imagery and a corporate logo that will get loaded into BigQuery as part of the deployment script.
 
@@ -37,6 +37,11 @@ This project contains default product imagery and a corporate logo that will get
 └── ...
 ```
 
+## Requirements
+
+Before you begin, ensure you have:
+- **Google Cloud SDK**: For GCP services - [Install](https://cloud.google.com/sdk/docs/install)
+
 ## Setup Scripts
 
 The `scripts/` directory contains a series of automation scripts to set up the necessary Google Cloud infrastructure for the project. These scripts must be run in order.
@@ -95,6 +100,8 @@ To add your own products to the system, upload your product images to the `stati
 
 ## Usage
 
+After installing dependencies, the product catalog ad generation agent can be run via the `adk web` command.
+
 The main agent orchestrates the entire ad generation workflow, which can be broken down into the following steps:
 
 1.  **Product Selection & Demographic Targeting**: The user provides a product name and desired demographic. The agent queries a BigQuery table to fetch product details and validates that the product is suitable for the target audience.
@@ -107,17 +114,17 @@ The main agent orchestrates the entire ad generation workflow, which can be brok
 
 ### Bring Your Own Asset Sheet
 
-You can provide your own "asset sheet" as long as it includes the product image you are asking for. You can do this by pasting the "GCS URI" into your chat, and the agent will take this and download it. The agent will then use that asset sheet as context to generate the storyline, and move forward through the rest of the flow. Note that this allows you to skip the "product image" upload as long as it exists in your asset sheet. The GCS URI can be from any bucket that the authenticated user has access to.
+You can provide your own "asset sheet" as long as it includes the product image you are asking for. You can either 1) upload the image directly through the ADK web UI or 2) paste the "GCS URI" of an asset sheet into your chat, and the agent will fetch it. The agent will then use your asset sheet as context to generate the storyline, and move forward through the rest of the flow. Note that this allows you to skip the "product image" upload as long as it exists in your asset sheet. The GCS URI can be from any bucket that the authenticated user has access to.
 
 ### Bring Your Own Product Photo
 
-Similarly, you can provide a direct GCS URI for a product photo instead of relying on the product selection from BigQuery. If you provide a GCS URI for the `product_photo_filename` parameter when calling the agent, it will download the image from that URI and use it as the product photo for the ad generation process.
+Similarly, you can provide a product photo either directly through the ADK web UI or as a GCS URI instead of relying on the product selection from BigQuery. If you provide a GCS URI for the `product_photo_filename` parameter when calling the agent, it will download the image from that URI and use it as the product photo for the ad generation process.
 
 ### Hardcoded Configurations
 
 The behavior of the agent is influenced by several hardcoded configurations in the `content_gen_agent` directory:
 
--   **Models**: The agent uses `gemini-2.5-pro` for storyline generation and `gemini-3-pro-image-preview` for image generation. The video generation is handled by `veo-3.1-generate-preview`, and the audio is generated using `lyria-002` and `gemini-2.5-flash-preview-tts`.
+-   **Models**: The agent uses `gemini-3-flash-preview` for storyline generation and `gemini-3-pro-image-preview` for image generation. The video generation is handled by `veo-3.1-generate-preview`, and the audio is generated using `lyria-002` and `gemini-2.5-flash-preview-tts`.  Note that some of these models may only be available in the "global" region of Google Cloud.
 -   **Company Name**: The `COMPANY_NAME` can be set in the `.env` file. If not set, it defaults to "ACME Corp". This influences the branding of the generated content.
 -   **Video Aspect Ratio**: All generated videos adhere to a `9:16` aspect ratio, suitable for short-form content platforms.
 -   **Logo**: The company logo is hardcoded in `static/uploads/branding/logo.png` and is uploaded to GCS during the `02-deploy-gcs-and-bq.sh` setup script.

python/agents/product-catalog-ad-generation/content_gen_agent/agent.py

@@ -21,7 +21,9 @@
 import os
 
 from google.adk.agents import Agent
-from google.adk.tools import FunctionTool
+from google.adk.apps import App
+from google.adk.plugins.save_files_as_artifacts_plugin import SaveFilesAsArtifactsPlugin
+from google.adk.tools import FunctionTool, load_artifacts
 
 from .func_tools.combine_video import combine
 from .func_tools.generate_audio import generate_audio_and_voiceover
@@ -31,49 +33,77 @@
 from .utils.storytelling import STORYTELLING_INSTRUCTIONS
 
 COMPANY_NAME = os.environ.get("COMPANY_NAME", "ACME Corp")
-SYSTEM_INSTRUCTION: str = f"""ROLE: You are a Personalized Ad Generation Assistant. \
-By default you are an assistant for {COMPANY_NAME}, \
+SYSTEM_INSTRUCTION: str = f"""
+ROLE: You are a Personalized Ad Generation Assistant.
+By default you are an assistant for {COMPANY_NAME},
 but the user can override your company name if they ask.
 
-**🛑 CORE RULE: NEVER execute a function or call a tool without first receiving explicit verbal confirmation to proceed.**
+**🛑 CORE RULE: NEVER execute a function or call a tool without first
+receiving explicit verbal confirmation to proceed.**
 
-TASK: Your goal is to orchestrate the generation of a short-form ad (under 15 seconds). You will use a team of specialized functions to accomplish this.
+TASK: Your goal is to orchestrate the generation of a short-form ad
+(under 15 seconds). You will use a team of specialized functions to
+accomplish this.
 
 **Workflow:**
-1. **Storyline Generation:** Use the `generate_storyline` tool to create a compelling "before and after" narrative and a detailed visual style guide.
-2. **Image Generation:** After storyline and asset sheet are generated, generate a series of consistent images for the storyboard.
-3. **Video Generation:** Use the `generate_video` tool to bring the images to life.
-4. **Audio & Voiceover Generation:** Use the `generate_audio_and_voiceover` tool to create both a catchy soundtrack and a voiceover in one step.
-5. **Final Assembly:** Use the `combine` tool to merge the video, audio, and voiceover into the final ad.
+1. **Storyline Generation:** Use the `generate_storyline` tool to create a
+   compelling "before and after" narrative and a detailed visual style guide.
+2. **Image Generation:** After storyline and asset sheet are generated,
+   generate a series of consistent images for the storyboard.
+3. **Video Generation:** Use the `generate_video` tool to bring the images to
+   life.
+4. **Audio & Voiceover Generation:** Use the `generate_audio_and_voiceover`
+   tool to create both a catchy soundtrack and a voiceover in one step.
+5. **Final Assembly:** Use the `combine` tool to merge the video, audio, and
+   voiceover into the final ad.
 
 **Guidance:**
 - Always guide the user step-by-step.
-- Before executing any tool, present the proposed inputs and **STOP** to ask for the user's confirmation.
+- Before executing any tool, present the proposed inputs and **STOP** to ask
+  for the user's confirmation.
 - Ensure all generated content adheres to a **9:16 aspect ratio**.
-- When possible, try to parallelize the video and audio generation functions upon user confirmation.
+- When possible, try to parallelize the video and audio generation functions
+  upon user confirmation.
 - Avoid generating children.
-- Each scene generated is done so in isolation. Instruct prompts as though they were each generated distinctly, with only the asset sheet as reference across scenes.
+- Each scene generated is done so in isolation. Instruct prompts as though
+  they were each generated distinctly, with only the asset sheet as reference
+  across scenes.
 
 **TOOLS:**
-- **generate_storyline**: Generates the ad's narrative and visual style guide. It can optionally accept a `style_guide` parameter to customize the visual style of the generated assets.
-- **generate_images_from_storyline**: Generates images based on the storyline and asset sheet.
-- **generate_video**: A longer async tool that generates a list of videos based on previously generated images and input prompts.
-- **generate_audio_and_voiceover**: A longer async tool that generates both a music clip and a voiceover in one step.
-- **combine**: The final step, combining video, audio, and voiceover into a single file.
+- **load_artifacts**: Call if the user uploaded a file that you're wanting to
+  pass to other tools via the Tool Context
+- **generate_storyline**: Generates the ad's narrative and visual style guide.
+  It can optionally accept a `style_guide` parameter to customize the visual
+  style of the generated assets.
+- **generate_images_from_storyline**: Generates images based on the storyline
+  and asset sheet.
+- **generate_video**: A longer async tool that generates a list of videos
+  based on previously generated images and input prompts.
+- **generate_audio_and_voiceover**: A longer async tool that generates both a
+  music clip and a voiceover in one step.
+- **combine**: The final step, combining video, audio, and voiceover into a
+  single file.
 
 {STORYTELLING_INSTRUCTIONS}
 
 """
 
 root_agent = Agent(
     name="content_generation_agent",
-    model="gemini-2.5-pro",
+    model="gemini-3-flash-preview",
     instruction=SYSTEM_INSTRUCTION,
     tools=[
+        load_artifacts,
         FunctionTool(func=generate_storyline),
         FunctionTool(func=generate_images_from_storyline),
         FunctionTool(func=combine),
         FunctionTool(func=generate_video),
         FunctionTool(func=generate_audio_and_voiceover),
     ],
 )
+
+app = App(
+    name="content_gen_agent",
+    root_agent=root_agent,
+    plugins=[SaveFilesAsArtifactsPlugin()],
+)

python/agents/product-catalog-ad-generation/content_gen_agent/func_tools/combine_video.py

@@ -251,7 +251,11 @@ async def _combine_and_upload_video(
     try:
         final_clip = concatenate_videoclips(video_clips, method="compose")
         final_clip.audio = await _load_and_process_audio_clips(
-            audio_file, voiceover_file, final_clip.duration, tool_context, temp_dir
+            audio_file,
+            voiceover_file,
+            final_clip.duration,
+            tool_context,
+            temp_dir,
         )
 
         filename = f"combined_video_{int(time.time())}.mp4"
@@ -294,7 +298,8 @@ async def combine(
         video_files (List[str]): A list of video artifact filenames.
         audio_file (str): The filename of the background audio artifact.
         num_images (int): The number of images in the storyline.
-        tool_context (ToolContext): The context for tool execution and artifact management.
+        tool_context (ToolContext): The context for tool execution and
+          artifact management.
         voiceover_file (Optional[str]): The filename of the voiceover artifact.
           Defaults to None.