Events¶
With X-Faden-Events: ag-ui, the server tells your client what it does while it answers: which server tools ran, which sources were used, what personal data was found, and what was refused. The SDKs use these to show tool lines, citations and notices.
Server version
The extra events come with the next Fadenstack release, after 0.4.1.
How they arrive¶
In a streamed answer, events come between OpenAI's chunks as server-sent events of their own type:
event: faden
data: {"type": "TOOL_CALL_START", "toolCallId": "call_1", "toolCallName": "knowledge_search", "kind": "knowledge"}
OpenAI clients that only read data: lines of the default event type ignore them.
In a whole answer, the response has a faden object with an events list.
Event types¶
The shapes follow the AG-UI event protocol.
| Type | Fields | Means |
|---|---|---|
TOOL_CALL_START |
toolCallId, toolCallName, kind |
A server tool started. kind is knowledge, attachment, skill_file, mcp or system. |
TOOL_CALL_END |
toolCallId, toolCallName, durationMs, error |
It ended |
CUSTOM |
name, value |
A Fadenstack event, below |
CUSTOM name |
value |
Means |
|---|---|---|
faden.citations |
tool, sources (each with source, document_id and the passages) |
Documents the answer drew on |
faden.pii |
mode, entities (kind: count) |
Personal data was found and handled; never the data itself |
faden.tool_mode |
mode, hidden |
The tool mode applied, and which tools it hid |
faden.tool_denied |
toolCallId, toolCallName, message |
A tool call was refused |
faden.approval_required |
approvalId, toolCallId, toolCallName, message, timeoutS |
A server tool waits for the user's approval. Answer it before the timeout. |
faden.governance |
outcome, stage, category, message |
A rule refused the request or the answer |
faden.gateway_round |
messages |
The server's own tool steps, for the client to keep in the conversation's history |
Ignore events you do not know; new ones may be added.