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

​
AG-UI Protocol Endpoints

The AG-UI protocol enables integration with CopilotKit and other AG-UI compatible frontends.

​
Base URL

http://localhost:8000

​
Endpoints

​
Run Agent

Execute the agent via AG-UI protocol with Server-Sent Events streaming.
​
POST
/agui
Run agent with streaming response
Request Body 
{
  "threadId": "thread-123",
  "runId": "run-456",
  "state": {
    "messages": [
      {
        "id": "msg-1",
        "role": "user",
        "content": "Hello, agent!"
      }
    ]
  }
}
Response (Server-Sent Events) 
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.
​
GET
/status
Returns agent 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

​
Usage Example

​
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);
    }
  }
}

​
Setting Up AG-UI Server

from praisonaiagents import Agent
from praisonaiagents.ui.agui import AGUI
from fastapi import FastAPI
import uvicorn

# Create agent
agent = Agent(
    name="Assistant",
    role="Helpful AI Assistant",
    goal="Help users with their questions"
)

# Create AG-UI interface
agui = AGUI(agent=agent)

# Create FastAPI app
app = FastAPI()
app.include_router(agui.get_router())

# Run server
uvicorn.run(app, host="0.0.0.0", port=8000)

​
With CopilotKit

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

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