Skip to main content
POST
/
agui
POST /agui
curl --request POST \
  --url https://api.example.com/agui \
  --header 'Authorization: Bearer <token>'

​
POST /agui

Run an agent and receive a streaming response via AG-UI protocol.

​
Endpoint

POST /agui

​
Description

This endpoint accepts a message and returns a Server-Sent Events (SSE) stream with AG-UI protocol events. It’s designed for integration with CopilotKit and similar frontend frameworks.

​
Request

​
Headers

HeaderValueRequired
Content-Typeapplication/jsonYes
Accepttext/event-streamRecommended

​
Body

{
  "message": "What is machine learning?",
  "thread_id": "thread-123",
  "run_id": "run-456"
}

​
Request Fields

FieldTypeRequiredDescription
messagestringYesUser message
thread_idstringNoThread/conversation ID
run_idstringNoRun identifier

​
Response

​
Success Response (200 OK)

Returns a Server-Sent Events stream. 
event: RUN_STARTED
data: {"type": "RUN_STARTED", "threadId": "thread-123", "runId": "run-456"}

event: TEXT_MESSAGE_START
data: {"type": "TEXT_MESSAGE_START", "messageId": "msg-789"}

event: TEXT_MESSAGE_CONTENT
data: {"type": "TEXT_MESSAGE_CONTENT", "content": "Machine learning is"}

event: TEXT_MESSAGE_CONTENT
data: {"type": "TEXT_MESSAGE_CONTENT", "content": " a subset of AI..."}

event: TEXT_MESSAGE_END
data: {"type": "TEXT_MESSAGE_END"}

event: RUN_FINISHED
data: {"type": "RUN_FINISHED"}

​
Event Types

EventDescription
RUN_STARTEDAgent run has started
TEXT_MESSAGE_STARTText message beginning
TEXT_MESSAGE_CONTENTStreaming text content
TEXT_MESSAGE_ENDText message complete
TOOL_CALL_STARTTool call beginning
TOOL_CALL_ARGSTool call arguments
TOOL_CALL_ENDTool call complete
RUN_FINISHEDAgent run complete
RUN_ERRORError occurred

​
Example

​
cURL

curl -X POST http://localhost:8000/agui \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{"message": "Hello!"}'

​
Python

import requests

response = requests.post(
    "http://localhost:8000/agui",
    json={"message": "Hello!"},
    headers={"Accept": "text/event-stream"},
    stream=True
)

for line in response.iter_lines():
    if line:
        print(line.decode())

​
JavaScript (EventSource)

const response = await fetch("http://localhost:8000/agui", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ message: "Hello!" }),
});

const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  console.log(decoder.decode(value));
}

​
Error Responses

StatusDescription
400Bad request - missing message
500Internal server error

​
See Also