Merge pull request openai#107 from openai/update-docs-for-entity-tags-and-annotations

jiwon-oai · web-flow · commit 22496cecf8c5 · 2026-01-17T06:37:59.000Z
[docs] Update docs on entity tags and annotations
diff --git a/docs/guides/accept-rich-user-input.md b/docs/guides/accept-rich-user-input.md
@@ -182,6 +182,8 @@ To enable entity tagging as @-mentions in the composer, configure [`entities.onT
 
 It should return a list of [Entity](https://openai.github.io/chatkit-js/api/openai/chatkit/type-aliases/entity/) objects that match the query string.
 
+If you want to hint that @-mentions are available, enable the composer `@` button by setting [`entities.showComposerMenu`](https://openai.github.io/chatkit-js/api/openai/chatkit/type-aliases/entitiesoption/#showcomposermenu). When clicked, it inserts `@` into the composer and opens the tag search menu automatically.
+
 ```ts
 const chatkit = useChatKit({
   // ...
@@ -204,6 +206,8 @@ const chatkit = useChatKit({
         },
       ]
     },
+    // Optional: show the "@" button in the composer for added discoverability.
+    showComposerMenu: true,
   },
 })
 ```
diff --git a/docs/guides/add-annotations.md b/docs/guides/add-annotations.md
@@ -13,6 +13,53 @@ Provide the model with citable evidence via tools to receive citation annotation
 
 No additional server-side wiring is required beyond calling `stream_agent_response`. If the model emits citation annotations from tool usage, ChatKit will forward them automatically as `Annotation` objects on the corresponding content parts.
 
+### Customize how citations are converted
+
+Sometimes the default rendering for model-emitted citations is not very helpful. For example, file citations may not include enough metadata for ChatKit to show a meaningful default title or description. You can pass a custom [`ResponseStreamConverter`](../../api/chatkit/agents/#chatkit.agents.ResponseStreamConverter) and override:
+
+- `file_citation_to_annotation`
+- `container_file_citation_to_annotation`
+- `url_citation_to_annotation`
+
+Here is a minimal example that enriches file citations with a more helpful title/description using an internal mapping:
+
+```python
+from chatkit.agents import ResponseStreamConverter, stream_agent_response
+from chatkit.types import Annotation, FileSource
+
+
+class MyResponseStreamConverter(ResponseStreamConverter):
+    def __init__(self, file_lookup: dict[str, dict[str, str]]):
+        super().__init__()
+        self._file_lookup = file_lookup
+
+    async def file_citation_to_annotation(self, citation):
+        info = self._file_lookup.get(citation.file_id, {})
+        return Annotation(
+            source=FileSource(
+                filename=info.get("filename", citation.file_id),
+                title=info.get("title"),
+                description=info.get("description"),
+            ),
+            index=citation.index,
+        )
+
+
+converter = MyResponseStreamConverter(
+    file_lookup={
+        "file_123": {
+            "filename": "q1_report.pdf",
+            "title": "Q1 Report",
+            "description": "Quarterly performance summary",
+        }
+    }
+)
+
+stream_agent_response(..., converter=converter)
+```
+
+You can also return an `EntitySource` instead of a `FileSource` to control the inline label, handle clicks, and customize the popover preview. For more on entity annotations (including `interactive` click/preview hooks), see [Annotating with custom entities](#annotating-with-custom-entities) below.
+
 
 ## Attach sources manually
 
