Azure / Azure/azure-sdk-for-python

Feature Request: Return `chunk_id` in URL Citation Annotations for Azure AI Search Tool

Open
#44,670 2 comments 1 reaction 0 assignees View on GitHub
AI Projects customer-reported needs-team-attention question Service Attention
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.