You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: reference/api/chats.mdx
+213-6Lines changed: 213 additions & 6 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -402,11 +402,218 @@ The chat feature integrates with Meilisearch's authentication system:
402
402
403
403
## Tool calling
404
404
405
-
The chat feature uses internal tool calling to search your indexes.
406
-
But there are a bunch of tools that are automatically invoked based on the user's questions:
405
+
The chat feature uses internal tool calling to search your indexes and provide enhanced user experience. For optimal performance and user experience, you should declare three special tools in your chat completion requests. These tools are handled internally by Meilisearch and provide real-time feedback about search operations, conversation context, and source documents.
"description":"Append a new message to the conversation based on what happened internally",
462
+
"parameters": {
463
+
"type":"object",
464
+
"properties": {
465
+
"role": {
466
+
"type":"string",
467
+
"description":"The role of the messages author, either `role` or `assistant`"
468
+
},
469
+
"content": {
470
+
"type":"string",
471
+
"description":"The contents of the `assistant` or `tool` message. Required unless `tool_calls` is specified."
472
+
},
473
+
"tool_calls": {
474
+
"type": ["array", "null"],
475
+
"description":"The tool calls generated by the model, such as function calls",
476
+
"items": {
477
+
"type":"object",
478
+
"properties": {
479
+
"function": {
480
+
"type":"object",
481
+
"description":"The function that the model called",
482
+
"properties": {
483
+
"name": {
484
+
"type":"string",
485
+
"description":"The name of the function to call"
486
+
},
487
+
"arguments": {
488
+
"type":"string",
489
+
"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."
490
+
}
491
+
}
492
+
},
493
+
"id": {
494
+
"type":"string",
495
+
"description":"The ID of the tool call"
496
+
},
497
+
"type": {
498
+
"type":"string",
499
+
"description":"The type of the tool. Currently, only function is supported"
500
+
}
501
+
}
502
+
}
503
+
},
504
+
"tool_call_id": {
505
+
"type": ["string", "null"],
506
+
"description":"Tool call that this message is responding to"
"description":"The call ID to track the original search associated to those sources"
526
+
},
527
+
"documents": {
528
+
"type":"object",
529
+
"description":"The documents associated with the search (call_id). Only the displayed attributes of the documents are returned"
530
+
}
531
+
},
532
+
"required": ["call_id", "documents"],
533
+
"additionalProperties":false
534
+
},
535
+
"strict":true
536
+
}
537
+
}
538
+
]
539
+
}
540
+
```
541
+
542
+
</CodeGroup>
543
+
544
+
### Tool Functions Explained
545
+
546
+
#### `_meiliSearchProgress`
547
+
548
+
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.
549
+
550
+
**Purpose**: Provides transparency about search operations and reduces perceived latency by showing users what's happening behind the scenes.
551
+
552
+
**Arguments**:
553
+
- `call_id`: Unique identifier to track the search operation
554
+
- `function_name`: Name of the internal function being executed (e.g., "_meiliSearchInIndex")
555
+
- `function_parameters`: JSON-encoded string containing search parameters like `q` (query) and `index_uid`
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.
570
+
571
+
**Purpose**: Maintains conversation context for better response quality in subsequent requests by preserving tool calls and results.
572
+
573
+
**Arguments**:
574
+
- `role`: Message author role ("user" or "assistant")
575
+
- `content`: Message content (for tool results)
576
+
- `tool_calls`: Array of tool calls made by the assistant
577
+
- `tool_call_id`: ID of the tool call this message responds to
This tool provides the source documents that were used by the LLM to generate responses, enabling transparency and allowing users to verify information sources.
592
+
593
+
**Purpose**: Shows users which documents were used to generate responses, improving trust and enabling source verification.
594
+
595
+
**Arguments**:
596
+
- `call_id`: Matches the `call_id` from `_meiliSearchProgress` to associate queries with results
597
+
- `documents`: JSON object containing the source documents with only displayed attributes
1. **Always declare all three tools** for the best user experience
612
+
2. **Handle progress updates** by displaying search status to users during streaming
613
+
3. **Append conversation messages** as requested to maintain context for future requests
614
+
4. **Display source documents** to users for transparency and verification
615
+
5. **Use the `call_id`** to associate progress updates with their corresponding source results
616
+
617
+
<Note>
618
+
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.
0 commit comments