Mock Tool Responses (Tool Fakes)¶

When you run simulations or evaluations with the --use-tool-fakes flag enabled, the platform bypasses the actual tool implementation and executes a pre-defined Mock Tool Response (also known as a Tool Fake).

Configuring Fakes in the Console¶

To set up a mock tool response for a tool:

1. Open your agent in the Customer Experience Agent Studio Console.
2. Navigate to the tool configuration panel (e.g., select the tool node in your flow builder, or select it from the Tools list).
3. Under the Configuration tab, scroll down to the Mock tool response section and click Use mock response.
4. In the code editor, write the python handler script for your fake tool call.

The Fake Tool Handler Signature¶

The platform expects a python function named fake_tool_call with a strict signature:

# Handler for a specific tool.
# If None is returned, the real tool is invoked.

def fake_tool_call(
    tool: Tool, 
    input: dict[str, Any], 
    callback_context: CallbackContext
) -> Optional[dict[str, Any]]:
    return {}

• tool: The tool definition object.
• input: A dictionary containing the inputs passed to the tool during the conversation.
• callback_context: The execution context (providing access to callback_context.variables for reading and writing session state variables).
• Return Value: Must return a dictionary representing the mock tool result, or None if you want execution to fall back to the real tool backend.

Example: Session-Based Mocking¶

You can inspect session variables from the callback_context to conditionally choose which mock response to return. This allows you to test multiple paths (e.g., success, failure, or customer-specific details) deterministically:

# pylint: disable=all
from typing import Any, Dict, List, Optional

# Mock data mapping based on a session key (e.g., account type or tier)
TIER_MAP = {
    "premium": {
        "status": "active",
        "benefits_summary": "Access to 24/7 dedicated support and premium lounges.",
        "discount_pct": 15.0,
    },
    "standard": {
        "status": "active",
        "benefits_summary": "Standard business hours support.",
        "discount_pct": 0.0,
    }
}

def fake_tool_call(
    tool: Tool, 
    input: dict[str, Any], 
    callback_context: CallbackContext
) -> Optional[dict[str, Any]]:
    # Read the session variable to determine the context/scenario
    customer_tier = callback_context.variables.get("customer_tier", "standard")

    if customer_tier in TIER_MAP:
        return TIER_MAP[customer_tier]

    # Return a mock failure result if tier is unrecognized
    return {"status": "FAILED", "error_code": "INVALID_TIER"}