Azure / Azure/azure-sdk-for-python
Feature Request: Return `chunk_id` in URL Citation Annotations for Azure AI Search Tool
- Dominant language
- Python
- Stars
- 5.6k
- Forks
- 3.4k
- Avg merge
- 1d 21h
- Merged PRs (30d)
- 193
Description
## Is your feature request related to a problem? Please describe.
When using `AzureAISearchAgentTool` with the Azure AI Projects SDK (Responses API), the agent returns citations via `url_citation` annotations in the response. These annotations include:
- `start_index` / `end_index` - position in the response text
- `url` - the search service URL
- `title` - document name (e.g., "doc_2")
However, there is **no way to map a specific citation back to the exact chunk** that was retrieved from Azure AI Search. The `title` field only provides the document name, not the specific chunk within that document.
**Example current annotation:**
```python
annotation.type = "url_citation"
annotation.url = "https://mysearch.search.windows.net/"
annotation.title = "doc_2" # Which chunk
annotation.start_index = 558
annotation.end_index = 570
```
## Describe the solution you'd like
Add a `chunk_id` (or `result_id` / `source_id`) field to the `url_citation` annotation that maps directly to the specific chunk from the Azure AI Search results.
**Proposed annotation structure:**
```python
annotation.type = "url_citation"
annotation.url = "https://mysearch.search.windows.net/"
annotation.title = "doc_2"
annotation.chunk_id = "" # <-- NEW: Specific chunk identifier
annotation.start_index = 558
annotation.end_index = 570
```
This would allow developers to:
1. Trace exactly which chunk the model used for each citation
2. Retrieve the full chunk content from their search index
3. Build proper citation UIs with accurate source linking
4. Implement evaluation/debugging for RAG applications
## Differentiation from Related Issue
This request is **different from [#42218](https://github.com/Azure/azure-sdk-for-python/issues/42218)**, which asks for search results to be returned per tool call.
| Issue | Scope | Use Case |
|-------|-------|----------|
| #42218 | Return all search results for each tool call | See what chunks were retrieved |
| **This request** | Return chunk_id per annotation/citation | Map each citation to its specific source chunk |
Even if #42218 is implemented, without chunk IDs in annotations, there's no reliable way to correlate which retrieved chunk corresponds to which citation in the response.
## Describe alternatives you've considered
N/A
## Additional context
**SDK versions:**
- `azure-ai-projects>=2.0.0b1`
- Using `AzureAISearchAgentTool` with `openai_client.responses.create(stream=True)`
**Current output showing the gap:**
```
📝 Citations in Response:
Citation:
Referenced Text: '【4:2†source】'
URL: https://mysearch.search.windows.net/
Title: doc_2 # <-- no chunk ID
Position: [558:570]
```
**Expected behavior:**
Each `url_citation` annotation should include a `chunk_id` field that uniquely identifies the source chunk, enabling precise citation-to-source mapping.
Contributor guide
Assessment
This issue has not been assessed yet.