Skip to main content
AG-UI protocol endpoints for agents deployed via AGUI(agent).get_router().

Base URL

http://localhost:{port}
Default port is 8000.

Endpoints

POST /agui

Run agent with Server-Sent Events streaming. Request:
curl -X POST http://localhost:8000/agui \
  -H "Content-Type: application/json" \
  -d '{
    "threadId": "thread-123",
    "runId": "run-456",
    "state": {
      "messages": [
        {"id": "msg-1", "role": "user", "content": "Hello!"}
      ]
    }
  }'
Request Body:
FieldTypeRequiredDescription
threadIdstringYesThread identifier
runIdstringYesRun identifier
state.messagesarrayYesConversation messages
Response (SSE 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-2"}

event: text_message_content
data: {"type": "text_message_content", "messageId": "msg-2", "delta": "Hello"}

event: text_message_content
data: {"type": "text_message_content", "messageId": "msg-2", "delta": "! How can I help?"}

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

event: run_finished
data: {"type": "run_finished", "threadId": "thread-123", "runId": "run-456"}

GET /status

Check agent availability. Request:
curl http://localhost:8000/status
Response:
{
  "status": "available"
}

Event Types

EventDescription
run_startedAgent run has started
run_finishedAgent run completed
run_errorError occurred during run
text_message_startNew text message started
text_message_contentText content delta
text_message_endText message completed
tool_call_startTool call started
tool_call_argsTool call arguments
tool_call_endTool call completed

Message Format

Input Message:
{
  "id": "msg-1",
  "role": "user",
  "content": "Hello!"
}
FieldTypeDescription
idstringMessage ID
rolestring”user” or “assistant”
contentstringMessage content

Error Events

event: run_error
data: {"type": "run_error", "threadId": "thread-123", "runId": "run-456", "error": "Error message"}

Python Client

import requests

response = requests.post(
    "http://localhost:8000/agui",
    json={
        "threadId": "thread-123",
        "runId": "run-456",
        "state": {
            "messages": [{"id": "msg-1", "role": "user", "content": "Hello!"}]
        }
    },
    stream=True
)

for line in response.iter_lines():
    if line:
        line = line.decode('utf-8')
        if line.startswith('data: '):
            import json
            event = json.loads(line[6:])
            print(f"Event: {event['type']}")
            if event['type'] == 'text_message_content':
                print(f"  Delta: {event['delta']}")

JavaScript Client

const response = await fetch('http://localhost:8000/agui', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    threadId: 'thread-123',
    runId: 'run-456',
    state: {
      messages: [{ id: 'msg-1', role: 'user', content: 'Hello!' }]
    }
  })
});

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

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  
  const text = decoder.decode(value);
  const lines = text.split('\n');
  
  for (const line of lines) {
    if (line.startsWith('data: ')) {
      const event = JSON.parse(line.slice(6));
      console.log('Event:', event.type);
      if (event.type === 'text_message_content') {
        console.log('  Delta:', event.delta);
      }
    }
  }
}

CopilotKit Integration

import { CopilotKit } from "@copilotkit/react-core";

function App() {
  return (
    <CopilotKit runtimeUrl="http://localhost:8000/agui">
      <YourApp />
    </CopilotKit>
  );
}