Azure / Azure/azure-sdk-for-python
Feature Request: Return `chunk_id` in URL Citation Annotations for Azure AI Search Tool
- Lingua principale
- Python
- Stelle
- 5.6k
- Fork
- 3.4k
- Merge medio
- 2g
- PR unite (30g)
- 217
Descrizione
## 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.
Guida per i contributori
Apri la guida per i contributori
Direzione di ricerca
Inizia tracciando l’output di AzureAISearchAgentTool fino alle annotazioni url_citation della Responses API, soprattutto quando usi openai_client.responses.create(stream=True). Confronta la mappatura chunk_id richiesta con l’issue correlata #42218 e verifica quali metadati del risultato di Azure AI Search sono disponibili. Il lavoro è completato quando ogni citation può identificare il proprio chunk recuperato specifico senza compromettere i campi di annotazione esistenti.
Scritto dal modello di indicizzazione a partire dal testo della issue.
Valutazione
- Stack tecnologico
- azure, python
- Ambito
- api, backend
- Tipo di issue
- Funzionalità
- Difficoltà
- 4/5
- Tempo stimato
- 3-5 giorni
- Stato di attività
- Tranquilla
- Chiarezza
- Abbastanza chiara
- Idoneità per principianti
- 45/100