RPC tool
Use send_rpc_request to let an Assistant perform actions in your WebRTC client during a conversation.
Overview
The tool sends a Remote Procedure Call, or RPC, to the connected WebRTC client through LiveKit and returns the response string to the LLM.
You configure the RPC method, timeout, and payload schema through a configuration object when attaching the tool to an Assistant.
WebRTC only
This tool is available only in WebRTC sessions. It is excluded from SIP sessions, including when the same Assistant handles both connection types.
Naming and describing the tool
Set nameOverride and descriptionOverride to describe the action your client performs. The LLM sees these values in the tool schema and uses them to decide when to call the tool.
| Field | Type | Required | LLM-facing | Description |
|---|---|---|---|---|
nameOverride | string | No | Yes | Replaces the tool's function name as seen by the LLM. Should read like a function name. |
descriptionOverride | string | No | Yes | Replaces the tool's description as seen by the LLM. Should explain when and why to call it. |
Writing effective overrides
The nameOverride should read like a function name: short, lowercase with underscores, and descriptive of the action (update_cart, lock_screen, submit_order). Avoid generic names like do_action or call_rpc.
In descriptionOverride, state when to call the tool and what result to expect.
Example:
Code
Where to set overrides
nameOverride and descriptionOverride are set at the tool-association level (alongside assistantId, definitionId, and configuration). They are not part of the configuration object itself.
Configuration schema
The configuration object you provide when attaching the tool to an Assistant accepts the following fields.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
method | string | Yes | RPC method name (e.g. "updateCart"). Also used as the default tool name. | |
timeout | number | No | 10 | Response timeout in seconds. |
message | string | No | Text the agent vocalises while the RPC runs. The tool waits for both the response and playback. Supports {variable} resolution. | |
payloadSchema | JSON Schema | No | Describes the RPC payload. Properties become the LLM-facing tool parameters. | |
responseSchema | JSON Schema or string | No | Describes the expected response structure. Appended to the LLM-facing tool description so the model can interpret responses reliably. |
Example:
Code
Payload schema
Define payloadSchema with JSON Schema keywords such as type, properties, and required. Its properties become the tool parameters that the LLM supplies.
Defining parameters
Each property in payloadSchema.properties becomes a parameter the LLM can populate from the conversation. Use description fields to guide the model on what values to extract, and required to mark parameters that must be present for the RPC to succeed.
Code
When no payloadSchema is provided, the tool takes no arguments and sends an empty {} payload to the client.
Resulting LLM-facing tool
For the payload above with descriptionOverride = "Updates the shopping cart. Use when the user wants to add or remove items.", no nameOverride, and no responseSchema, the LLM-facing tool schema becomes:
Code
Response schema
Set responseSchema to describe the response fields the LLM should expect. The platform appends it to the tool description under "Response format:". Without it, the model receives the response string without a description of its structure.
JSON schema format
Provide a standard JSON Schema object describing the response structure:
Code
Description only
responseSchema describes the response but does not validate or transform it. The tool returns the response string, truncated after 5,000 characters when necessary.
Dynamic variables
Use {variable} placeholders in string values anywhere in configuration. The platform resolves them from variables and injected data when loading the configuration, before building the tool.
Reference injected data with the key userFirstName in configuration.message:
Code
Unresolved variables
An unresolved {variable} placeholder becomes an empty string. The tool still attempts the RPC with the resulting configuration.
Limitations
| Constraint | Limit |
|---|---|
| Connection type | WebRTC only. The tool is not registered for Assistants using a SIP Channel. |
| Response size | Truncated at 5 000 characters. |
| Default timeout | 10 seconds. Configurable via the timeout field. |
| Payload format | JSON only. Arguments are serialised with json.dumps. |
| No client participant | Returns an error string if no WebRTC client is found in the room. |
| Streaming responses | Not supported. The full response is awaited before returning. |
Full example
Attach a shopping-cart tool to an Assistant. Fetch the send_rpc_request definition with GET /data_next/ai/toolDefinitions?where={"name":"send_rpc_request"} and use its id as definitionId. Replace the example Assistant ID and token with your own. Your connected WebRTC client must register an updateCart RPC handler that accepts this payload and returns a response string.
Code
Code