Skip to main content
The AG-UI (Agent GUI) protocol provides a richer streaming interface than the OpenAI API. It’s used by the Sorat web frontend.

​
Endpoint

POST /ag-ui

​
Request body

{
  "threadId": "optional-session-id",
  "runId": "unique-run-id",
  "messages": [
    {"id": "msg-1", "role": "user", "content": "Do something"}
  ]
}

​
Response headers

HeaderDescription
X-Thread-IDThe session ID (returned for new sessions)
Content-Typetext/event-stream

​
Event types

The SSE stream emits events with a type field indicating the event kind.

​
Run lifecycle

EventFieldsDescription
RUN_STARTEDthreadId, runIdAgent run has begun
RUN_FINISHEDthreadId, runIdAgent run completed
RUN_ERRORmessage, codeError occurred

​
Reasoning (thinking)

EventFieldsDescription
REASONING_STARTmessageIdAgent started thinking
REASONING_CONTENTmessageId, deltaThought content chunk
REASONING_ENDmessageIdThought complete

​
Text messages

EventFieldsDescription
TEXT_MESSAGE_STARTmessageId, roleText response started
TEXT_MESSAGE_CONTENTmessageId, deltaText content chunk
TEXT_MESSAGE_ENDmessageIdText response complete

​
Tool calls

EventFieldsDescription
TOOL_CALL_STARTtoolCallId, toolCallNameTool invocation started
TOOL_CALL_ARGStoolCallId, deltaTool arguments (streamed)
TOOL_CALL_ENDtoolCallIdTool call finished
TOOL_CALL_RESULTtoolCallId, resultTool returned a result

​
Example stream

event: RUN_STARTED
data: {"type":"RUN_STARTED","threadId":"abc-123","runId":"run-456"}

event: REASONING_START
data: {"type":"REASONING_START","messageId":"msg-1"}

event: REASONING_CONTENT
data: {"type":"REASONING_CONTENT","messageId":"msg-1","delta":"Let me search for that..."}

event: REASONING_END
data: {"type":"REASONING_END","messageId":"msg-1"}

event: TOOL_CALL_START
data: {"type":"TOOL_CALL_START","toolCallId":"tc-1","toolCallName":"web_search"}

event: TOOL_CALL_ARGS
data: {"type":"TOOL_CALL_ARGS","toolCallId":"tc-1","delta":"{\"query\":\"Go 1.24\"}"}

event: TOOL_CALL_END
data: {"type":"TOOL_CALL_END","toolCallId":"tc-1"}

event: TOOL_CALL_RESULT
data: {"type":"TOOL_CALL_RESULT","toolCallId":"tc-1","result":"..."}

event: TEXT_MESSAGE_START
data: {"type":"TEXT_MESSAGE_START","messageId":"msg-2","role":"assistant"}

event: TEXT_MESSAGE_CONTENT
data: {"type":"TEXT_MESSAGE_CONTENT","messageId":"msg-2","delta":"Here's what I found..."}

event: TEXT_MESSAGE_END
data: {"type":"TEXT_MESSAGE_END","messageId":"msg-2"}

event: RUN_FINISHED
data: {"type":"RUN_FINISHED","threadId":"abc-123","runId":"run-456"}

​
Max iterations guard

The AG-UI handler enforces a maximum number of tool calls per run, configured via agent.max_iterations (default 30). If the limit is reached, a RUN_ERROR event is emitted.