Skip to main content

Lab 13: Building a Secure Agent with HITL and Actions

Goal​

In this lab, you will build a Secure Finance Agent. You will learn how to implement Human-in-the-Loop (HITL) for sensitive transactions and how to use tool_context.actions to dynamically escalate a conversation to a supervisor node.

Step 1: Prepare the Project​

Environment setup:

  • Local machine: If you're continuing the course in sequence, cd into the adk-training project you created in Module 2 and skip the block below -- your environment and dependencies already carry forward. If you're starting fresh at this module, create that project first: 
    uv init adk-training --python 3.10 && cd adk-training
    uv add "google-adk>=2.1.0" python-dotenv
  • DevContainer / Codespaces (Alternative): If you opened this repository in a DevContainer or GitHub Codespaces, Python, uv, and the core ADK dependencies are already pre-installed in your container environment.
uv run adk create secure_finance
cd secure_finance

Step 2: Implement the Secure Tools​

Exercise: Create tools/finance.py. You will implement a tool that handles investments.

# In tools/finance.py
from google.adk.tools import ToolContext

def execute_investment(amount: float, tool_context: ToolContext) -> str:
    """
    Executes a long-term investment.
    Use this tool only when the user explicitly asks to 'invest' or 'buy'.
    """
    # 1. Check for escalation: Any amount > 10,000 needs a human supervisor
    if amount > 10000:
        # TODO: Set tool_context.actions.transfer_to_agent to "supervisor"
        # Hint: This will dynamically route the user to a different node.
        pass
        return f"Amount ${amount} requires supervisor approval. Escalating..."

    # 2. Regular investment logic
    return f"Success! ${amount} has been invested in your portfolio."

Step 3: Configure the Agent with HITL​

Exercise: Open agent.py. You need to wrap your tool in a FunctionTool to enable the confirmation pop-up.

# In agent.py
from google.adk import Agent, Workflow
from google.adk.tools import FunctionTool
from .tools.finance import execute_investment

# --- 1. Define the Supervisor Node ---
supervisor = Agent(
    name="supervisor",
    model="gemini-3.5-flash",
    instruction="You are a senior supervisor. Review the large investment request and provide a final verdict."
)

# --- 2. Wrap the Tool for Safety ---
# TODO: Create a FunctionTool named 'secure_investment_tool'
# Enable require_confirmation=True
secure_investment_tool = ...

# --- 3. Define the Main Agent ---
finance_agent = Agent(
    name="finance_agent",
    model="gemini-3.5-flash",
    instruction="Help users with their investments. Use 'execute_investment' for trades.",
    tools=[secure_investment_tool],
    sub_agents=[supervisor] # Required for discovery during transfer
)

# --- 4. Build the Workflow Graph ---
root_agent = Workflow(
    name="SecureSystem",
    edges=[("START", finance_agent)]
)

Step 4: Test the Secure Workflow​

  1. Start the Dev UI: uv run adk web .
  2. Test HITL:
    • Ask: "Invest $500 for me."
    • Observe: A confirmation box should appear. The code only runs if you click "Approve."
  3. Test Dynamic Transfer:
    • Ask: "Invest $50,000 for me."
    • Observe: Since require_confirmation=True wraps the tool unconditionally, you will see the same confirmation pop-up as above first — click "Approve" to let the tool actually run. Only then does the escalation logic inside execute_investment fire. In the Trace, you will see the active_agent change from finance_agent to supervisor.

Lab Summary​

You have built a production-ready secure agent! You learned:

  • How to pause execution for human approval using require_confirmation.
  • How to reroute the conversation dynamically using tool_context.actions.transfer_to_agent.
  • How to combine manual safety (HITL) with automated business rules (Escalation).

Self-Reflection Questions​

  • Why is it important to use require_confirmation for sensitive actions rather than just relying on the LLM's instructions?
  • In the dynamic transfer example, why did we need to add the supervisor agent to the sub_agents list of the finance_agent?
  • How does tool_context.actions allow you to implement business rules that the LLM cannot override?

🔐 Reference Solution Vault​

🔐

Module 13 Reference Solution Vault

Active Comprehension Gate • Zero Guessable URLs • Guided Verification

Step 1/3: Question 1 of 3

In Module 13 (Tool Context), what is the primary role of context parameters in ADK architectures?