|
| 1 | +--- |
| 2 | +title: Chat tooling reference |
| 3 | +description: An exhaustive reference of special chat tools supported by Meilisearch |
| 4 | +--- |
| 5 | + |
| 6 | +When creating your conversational search agent, you may be able to extend the model's capabilities with a number of tools. This page lists Meilisearch-specific tools that may improve user experience. |
| 7 | + |
| 8 | +<Note> |
| 9 | +This is an experimental feature. Use the Meilisearch Cloud UI or the experimental features endpoint to activate it: |
| 10 | + |
| 11 | +```sh |
| 12 | +curl \ |
| 13 | + -X PATCH 'MEILISEARCH_URL/experimental-features/' \ |
| 14 | + -H 'Content-Type: application/json' \ |
| 15 | + --data-binary '{ |
| 16 | + "chatCompletions": true |
| 17 | + }' |
| 18 | +``` |
| 19 | +</Note> |
| 20 | + |
| 21 | +## Meilisearch chat tools |
| 22 | + |
| 23 | +For the best user experience, configure all following tools. |
| 24 | + |
| 25 | +1. **Handle progress updates** by displaying search status to users during streaming |
| 26 | +2. **Append conversation messages** as requested to maintain context for future requests |
| 27 | +3. **Display source documents** to users for transparency and verification |
| 28 | +4. **Use `call_id`** to associate progress updates with their corresponding source results |
| 29 | + |
| 30 | +<Note> |
| 31 | +These special tools are handled internally by Meilisearch and are not forwarded to the LLM provider. They serve as a communication mechanism between Meilisearch and your application to provide enhanced user experience features. |
| 32 | +</Note> |
| 33 | + |
| 34 | +### `_meiliSearchProgress` |
| 35 | + |
| 36 | +This tool reports real-time progress of internal search operations. When declared, Meilisearch will call this function whenever search operations are performed in the background. |
| 37 | + |
| 38 | +**Purpose**: Provides transparency about search operations and reduces perceived latency by showing users what's happening behind the scenes. |
| 39 | + |
| 40 | +**Arguments**: |
| 41 | + |
| 42 | +- `call_id`: Unique identifier to track the search operation |
| 43 | +- `function_name`: Name of the internal function being executed (e.g., "_meiliSearchInIndex") |
| 44 | +- `function_parameters`: JSON-encoded string containing search parameters like `q` (query) and `index_uid` |
| 45 | + |
| 46 | +**Example Response**: |
| 47 | + |
| 48 | +```json |
| 49 | +{ |
| 50 | + "function": { |
| 51 | + "name": "_meiliSearchProgress", |
| 52 | + "arguments": "{\"call_id\":\"89939d1f-6857-477c-8ae2-838c7a504e6a\",\"function_name\":\"_meiliSearchInIndex\",\"function_parameters\":\"{\\\"index_uid\\\":\\\"movies\\\",\\\"q\\\":\\\"search engine\\\"}\"}" |
| 53 | + } |
| 54 | +} |
| 55 | +``` |
| 56 | + |
| 57 | +### `_meiliAppendConversationMessage` |
| 58 | + |
| 59 | +Since the `/chats/{workspace}/chat/completions` endpoint is stateless, this tool helps maintain conversation context by requesting the client to append internal messages to the conversation history. |
| 60 | + |
| 61 | +**Purpose**: Maintains conversation context for better response quality in subsequent requests by preserving tool calls and results. |
| 62 | + |
| 63 | +**Arguments**: |
| 64 | + |
| 65 | +- `role`: Message author role ("user" or "assistant") |
| 66 | +- `content`: Message content (for tool results) |
| 67 | +- `tool_calls`: Array of tool calls made by the assistant |
| 68 | +- `tool_call_id`: ID of the tool call this message responds to |
| 69 | + |
| 70 | +**Example Response**: |
| 71 | + |
| 72 | +```json |
| 73 | +{ |
| 74 | + "function": { |
| 75 | + "name": "_meiliAppendConversationMessage", |
| 76 | + "arguments": "{\"role\":\"assistant\",\"tool_calls\":[{\"id\":\"call_ijAdM42bixq9lAF4SiPwkq2b\",\"type\":\"function\",\"function\":{\"name\":\"_meiliSearchInIndex\",\"arguments\":\"{\\\"index_uid\\\":\\\"movies\\\",\\\"q\\\":\\\"search engine\\\"}\"}}]}" |
| 77 | + } |
| 78 | +} |
| 79 | +``` |
| 80 | + |
| 81 | +### `_meiliSearchSources` |
| 82 | + |
| 83 | +This tool provides the source documents that were used by the LLM to generate responses, enabling transparency and allowing users to verify information sources. |
| 84 | + |
| 85 | +**Purpose**: Shows users which documents were used to generate responses, improving trust and enabling source verification. |
| 86 | + |
| 87 | +**Arguments**: |
| 88 | + |
| 89 | +- `call_id`: Matches the `call_id` from `_meiliSearchProgress` to associate queries with results |
| 90 | +- `documents`: JSON object containing the source documents with only displayed attributes |
| 91 | + |
| 92 | +**Example Response**: |
| 93 | + |
| 94 | +```json |
| 95 | +{ |
| 96 | + "function": { |
| 97 | + "name": "_meiliSearchSources", |
| 98 | + "arguments": "{\"call_id\":\"abc123\",\"documents\":[{\"id\":197302,\"title\":\"The Sacred Science\",\"overview\":\"Diabetes. Prostate cancer...\",\"genres\":[\"Documentary\",\"Adventure\",\"Drama\"]}]}" |
| 99 | + } |
| 100 | +} |
| 101 | +``` |
| 102 | + |
| 103 | +### Sample OpenAI tool declaration |
| 104 | + |
| 105 | +Include these tools in your request's `tools` array to enable enhanced functionality: |
| 106 | + |
| 107 | +<CodeGroup> |
| 108 | + |
| 109 | +```json |
| 110 | +{ |
| 111 | + … |
| 112 | + "tools": [ |
| 113 | + { |
| 114 | + "type": "function", |
| 115 | + "function": { |
| 116 | + "name": "_meiliSearchProgress", |
| 117 | + "description": "Provides information about the current Meilisearch search operation", |
| 118 | + "parameters": { |
| 119 | + "type": "object", |
| 120 | + "properties": { |
| 121 | + "call_id": { |
| 122 | + "type": "string", |
| 123 | + "description": "The call ID to track the sources of the search" |
| 124 | + }, |
| 125 | + "function_name": { |
| 126 | + "type": "string", |
| 127 | + "description": "The name of the function we are executing" |
| 128 | + }, |
| 129 | + "function_parameters": { |
| 130 | + "type": "string", |
| 131 | + "description": "The parameters of the function we are executing, encoded in JSON" |
| 132 | + } |
| 133 | + }, |
| 134 | + "required": ["call_id", "function_name", "function_parameters"], |
| 135 | + "additionalProperties": false |
| 136 | + }, |
| 137 | + "strict": true |
| 138 | + } |
| 139 | + }, |
| 140 | + { |
| 141 | + "type": "function", |
| 142 | + "function": { |
| 143 | + "name": "_meiliAppendConversationMessage", |
| 144 | + "description": "Append a new message to the conversation based on what happened internally", |
| 145 | + "parameters": { |
| 146 | + "type": "object", |
| 147 | + "properties": { |
| 148 | + "role": { |
| 149 | + "type": "string", |
| 150 | + "description": "The role of the messages author, either `role` or `assistant`" |
| 151 | + }, |
| 152 | + "content": { |
| 153 | + "type": "string", |
| 154 | + "description": "The contents of the `assistant` or `tool` message. Required unless `tool_calls` is specified." |
| 155 | + }, |
| 156 | + "tool_calls": { |
| 157 | + "type": ["array", "null"], |
| 158 | + "description": "The tool calls generated by the model, such as function calls", |
| 159 | + "items": { |
| 160 | + "type": "object", |
| 161 | + "properties": { |
| 162 | + "function": { |
| 163 | + "type": "object", |
| 164 | + "description": "The function that the model called", |
| 165 | + "properties": { |
| 166 | + "name": { |
| 167 | + "type": "string", |
| 168 | + "description": "The name of the function to call" |
| 169 | + }, |
| 170 | + "arguments": { |
| 171 | + "type": "string", |
| 172 | + "description": "The arguments to call the function with, as generated by the model in JSON format. Note that the model does not always generate valid JSON, and may hallucinate parameters not defined by your function schema. Validate the arguments in your code before calling your function." |
| 173 | + } |
| 174 | + } |
| 175 | + }, |
| 176 | + "id": { |
| 177 | + "type": "string", |
| 178 | + "description": "The ID of the tool call" |
| 179 | + }, |
| 180 | + "type": { |
| 181 | + "type": "string", |
| 182 | + "description": "The type of the tool. Currently, only function is supported" |
| 183 | + } |
| 184 | + } |
| 185 | + } |
| 186 | + }, |
| 187 | + "tool_call_id": { |
| 188 | + "type": ["string", "null"], |
| 189 | + "description": "Tool call that this message is responding to" |
| 190 | + } |
| 191 | + }, |
| 192 | + "required": ["role", "content", "tool_calls", "tool_call_id"], |
| 193 | + "additionalProperties": false |
| 194 | + }, |
| 195 | + "strict": true |
| 196 | + } |
| 197 | + }, |
| 198 | + { |
| 199 | + "type": "function", |
| 200 | + "function": { |
| 201 | + "name": "_meiliSearchSources", |
| 202 | + "description": "Provides sources of the search", |
| 203 | + "parameters": { |
| 204 | + "type": "object", |
| 205 | + "properties": { |
| 206 | + "call_id": { |
| 207 | + "type": "string", |
| 208 | + "description": "The call ID to track the original search associated to those sources" |
| 209 | + }, |
| 210 | + "documents": { |
| 211 | + "type": "object", |
| 212 | + "description": "The documents associated with the search (call_id). Only the displayed attributes of the documents are returned" |
| 213 | + } |
| 214 | + }, |
| 215 | + "required": ["call_id", "documents"], |
| 216 | + "additionalProperties": false |
| 217 | + }, |
| 218 | + "strict": true |
| 219 | + } |
| 220 | + } |
| 221 | + ] |
| 222 | +} |
| 223 | +``` |
| 224 | + |
| 225 | +</CodeGroup> |
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4&size=40){kind=avatar}
0 commit comments