This sample is an Agent Development Kit (ADK) multi-agent workflow that helps optimize retail product titles for brand search performance.

• Finds high-value keywords for a brand from product catalog data in BigQuery.
• Searches a target website using browser tooling.
• Compares top search results with your product data.
• Recommends title improvements to reduce zero/low-result search outcomes.

The root agent routes work to specialized sub-agents:

• keyword_finding: extracts relevant brand keywords.
• search_results: navigates and analyzes search result pages.
• comparison: compares candidate titles and proposes improvements.

• Python 3.12+
• uv installed: https://docs.astral.sh/uv/
• Google Cloud project access
• Application Default Credentials:

gcloud auth application-default login

1. Clone the repository and open this agent directory:

git clone https://github.com/google/adk-samples.git
cd adk-samples/python/agents/brand-search-optimization

2. Create your environment file:

cp .env.example .env

3. Sync dependencies:

uv sync --dev

4. (Optional) Populate sample BigQuery data:

uv run python -m deployment.bq_populate_data

CLI mode:

uv run adk run brand_search_optimization

Web UI mode:

uv run adk web

Then select brand-search-optimization from the app dropdown.

uv run adk eval brand_search_optimization eval/data/eval_data1.evalset.json --config_file_path eval/data/test_config.json

Run tests with warnings enabled:

uv run pytest -s -W default

Run Ruff checks and formatting:

uv run ruff check . --fix
uv run ruff format .

Run mypy:

uv run mypy .

uv sync --group deployment
uv run python deployment/deploy.py --create

For a post-deploy validation flow, see deployment/test_deployment.py.

Environment variables are documented in .env.example.

Important variables:

• GOOGLE_CLOUD_PROJECT
• GOOGLE_CLOUD_LOCATION
• GOOGLE_GENAI_USE_VERTEXAI
• MODEL
• DATASET_ID
• TABLE_ID
• DISABLE_WEB_DRIVER
• STAGING_BUCKET

See tests/example_interaction.md for a full sample session.

This sample is for educational and prototyping use. It is not production hardened and should be reviewed, tested, and secured before production deployment.