fix(hitl): address review feedback from PR #110

- Replace datetime.utcnow() with datetime.now(timezone.utc) throughout
  (deprecated in Python 3.12+)
- Make API_BASE_URL configurable via ADK_HITL_API_URL env var
- Make poll interval configurable via ADK_HITL_POLL_INTERVAL_S env var
- Add jitter to polling loop to reduce backend traffic under
  concurrent load
- Simplify _to_pydantic() using Pydantic v2 model_validate() with
  from_attributes=True and a model_validator to handle JSON strings
- Update test_approved_tool_runs assertion to match enriched return
  dict (action_result + supervisor_decision)
- Add README.md with architecture diagram, quick start, and
  configuration reference

Author: garythomasgeorge

.pr_body.md

@@ -0,0 +1,103 @@
+## Summary
+Closes #[ISSUE NUMBER]
+Adds a production-ready Human-in-the-Loop approval gateway for Google ADK agents. This addresses a documented gap where ADK's built-in Tool Confirmation feature explicitly does not support `DatabaseSessionService` or `VertexAiSessionService` — the two session backends required for production deployments — making structured human oversight unavailable in any persistent production environment.
+
+## Problem
+ADK's Tool Confirmation (v1.14.0+) is experimental and has three blockers for production use:
+1. Does not support `DatabaseSessionService` or `VertexAiSessionService`
+2. Does not trigger inside `AgentTool` or across A2A boundaries
+3. No structured approval UI, audit trail, or persistence layer
+
+Validated by community issues: #1797, #1851, #2645, #3276, #3567 on `google/adk-python`.
+
+## Solution
+A session-agnostic HITL approval gateway that manages approval state in its own persistence layer (SQLite, with a documented path to Postgres), independent of ADK's session service. The agent resumes via ADK's standard REST API after a human decision is submitted.
+
+### What's included
+
+**Core module** (`src/google/adk_community/tools/hitl/`)
+- `gateway.py` — `hitl_tool` decorator that wraps any async function before it is passed to `FunctionTool`. Adding HITL to an existing tool takes ~5 lines.
+- `models.py` — `ApprovalRequest` Pydantic model, normalised data contract capturing agent context, payload, risk level, and audit metadata
+- `adapters/adk1.py` — ADK 1.x adapter translating `request_confirmation()` events into `ApprovalRequest` objects
+
+**Service** (`src/google/adk_community/services/hitl_approval/`)
+- `api.py` — FastAPI application
+- `routes.py` — REST endpoints for approval queue management
+- `store.py` — SQLite persistence with full audit log
+
+**Sample** (`contributing/samples/hitl_approval/`)
+- `credit_agent/agent.py` — Credit approval agent demonstrating end-to-end integration
+- `dashboard/app.py` — Reference Streamlit approval inbox UI
+- `start_servers.sh` — One-command startup for all three services
+- `requirements.txt` — Sample-only dependencies
+
+### Architecture
+```
+ADK Agent Pipeline
+      ↓
+@hitl_tool decorator (wraps async function → FunctionTool)
+      ↓ POST /approvals/ — creates ApprovalRequest
+FastAPI + SQLite (approval state)
+      ↓ serves pending approvals
+Streamlit Dashboard (reviewer decides)
+      ↓ POST /approvals/{id}/decide
+FastAPI updates status in SQLite
+      ↓ decorator polls GET /approvals/{id} every 2 s
+Agent resumes execution (wrapper unblocks; runs tool if approved)
+```
+
+### Forward compatibility
+Built with an adapter pattern so the same approval backend and dashboard work with ADK 1.x today and ADK 2.0's `RequestInput` pattern when it reaches stable — without teams needing to rebuild their approval layer on upgrade.
+
+## Testing
+### Unit tests
+All 11 tests passing:
+```text
+============================= test session starts =============================
+platform darwin -- Python 3.11.15, pytest-9.0.2, pluggy-1.6.0
+rootdir: /Users/garythomasgeorge/Desktop/Work/AI Dev/adk-python-community
+configfile: pyproject.toml
+plugins: anyio-4.12.1, asyncio-1.3.0
+asyncio: mode=Mode.AUTO, debug=False, asyncio_default_fixture_loop_scope=function, asyncio_default_test_loop_scope=function
+collected 11 items                                                                  
+
+tests/unittests/tools/test_hitl_gateway.py ......                             [ 54%]
+tests/unittests/services/test_hitl_approval_api.py .....                      [100%]
+
+================================ 11 passed in 1.76s =================================
+Exit code: 0
+```
+
+### Manual E2E
+Full end-to-end flow verified:
+- Agent triggers approval request → appears in Streamlit dashboard ✓
+- Reviewer approves in dashboard → agent resumes correctly ✓
+- Uvicorn restart → SQLite persists previous approvals ✓
+
+> 🎥 *Please drag-and-drop your `hitl_demo_video_1774318429041.webp` file here before publishing*
+
+## Testing plan
+For reviewers wanting to reproduce locally:
+```bash
+cd contributing/samples/hitl_approval
+uv pip install -r requirements.txt
+./start_servers.sh
+```
+
+Then open:
+- ADK Dev UI: `http://localhost:8080`
+- Streamlit dashboard: `http://localhost:8501`
+- FastAPI docs: `http://localhost:8000/docs`
+
+Trigger an approval by asking the credit agent to process an amount over $500.
+
+## Notes for reviewers
+- Opening as **Draft** — happy to address structural feedback before requesting full review
+- ADK 2.0 adapter (`adapters/adk2.py`) is planned as a follow-up PR once 2.0 moves toward stable
+- Confirmed structure placement from proposal issue: `tools/hitl` for the gateway and models, `services/hitl_approval` for the FastAPI backend — let me know if you'd prefer a different organisation
+
+## Related
+- Proposal issue: #[ISSUE NUMBER]
+- ADK Tool Confirmation docs (known limitations): https://google.github.io/adk-docs/tools-custom/confirmation/
+- ADK multi-agent HITL pattern reference: https://developers.googleblog.com/developers-guide-to-multi-agent-patterns-in-adk/
+- Existing community example this extends: https://github.com/jackwotherspoon/adk-human-in-the-loop

contributing/samples/hitl_approval/README.md

@@ -5,19 +5,20 @@ A drop-in **production-ready Human-in-the-Loop (HITL) approval middleware** for
 ## The Problem Solved
 
 ADK 1.x ships with an experimental `require_confirmation=True` feature that handles pausing the LLM loop for human verification. However, it is fundamentally built for local debugging and introduces major blockers to an enterprise environment:
+
 1. **Incompatible with Persistent Sessions:** Native confirmations intentionally do not serialize well and will completely fail to resume your agent if you use `DatabaseSessionService`, `SpannerSessionService`, or `VertexAiSessionService` (the mandatory session backends for production deployments).
 2. **Single-Agent Limitations:** They silently break across `AgentTool` nested bounds and true multi-agent (A2A) topologies, causing missing events or infinitely looping models.
-3. **No Resilient Audit Log:** The Native confirmation tool leaves no easily queryable paper trail linking the human supervisor to a precise LLM request.
+3. **No Resilient Audit Log:** The native confirmation tool leaves no easily queryable paper trail linking the human supervisor to a precise LLM request.
 
-*This project is the production implementation of the HITL pattern covered in the [ADK Multi-Agent Patterns Guide (Advent of Agents Day 13)](#).*
+*This project is the production implementation of the HITL pattern covered in the [ADK Multi-Agent Patterns Guide (Advent of Agents Day 13)](https://medium.com/@garythomasgeorge/why-google-adks-human-in-the-loop-story-has-a-production-gap-and-one-way-it-could-be-fixed-66aabef33a32).*
 
 ## What This Library Provides
 
 This project solves the production gaps by explicitly decoupling the human approval payload from ADK's internal session memory. It introduces a session-agnostic REST API layer using an Adapter pattern.
 
 ### The 3-Layer Architecture
 
-```text
+```
 ┌─────────────────────────────────────────┐
 │     Dashboard UI (Streamlit)            │  Layer 3: Demo/reference UI
 │     Approval inbox, audit log viewer    │  (Easily replaced by Zendesk/etc.)
@@ -37,24 +38,42 @@ This project solves the production gaps by explicitly decoupling the human appro
 
 By retaining HITL state inside an independent FastAPI engine and SQLite database, an active agent can pause safely. When a human supervisor hits "Approve" inside a centralized web portal hours later, the middleware simply posts the decision back into the agent's `/run_sse` stream seamlessly.
 
+## Configuration
+
+| Environment Variable | Default | Description |
+|---|---|---|
+| `ADK_HITL_API_URL` | `http://localhost:8000` | URL of the HITL approval FastAPI backend. Override for Cloud Run or any remote deployment. |
+| `ADK_HITL_POLL_INTERVAL_S` | `2.0` | Base polling interval in seconds. Up to 1s of random jitter is added automatically to reduce backend traffic under concurrent load. |
+
+Set these before starting the gateway:
+
+```bash
+export ADK_HITL_API_URL="https://your-hitl-service.run.app"
+export ADK_HITL_POLL_INTERVAL_S="3.0"
+```
+
 ## Quick Start (Local Sandbox)
 
 We have provided a demo customer service agent (`credit_agent`) alongside a launch script to test the interaction end-to-end.
 
-1. Create your python virtual environment and sync dependencies using `uv` (requires Python 3.11+):
-   ```bash
-   uv venv --python "python3.11" ".venv"
-   source .venv/bin/activate
-   uv sync --all-extras
-   ```
+1. Create your Python virtual environment and sync dependencies using `uv` (requires Python 3.11+):
+
+```bash
+uv venv --python "python3.11" ".venv"
+source .venv/bin/activate
+uv sync --all-extras
+```
+
 2. Start the FastAPI backend, Streamlit dashboard, and ADK Live Chat agent all at once:
-   ```bash
-   ./start_servers.sh
-   ```
+
+```bash
+./start_servers.sh
+```
+
 3. Open `http://localhost:8080` to chat with the agent and ask for a $75 account credit.
 4. When the agent pauses and asks for a supervisor, open `http://localhost:8501` to approve or reject the request.
 
-## How to use in your own ADK application
+## How to Use in Your Own ADK Application
 
 Wrapping an ADK agent with a formal enterprise HITL checkpoint takes under 5 lines of code:
 
@@ -69,7 +88,7 @@ from google.adk_community.tools.hitl.gateway import hitl_tool
 # 1. Wrap your function with the decorator
 @hitl_tool(agent_name="my_billing_agent")
 async def issue_refund(user_id: str, amount: float):
-    # This block won't execute until explicitly approved inside the FastAPI dashboard
+    # This block won't execute until explicitly approved in the dashboard
     return {"status": "success", "amount_refunded": amount}
 
 # 2. Attach to ADK Agent
@@ -82,10 +101,11 @@ root_agent = Agent(
 ## Production Integration Strategies
 
 This repository acts as the production baseline for a contact center or enterprise orchestration grid. Once deployed to staging, consider swapping out:
-* **Storage Layer:** Replace the local `SQLite` engine in `app/api/store.py` with `PostgreSQL` or `Cloud Spanner`.
-* **Proactive Notification:** Hook the FastAPI `POST /approvals/` route into Slack, PagerDuty, or Microsoft Teams to actively ping channels when a high-risk request pops up.
-* **Remove Streamlit:** Bypass the Streamlit frontend completely and point your existing support portal interface (like Salesforce Service Cloud) directly to `GET /approvals/pending` and `POST /approvals/{id}/decide`.
+
+- **Storage Layer:** Replace the local `SQLite` engine in `app/api/store.py` with `PostgreSQL` or `Cloud Spanner`.
+- **Proactive Notification:** Hook the FastAPI `POST /approvals/` route into Slack, PagerDuty, or Microsoft Teams to actively ping channels when a high-risk request pops up.
+- **Remove Streamlit:** Bypass the Streamlit frontend completely and point your existing support portal interface (like Salesforce Service Cloud) directly to `GET /approvals/pending` and `POST /approvals/{id}/decide`.
 
 ## ADK 2.0 Compatibility
 
-This project currently uses ADK 1.x conventions and event triggers. Because it strictly implements an `adapters` layer, all the Pydantic API schemas and Streamlit logic are completely forward-compatible with ADK 2.0 `RequestInput` workflow yielding. You'll simply need to switch the adapter layer translation once ADK 2.0 exits Alpha.
+This project currently uses ADK 1.x conventions and event triggers. Because it strictly implements an `adapters` layer, all the Pydantic API schemas and Streamlit logic are completely forward-compatible with ADK 2.0 `RequestInput` workflow yielding. You'll simply need to switch the adapter layer translation once ADK 2.0 exits Alpha. The `ADK_HITL_API_URL` and `ADK_HITL_POLL_INTERVAL_S` environment variables remain valid across both adapter versions.

contributing/samples/hitl_approval/credit_agent/.adk/session.db

@@ -138,25 +138,4 @@ async def _get_or_404(request_id: str, db: AsyncSession) -> ApprovalRequestDB:
 
 
 def _to_pydantic(db_item: ApprovalRequestDB) -> ApprovalRequest:
-    return ApprovalRequest(
-        id=db_item.id,
-        session_id=db_item.session_id,
-        invocation_id=db_item.invocation_id,
-        function_call_id=db_item.function_call_id,
-        app_name=db_item.app_name,
-        user_id=db_item.user_id,
-        agent_name=db_item.agent_name,
-        tool_name=db_item.tool_name,
-        message=db_item.message,
-        payload=json.loads(db_item.payload) if db_item.payload else {},
-        response_schema=json.loads(db_item.response_schema)
-        if db_item.response_schema
-        else {},
-        risk_level=db_item.risk_level,
-        status=db_item.status,
-        created_at=db_item.created_at,
-        decided_at=db_item.decided_at,
-        decided_by=db_item.decided_by,
-        decision_notes=db_item.decision_notes,
-        escalated_to=db_item.escalated_to,
-    )
+    return ApprovalRequest.model_validate(db_item)

contributing/samples/hitl_approval/hitl.db

@@ -37,10 +37,13 @@ async def apply_credit(account_id: str, amount: float) -> str:
 from typing import Any, Callable, Optional
 
 import httpx
+import os
+import random
 
-API_BASE_URL = "http://localhost:8000"
-POLL_INTERVAL_S = 2.0
-POLL_TIMEOUT_S = 300.0  # 5 minutes
+API_BASE_URL = os.getenv("ADK_HITL_API_URL", "http://localhost:8000")
+POLL_INTERVAL_S = float(os.getenv("ADK_HITL_POLL_INTERVAL_S", "2.0"))
+POLL_JITTER_S = 1.0
+POLL_TIMEOUT_S = 300.0  # ← this one was likely removed accidentally
 
 
 def hitl_tool(
@@ -138,7 +141,7 @@ async def _poll_for_decision(
             data = resp.json()
             if data["status"] != "pending":
                 return data
-            await asyncio.sleep(interval)
+            await asyncio.sleep(POLL_INTERVAL_S + random.uniform(0, POLL_JITTER_S))
     return None
 
 

hitl.db

@@ -14,11 +14,12 @@
 
 from __future__ import annotations
 
-import uuid
-from datetime import datetime
+import uuid, json
+from datetime import datetime, timezone
 from typing import Any, Optional
 
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+import json     
 
 
 class ApprovalStatus:
@@ -36,6 +37,7 @@ class RiskLevel:
 
 
 class ApprovalRequest(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
     # Identity
     id: str = Field(default_factory=lambda: str(uuid.uuid4()))
 
@@ -58,14 +60,48 @@ class ApprovalRequest(BaseModel):
 
     # Status tracking
     status: str = ApprovalStatus.PENDING
-    created_at: datetime = Field(default_factory=datetime.utcnow)
+    created_at: datetime = Field(
+        default_factory=lambda: datetime.now(timezone.utc)
+    )
     decided_at: Optional[datetime] = None
     decided_by: Optional[str] = None
     decision_notes: Optional[str] = None
-
     # Escalation
     escalated_to: Optional[str] = None
+    
+    @model_validator(mode="before")
+    @classmethod
+    def _parse_json_strings(cls, values):
+        """
+        When constructing from an ORM object, SQLite stores payload
+        and response_schema as JSON strings. Parse them to dicts
+        for Pydantic without mutating the original ORM object.
+        """
+        # Handle dict input (normal Pydantic construction)
+        if isinstance(values, dict):
+            for field in ("payload", "response_schema"):
+                val = values.get(field)
+                if isinstance(val, str):
+                    try:
+                        values[field] = json.loads(val)
+                    except (ValueError, TypeError):
+                        values[field] = {}
+            return values
 
+        # Handle ORM object input (from_attributes path)
+        # Build a plain dict from the ORM object attributes
+        # so we never mutate the SQLAlchemy-tracked object
+        data = {}
+        for column in values.__table__.columns:
+            val = getattr(values, column.name, None)
+            if column.name in ("payload", "response_schema") and isinstance(val, str):
+                try:
+                    data[column.name] = json.loads(val)
+                except (ValueError, TypeError):
+                    data[column.name] = {}
+            else:
+                data[column.name] = val
+        return data
 
 class ApprovalDecision(BaseModel):
     decision: str  # approved / rejected / escalated

src/google/adk_community/services/hitl_approval/routes.py

@@ -84,7 +84,9 @@ def add(a: int, b: int) -> int:
         return a + b
 
     result = await add(2, 3)
-    assert result == 5
+    assert result["action_result"] == 5
+    assert result["supervisor_decision"] == "APPROVED"
+    assert result["supervisor_notes"] == "No notes provided."
 
 
 @pytest.mark.asyncio