Add Gmail delivery to HN briefing agent

Author: Shubhamsaboo

always_on_agents/always_on_hn_briefing_agent/README.md

@@ -2,9 +2,9 @@
 
 AgentScout is an always-on Hacker News briefing agent built with Google ADK. It scans Hacker News for high-signal stories about AI agents, MCP, coding agents, workflow automation, and LLM apps, then turns the best links into a concise engineering brief.
 
-The app can run as an interactive ADK agent or as a scheduled backend service. Use ADK Web to ask for a brief manually, or run the FastAPI scheduler hook so Cloud Scheduler can trigger a daily Hacker News briefing and send the rendered payload to email, Slack, Linear, Jira, or an internal digest workflow.
+The app can run as an interactive ADK agent or as a scheduled backend service. Use ADK Web to ask for a brief manually, or run the FastAPI scheduler hook so Cloud Scheduler can trigger a daily Hacker News briefing and send it through Gmail, Slack, Linear, Jira, or an internal digest workflow.
 
-![Always-on Hacker News Briefing Agent architecture](assets/agent-scout-architecture.svg)
+![Always-on Hacker News Briefing Agent architecture](assets/always-on-hn-briefing-agent.png)
 
 ## Features
 
@@ -13,7 +13,8 @@ The app can run as an interactive ADK agent or as a scheduled backend service. U
 - **Brief generation**: Produces a clean text and HTML briefing with summaries, links, and next actions.
 - **Google ADK agent**: Exposes a `root_agent` so users can request briefs in ADK Web.
 - **Scheduler-ready backend**: Includes HTTP and Pub/Sub endpoints for Cloud Scheduler or other automation systems.
-- **Safe delivery flow**: Defaults to dry-run mode and only posts to a webhook when `dry_run=false`.
+- **Gmail and webhook delivery**: Sends briefs through Gmail API or a generic webhook when `dry_run=false`.
+- **Safe delivery flow**: Defaults to dry-run mode and skips delivery unless credentials are explicitly configured.
 
 ## How It Works
 
@@ -22,13 +23,14 @@ The app can run as an interactive ADK agent or as a scheduled backend service. U
 3. It ranks the most useful stories for engineers and product builders.
 4. It renders a daily briefing in text and HTML.
 5. ADK Web, an HTTP trigger, or a Pub/Sub push endpoint returns the result.
-6. If delivery is enabled, the scheduler API posts the brief to `AGENTSCOUT_WEBHOOK_URL`.
+6. If delivery is enabled, the scheduler API sends the brief through Gmail or posts it to `AGENTSCOUT_WEBHOOK_URL`.
 
 ## Requirements
 
 - Python 3.10+
-- Gemini API key for Google ADK
-- Optional webhook URL for scheduled delivery
+- Gemini API key for ADK Web
+- Optional Gmail OAuth credentials for direct email delivery
+- Optional webhook URL for Slack, Linear, Jira, GitHub Issues, SendGrid, or internal workflows
 
 ## Installation
 
@@ -39,7 +41,9 @@ pip install -r requirements.txt
 export GOOGLE_API_KEY="your_gemini_api_key"
 ```
 
-## Run in ADK Web
+## Option 1: Run in ADK Web
+
+Use ADK Web when you want to chat with the agent and ask for a brief manually.
 
 ```bash
 adk web .
@@ -61,37 +65,81 @@ Scout the top 3 Hacker News stories about AI agents and LLM apps.
 Show me the highest-signal Hacker News items about MCP, coding agents, and workflow automation.
 ```
 
-## Run the Scheduler API
+## Option 2: Run the Scheduler API Locally
+
+Use the scheduler API when you want AgentScout to run like an always-on backend service. This is the same surface you can deploy behind Cloud Run and trigger from Cloud Scheduler.
 
 Start the scheduler backend:
 
 ```bash
 uvicorn scheduler_api:app --host 0.0.0.0 --port 8000
 ```
 
-Preview a scheduled run without delivery:
+In another terminal, preview a scheduled run without delivery:
 
 ```bash
 curl "http://127.0.0.1:8000/agent-scout/dry-run?top_n=3&live=false"
 ```
 
-Trigger the scheduler path:
+Trigger the scheduler path in dry-run mode:
 
 ```bash
 curl -X POST "http://127.0.0.1:8000/agent-scout/trigger" \
   -H "Content-Type: application/json" \
   -d '{"dry_run": true, "top_n": 5, "live": false}'
 ```
 
-Enable live Hacker News scanning:
+Dry-run mode returns the rendered brief and delivery status, but it does not send anything.
+
+Enable live Hacker News scanning for the current process:
 
 ```bash
 export AGENTSCOUT_LIVE_HN=true
 ```
 
-Enable webhook delivery:
+You can also override live mode per request:
 
 ```bash
+curl -X POST "http://127.0.0.1:8000/agent-scout/trigger" \
+  -H "Content-Type: application/json" \
+  -d '{"dry_run": true, "top_n": 5, "live": true}'
+```
+
+## Option 3: Enable Scheduled Delivery
+
+Delivery is opt-in. AgentScout will not send email or call a webhook unless the request body includes `"dry_run": false` and one delivery method is configured.
+
+Delivery mode behavior:
+
+- `AGENTSCOUT_DELIVERY=gmail` sends through Gmail API.
+- `AGENTSCOUT_DELIVERY=webhook` posts to `AGENTSCOUT_WEBHOOK_URL`.
+- If `AGENTSCOUT_DELIVERY` is not set, AgentScout uses Gmail when Gmail is fully configured, otherwise webhook when a webhook URL is configured.
+
+### Gmail Delivery
+
+Use Gmail when you want AgentScout to send the daily brief directly to an inbox. Create a Google OAuth client with Gmail API access, generate a refresh token with the `https://www.googleapis.com/auth/gmail.send` scope, then set:
+
+```bash
+export AGENTSCOUT_DELIVERY="gmail"
+export AGENTSCOUT_EMAIL_TO="you@example.com"
+export AGENTSCOUT_EMAIL_FROM="you@example.com"
+export AGENTSCOUT_GMAIL_CLIENT_ID="your_google_oauth_client_id"
+export AGENTSCOUT_GMAIL_CLIENT_SECRET="your_google_oauth_client_secret"
+export AGENTSCOUT_GMAIL_REFRESH_TOKEN="your_gmail_refresh_token"
+
+curl -X POST "http://127.0.0.1:8000/agent-scout/trigger" \
+  -H "Content-Type: application/json" \
+  -d '{"dry_run": false, "top_n": 5, "live": true}'
+```
+
+AgentScout sends a multipart email with both plain text and HTML versions of the brief.
+
+### Webhook Delivery
+
+Use webhook delivery when you want to route the brief to Slack, Linear, Jira, GitHub Issues, SendGrid, or your own internal workflow.
+
+```bash
+export AGENTSCOUT_DELIVERY="webhook"
 export AGENTSCOUT_WEBHOOK_URL="https://example.com/agent-brief-webhook"
 export AGENTSCOUT_WEBHOOK_TOKEN="optional_bearer_token"
 
@@ -104,7 +152,7 @@ The webhook receives `subject`, `text`, `html`, `stories`, and `next_actions`.
 
 ## Cloud Scheduler Hook
 
-Deploy the scheduler API behind Cloud Run or another HTTP service, then call one of these endpoints from Cloud Scheduler.
+Deploy the scheduler API behind Cloud Run or another HTTP service, configure Gmail or webhook delivery in that environment, then call one of these endpoints from Cloud Scheduler.
 
 Direct HTTP trigger:
 
@@ -122,6 +170,8 @@ Request body:
 }
 ```
 
+Set `dry_run` to `true` while testing the schedule. Set it to `false` only after Gmail or webhook delivery is configured.
+
 Recommended weekday briefing schedule:
 
 ```text