Skip to main content
The HILA function lets you create a function that can be referenced in a task to seamlessly involve a human agent in a conversation. This is useful for handling complex queries or situations where human judgment is required. The GenerativeAgent will call the HILA function when it determines that human intervention is necessary based on the task configuration and conversation context. By using the HILA function, you can:
  • Define specific scenarios where human intervention is required.
  • Ensure that complex or sensitive issues are handled appropriately.
  • Improve customer satisfaction by providing a human touch when needed.
To create a HILA function:
  1. Create a function
  2. Define input parameters
  3. Configure “Message before sending” (optional)
  4. Set variables (Optional)
  5. Save the function
  6. Use the function in a task
  7. Handle the HILA ticket in a conversation

​
Step 1: Create a New Function

Navigate to the Functions page and click “Create Function.”
  1. Select “Human-in-the-loop agent” and click “Next: Function details”
  2. Specify the Name and Purpose of the Function
    • Function Name: Provide a concise, unique name, using underscores (e.g., get_refund_approval).
    • Function Purpose: Briefly describe what the function does (e.g., “Sends a message to the human agent to get approval for a refund request”).
      • Generative Agent uses this description to determine if/when it should call the function.

​
Step 2: Define Input Parameters (JSON)

The input parameters are the values that GenerativeAgent needs to pass when calling this function to create a HILA ticket for the human agent. Under “Input Parameters,” enter a valid JSON schema describing the required parameters. GenerativeAgent gathers the necessary information (from user messages or prior context) before calling the function.
Example Input Schema
{
  "type": "object",
  "required": [
    "customer_id",
    "issue_description",
    "refund_amount",
    "question"
  ],
  "properties": {
    "customer_id": {
      "type": "string",
      "description": "The unique identifier for the customer"
    },
    "issue_description": {
      "type": "string", 
      "description": "A detailed description of the issue that requires human intervention"
    },
    "refund_amount": {
      "type": "number",
      "description": "The amount of refund requested"
    },
    "question": {
      "type": "string",
      "description": "A question or instruction for the human agent"
    }
  }
}

​
Step 3: Message before sending

You can also configure a message that will be sent to the human agent when the HILA function is called. This message can provide context about the issue and any relevant information that the human agent may need to assist the customer effectively. This is optional, but it can help ensure that the human agent has all the necessary information to provide a timely and accurate response to the customer.

​
Step 4: Set Variables

You can optionally configure one or more reference variables:
  • Configure variables to rename or transform parameter values
  • Use Jinja2 for transformations if needed
  • Toggle “Include return variable as part of function response” to make variables immediately available
Jinja2 Templates: Use Jinja2 to transform values before transfer. For example, to convert a string boolean to a proper boolean: 
true if params.get("is_refund_eligible") == "True" else false

​
Step 5: Save Your Function

With your function defined, save it by clicking “Create Function”. After saving, you’ll see a detail page showing the JSON schema and any configured reference variables.

​
Step 6: Using the HILA function in a task

To use the HILA function, add it to the list of available functions in a task. When GenerativeAgent determines that human intervention is needed based on the task configuration and conversation context, it will call the HILA function to create a ticket for the human agent. Here’s how the HILA function works within a task and conversation flow:
  1. GenerativeAgent analyzes the user’s request and determines if it needs human intervention.
  2. (Optional) The system sends a “Message before Sending” to the human agent
  3. GenerativeAgent calls the HILA function with the appropriate parameters to create a ticket for the human agent.
# Objective
- The customer is requesting a refund for a recent purchase. 
- The refund amount exceeds the threshold for automatic approval, so human intervention is required to review and approve the refund request.

# Context
- Customer has purchased an item but is unsatisfied and requests a refund.
- The refund amount is $150, which exceeds the automatic approval limit of $100.
- The customer has provided a reason for the refund request, citing that the product was defective.

# Instructions
1. **Gather necessary information**: 
- Collect the customer's ID, a description of the issue, and the refund amount from the conversation and store them in variables for use in the HILA function. 

2. **Call the HILA function**:
- When the refund amount is detected to exceed the automatic approval limit, call the HILA function with the following parameters:
  - `question`: "A customer has requested a refund that exceeds the automatic approval limit. Please review the request and approve or deny the refund based on the provided information."
  - `customer_id`: The unique identifier for the customer.
  - `issue_description`: A detailed description of the issue that requires human intervention.
  - `refund_amount`: The amount of refund requested.

​
Step 7: Handle the HILA ticket in a conversation

When the Human agent responds to the HILA ticket, GenerativeAgent will receive the response and continue the conversation with the customer based on the human agent’s input. The human agent’s response can include instructions, approvals, or any other relevant information needed to assist the customer effectively. The response will be stored in the response parameter of the HILA function:
  • question: The original question or instruction sent to the human agent.
  • agentResponse: The response provided by the human agent after reviewing the ticket.
GenerativeAgent can then use this information to provide further assistance to the customer, such as confirming the refund approval or providing additional instructions based on the human agent’s response.

​
Next Steps

Task Best Practices

Learn more about best practices for task and function configuration.

Set Variable Functions

Learn how to store and manipulate conversation data with Set Variable Functions.

Human in the Loop Agent

Learn how to set up a Human-in-the-Loop system to seamlessly involve human agents in conversations when needed.

Previewer

Test your HILA functions in real-time with the Previewer tool.