Client Tools

Learn how to trigger client-side events from an agent.

Enhance your conversational AI agents by integrating client-side events that can trigger actions on the user’s frontend. Unlike server-side webhooks, client tools operate directly in the user’s browser, allowing agents to perform actions like opening modals, making API calls, or executing custom functions during conversations.

What You’ll Need

Creating Your First Client-Side Event

Follow these steps to set up a client-side event that triggers a browser alert.

1

Create a new tool in your agent

  1. Navigate to your agent dashboard.
  2. In the Tools section, click Add Tool.
Creating a new tool in the agent
2

Configure the tool

  • Name: triggerBrowserAlert
  • Description: Triggers a real-time alert in the user’s browser. Use this tool for urgent notifications, reminders, or time-sensitive updates that require immediate user action.
  • Parameters:
    • message (string): The message to display in the alert. The LLM should extract relevant text from the conversation, ensuring it is actionable and concise.
3

Implement the client tool in your code

Depending on your development environment, add the following code to integrate the client tool.

1from elevenlabs import ElevenLabs
2from elevenlabs.conversational_ai.conversation import Conversation, ClientTools
3client_tools = ClientTools()
4def trigger_browser_alert(parameters):
5    message = parameters.get("message")
6    print(f"Triggering alert: {message}")
7    return "Alert triggered successfully"
8client_tools.register("triggerBrowserAlert", trigger_browser_alert)
9# Initialize conversation
10conversation = Conversation(
11    client=ElevenLabs(api_key="your-api-key"),
12    agent_id="your-agent-id",
13    client_tools=client_tools,
14    # ... other configurations ...
15)
16# Start the conversation
17conversation.start_session()
  • Ensure that the clientTools name (triggerBrowserAlert) matches the tool name you set in the agent configuration.
  • The message parameter should align with the agent’s output.
4

Test the client-side event

Initiate a conversation with your agent and say something like:

“Trigger an alert that says ‘Hello World‘“

You should see a browser alert pop up with the message.

Browser alert triggered by client tool

Next Steps

Now that you’ve set up a basic client-side event, you can:

  • Explore more complex client tools like opening modals, navigating to pages, or interacting with the DOM.
  • Combine client tools with server-side webhooks for full-stack interactions.
  • Use client tools to enhance user engagement and provide real-time feedback during conversations.

Troubleshooting

  • Ensure that the tool name in your code matches exactly with the tool name in the agent configuration. - Check that the agent is correctly outputting the tool command in the conversation. - Verify there are no typos in the parameter names.
  • Open the browser console to check for any errors. - Ensure that your code has necessary error handling for undefined or unexpected parameters.
Built with