tool-confirmation-hitl

tool-confirmation-hitl

Wrap dangerous or expensive tools with required confirmation. ADK 2.0 ships this as a first-class feature.

When to use

• Destructive operations (delete, drop, send_email, run_payment)
• Expensive operations (large API calls, paid model calls)
• Compliance-flagged operations (PHI access, PII export)
• Any time you want an audit trail of human approvals

Template — wrap an existing tool

from google.adk.agents import LlmAgent
from google.adk.tools import require_confirmation

def send_email(to: str, subject: str, body: str) -> dict:
    """Send an email. Requires human approval before firing.

    Args:
        to: Recipient email.
        subject: Email subject line.
        body: Email body (plain text).

    Returns:
        Dict with 'sent' bool and 'message_id' string.
    """
    # Implementation calls SES / SMTP / etc.
    return {"sent": True, "message_id": "abc123"}

guarded_send = require_confirmation(
    send_email,
    prompt_template=(
        "Approve sending email?\n"
        "  To: {to}\n"
        "  Subject: {subject}\n"
        "  Body preview: {body:.100s}\n"
    ),
)

root_agent = LlmAgent(
    name="email_assistant",
    model="gemini-2.5-flash",
    instruction="Help draft and send emails. Always preview before sending.",
    tools=[guarded_send],
)

Auto-confirmation policies

guarded = require_confirmation(
    send_email,
    auto_approve=lambda args: args["to"].endswith("@trusted-domain.com"),
)

If auto_approve returns True, the tool fires without asking — useful for whitelisting.

How it surfaces in adk web

The debug UI shows a yellow confirmation card with the prompt text and "Approve" / "Reject" buttons. Programmatic approval over A2A is also supported.

Audit logging

from google.adk.callbacks import on_tool_confirmation

@on_tool_confirmation
def log_approval(ctx, tool_name, args, decision):
    print(f"[AUDIT] {tool_name} {decision} args={args}")

Validation

• Wrap every destructive/paid tool consistently
• Prompt template includes ALL args so reviewers can decide
• Auto-approval rules are conservative (whitelist, not blacklist)
• Approval events get logged for compliance

See also

• auth-framework-config (in adk-observability-safety) for tool-level auth gates