@telnyx/ai-agent-widget 0.33.6 → 0.33.8-beta.0

package/README.md

@@ -168,15 +168,68 @@ The widget emits DOM CustomEvents that you can listen to for tracking analytics,
 
 ### Available Events
 
-| Event                      | Description                                       | Detail                                                   |
-| -------------------------- | ------------------------------------------------- | -------------------------------------------------------- |
-| `agent.connected`          | Agent connected to platform                       | -                                                        |
-| `agent.disconnected`       | Agent disconnected from platform                  | -                                                        |
-| `agent.error`              | Error occurred                                    | `{ message, name }`                                      |
-| `transcript.item`          | Transcript message received                       | `{ id, role, content, timestamp, attachments? }`         |
-| `conversation.update`      | Conversation state updated                        | `{ type, callState }`                                    |
-| `conversation.agent.state` | Agent state changed (listening/speaking/thinking) | `{ state, userPerceivedLatencyMs?, thinkingStartedAt? }` |
-| `agent.audio.mute`         | Agent audio muted/unmuted                         | `{ muted }`                                              |
+| Event                      | Description                                          | Detail                                                   |
+| -------------------------- | ---------------------------------------------------- | -------------------------------------------------------- |
+| `agent.connected`          | Agent connected to platform                          | -                                                        |
+| `agent.disconnected`       | Agent disconnected from platform                     | -                                                        |
+| `agent.error`              | Error occurred                                       | `{ message, name }`                                      |
+| `transcript.item`          | Transcript message received                          | `{ id, role, content, timestamp, attachments? }`         |
+| `conversation.update`      | Conversation state updated                           | `{ type, callState }`                                    |
+| `conversation.agent.state` | Agent state changed (listening/speaking/thinking)    | `{ state, userPerceivedLatencyMs?, thinkingStartedAt? }` |
+| `agent.audio.mute`         | Agent audio muted/unmuted                            | `{ muted }`                                              |
+| `client.tool.invoked`      | A client-side tool was invoked by the agent          | `{ callId, toolName }`                                   |
+| `client.tool.completed`    | A client-side tool produced an output for the agent  | `{ callId, toolName, isError }`                          |
+| `client.tool.error`        | A client-side tool failed; a safe error was returned | `{ callId, toolName, reason }`                           |
+
+## Client-side Tools
+
+The widget can execute **client-side tools** requested by the AI agent (for
+example, looking something up in the page, reading local state, or triggering a
+UI action) and return the result to the agent. This implements the PR-531
+`client_side_tool` flow on top of [`@telnyx/ai-agent-lib`](https://www.npmjs.com/package/@telnyx/ai-agent-lib).
+
+Because tool handlers are JavaScript functions, they cannot be passed as HTML
+attributes. Instead, register them **imperatively** on the widget element:
+
+```html
+<telnyx-ai-agent agent-id="assistant-xxx"></telnyx-ai-agent>
+
+<script>
+  const widget = document.querySelector('telnyx-ai-agent');
+
+  // Register a handler. `args` is the parsed JSON arguments object the agent
+  // sent; return any JSON-serializable value (or a string) as the result.
+  widget.registerClientTool('get_cart_total', async (args, context) => {
+    // context = { callId, toolName, rawArguments }
+    return { total: 42.5, currency: 'USD' };
+  });
+
+  // Inspect or remove handlers later:
+  widget.getClientTools(); // ['get_cart_total']
+  widget.unregisterClientTool('get_cart_total'); // true
+
+  // Observe execution via DOM events (payloads never include raw
+  // arguments/outputs — only safe correlation fields):
+  widget.addEventListener('client.tool.invoked', (e) =>
+    console.log('tool invoked', e.detail),
+  );
+  widget.addEventListener('client.tool.completed', (e) =>
+    console.log('tool completed', e.detail),
+  );
+  widget.addEventListener('client.tool.error', (e) =>
+    console.warn('tool error', e.detail),
+  );
+</script>
+```
+
+Notes:
+
+- Register handlers as early as you like — registrations are durable and are
+  automatically re-applied across the widget's internal reconnects.
+- The library always returns a `function_call_output` to the agent (a safe
+  error payload on unknown tool, invalid arguments, handler throw, or timeout),
+  so a missing or failing handler never hangs the conversation.
+- Raw tool arguments and outputs are never logged.
 
 ## Development