This guide was prepared with AI assistance using the linked documentation. Code examples are illustrative; verify them against your environment and current API documentation before use.
A source link has a job to do
A reader asking for a policy deadline needs to know where the date came from. A list of document names at the bottom of an answer is a start, but it may not show which document supports which claim.
Design the answer and evidence together. The reader should be able to follow a reference, see the relevant document or passage when permitted, and understand when the source is missing or conflicting.
Separate a search result from a citation
A retrieved passage is a candidate for evidence; its presence in search results does not prove the generated answer uses it correctly. OpenAI's file-search response can include file annotations, while returned search results require an explicit include option. Inspect the response shape for the API and model you use.
Keep the source's identity, title, version, and access scope with your answer record. If a passage is unavailable or unauthorized, do not substitute a fabricated quotation.
Represent evidence explicitly
This small local type sketch separates the answer from its evidence. It is not a provider response schema; adapt it after parsing and validating the response from your chosen API.
type Evidence = { documentId: string; title: string; version?: string; href: string };
type Answer = { text: string; evidence: Evidence[]; status: "supported" | "insufficient" };
function mayShowSource(canRead: boolean, item: Evidence): Evidence | null {
return canRead ? item : null;
}Handle gaps and conflicts
A useful no-answer state says the available sources do not settle the question. Give the reader a way to refine the question or find an owner. Avoid treating a weak retrieval score as a precise probability that a statement is true.
When two policy versions disagree, display the conflict and relevant dates if the documents provide them. Your product should decide which version is authoritative through an explicit business rule or a human review, rather than silently choosing one.
Test the claim-to-source connection
Create a small evaluation set with known answers and source passages. For each response, inspect whether the right document was retrieved, the cited material is accessible, and the answer actually follows from it. Include a question whose answer is absent.
- Test a source that was replaced after the answer was generated.
- Try a citation link after access has been revoked.
- Check a response containing multiple claims supported by different documents.
Keep the reader in control
Show citations close enough to the answer that a reader can associate a claim with its source. Use descriptive links, make keyboard access possible, and distinguish source text from a model's paraphrase.
Recheck the source on access. A citation is not a permanent authorization grant, and an answer that was supported last month may need revalidation when its source changes.
Walk through a deadline answer
Suppose a reader asks when an application closes. Your retrieval step finds a policy document with a date. The assistant's answer says the deadline is 15 May, with a source link beside that statement. When the reader opens the link, the application checks access again and presents the document title and version it has stored.
That flow is only trustworthy if the date in the answer is actually supported by the cited material. A citation that names a relevant file but points to the wrong passage can still mislead. Review the passage and the generated claim together in your evaluation set.
If the same document has two deadlines for different application types, the answer should retain that distinction or ask which type the reader means. If your interface cannot show the relevant passage, say what the citation opens rather than implying that a particular line has been verified.
Decide what reviewers can inspect
Keep a compact evaluation record for each answer: the question, the authorized collection, the source identifier, the generated claim, and a reviewer decision. Store source text only when your retention and access policies allow it. A reviewer should be able to distinguish an incorrect answer from an incorrect retrieval result.
Use a fixed set of examples when comparing changes to a prompt or retrieval configuration. If a change finds the right document more often but increases unsupported claims, report both outcomes. A higher retrieval score by itself does not establish that readers are getting better answers.
Include source links in keyboard and screen-reader checks. A descriptive label such as the document title gives the reader more context than a row of numbered links, especially when several sources support different statements.
Sources and further reading
Documentation reviewed November 9, 2026. Verify current model support, limits and pricing before implementation.