Self Checks
Is your feature request related to a problem?
When using the agent completions endpoint (/api/v1/agents/{agent_id}/completions), there is no way to retrieve document metadata alongside reference chunks. This makes it impossible to display source attribution (e.g. author, document title, creation date) in applications built on the agent API, even though the underlying knowledge base has this metadata available.Describe the feature you'd like
extra_body.reference_metadata should be supported on /api/v1/agents/{agent_id}/completions, mirroring the existing behaviour on the chat completions endpoint (/api/v1/chats/{chat_id}/completions).
Request body:
{
"question": "What is the refund policy?",
"stream": true,
"extra_body": {
"reference_metadata": {
"include": true,
"fields": ["author", "created_time"]
}
}
}
When include: true, each reference chunk in the response should include a document_metadata object, e.g.:
{
"id": "abc123",
"content": "Refunds are processed within 5 business days...",
"document_metadata": {
"author": "Policy Team",
"created_time": "2024-01-15"
}
}
Describe implementation you've considered
he chat completions handler already parses extra_body.reference_metadata and passes include_metadata/metadata_fields through to the retrieval layer (api/apps/sdk/session.py, ~line 240):
reference_metadata = extra_body.get("reference_metadata") or {}
include_reference_metadata = bool(reference_metadata.get("include", False))
metadata_fields = reference_metadata.get("fields")
The agent completions handler (/agents/<agent_id>/completions) passes the full request body as **kwargs into canvas_service.completion(), which ignores extra_body entirely — reference_metadata is never extracted or forwarded. The same parsing logic would need to be applied in the agent handler and threaded through to wherever references are assembled in the canvas run pipeline.
Documentation, adoption, use case
Any client application using agents rather than plain chatbots that needs to show users which source documents a response drew from — with author, date, title, or other metadata — is currently blocked. This is a common requirement for transparency in RAG-based UIs. The feature already exists and is documented for chat completions; agent completions should behave consistently.
Additional information
No response
Self Checks
Is your feature request related to a problem?
When using the agent completions endpoint (/api/v1/agents/{agent_id}/completions), there is no way to retrieve document metadata alongside reference chunks. This makes it impossible to display source attribution (e.g. author, document title, creation date) in applications built on the agent API, even though the underlying knowledge base has this metadata available.Describe the feature you'd like
extra_body.reference_metadata should be supported on /api/v1/agents/{agent_id}/completions, mirroring the existing behaviour on the chat completions endpoint (/api/v1/chats/{chat_id}/completions).
Request body:
When include: true, each reference chunk in the response should include a document_metadata object, e.g.:
Describe implementation you've considered
he chat completions handler already parses extra_body.reference_metadata and passes include_metadata/metadata_fields through to the retrieval layer (api/apps/sdk/session.py, ~line 240):
The agent completions handler (/agents/<agent_id>/completions) passes the full request body as **kwargs into canvas_service.completion(), which ignores extra_body entirely — reference_metadata is never extracted or forwarded. The same parsing logic would need to be applied in the agent handler and threaded through to wherever references are assembled in the canvas run pipeline.
Documentation, adoption, use case
Additional information
No response