Deploy API: AGUI Server

curl --request POST \
  --url http://127.0.0.1:8765/agui \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "threadId": "<string>",
  "runId": "<string>",
  "state.messages": [
    {}
  ]
}
'

import requests

url = "http://127.0.0.1:8765/agui"

payload = {
    "threadId": "<string>",
    "runId": "<string>",
    "state.messages": [{}]
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({threadId: '<string>', runId: '<string>', 'state.messages': [{}]})
};

fetch('http://127.0.0.1:8765/agui', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_PORT => "8765",
  CURLOPT_URL => "http://127.0.0.1:8765/agui",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'threadId' => '<string>',
    'runId' => '<string>',
    'state.messages' => [
        [
                
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "http://127.0.0.1:8765/agui"

	payload := strings.NewReader("{\n  \"threadId\": \"<string>\",\n  \"runId\": \"<string>\",\n  \"state.messages\": [\n    {}\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("http://127.0.0.1:8765/agui")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"threadId\": \"<string>\",\n  \"runId\": \"<string>\",\n  \"state.messages\": [\n    {}\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("http://127.0.0.1:8765/agui")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"threadId\": \"<string>\",\n  \"runId\": \"<string>\",\n  \"state.messages\": [\n    {}\n  ]\n}"

response = http.request(request)
puts response.read_body

POST

agui

Deploy API: AGUI Server

curl --request POST \
  --url http://127.0.0.1:8765/agui \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "threadId": "<string>",
  "runId": "<string>",
  "state.messages": [
    {}
  ]
}
'

import requests

url = "http://127.0.0.1:8765/agui"

payload = {
    "threadId": "<string>",
    "runId": "<string>",
    "state.messages": [{}]
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({threadId: '<string>', runId: '<string>', 'state.messages': [{}]})
};

fetch('http://127.0.0.1:8765/agui', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_PORT => "8765",
  CURLOPT_URL => "http://127.0.0.1:8765/agui",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'threadId' => '<string>',
    'runId' => '<string>',
    'state.messages' => [
        [
                
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "http://127.0.0.1:8765/agui"

	payload := strings.NewReader("{\n  \"threadId\": \"<string>\",\n  \"runId\": \"<string>\",\n  \"state.messages\": [\n    {}\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("http://127.0.0.1:8765/agui")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"threadId\": \"<string>\",\n  \"runId\": \"<string>\",\n  \"state.messages\": [\n    {}\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("http://127.0.0.1:8765/agui")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"threadId\": \"<string>\",\n  \"runId\": \"<string>\",\n  \"state.messages\": [\n    {}\n  ]\n}"

response = http.request(request)
puts response.read_body

AGUI API

AG-UI protocol endpoints for agents deployed via AGUI(agent).get_router(). Compatible with CopilotKit.

Base URL + Playground

# Start AGUI server
from praisonaiagents import Agent
from praisonaiagents.agui import AGUI
import uvicorn

agent = Agent(instructions="You are a helpful assistant")
app = AGUI(agent).get_router()
uvicorn.run(app, host="0.0.0.0", port=8000)

Base URL: http://localhost:8000

Endpoints

POST /agui

Run agent with Server-Sent Events streaming.

string

required

Thread identifier

string

required

Run identifier

array

required

Conversation messages array

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!"}
      ]
    }
  }'

import requests
import json

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: '):
            event = json.loads(line[6:])
            print(f"Event: {event['type']}")
            if event['type'] == 'text_message_content':
                print(f"  Delta: {event['delta']}")

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);
  for (const line of text.split('\n')) {
    if (line.startsWith('data: ')) {
      const event = JSON.parse(line.slice(6));
      console.log('Event:', event.type);
    }
  }
}

Response (SSE Stream):

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

event: tool_call_start
data: {"type": "tool_call_start", "toolCallId": "call-1", "toolCallName": "search"}

event: custom
data: {"type": "custom", "name": "praisonai.tool_progress", "value": {"content": "Fetched 12 results", "tool_call": {"id": "call-1"}, "metadata": {"progress": 0.5}}}

event: tool_call_end
data: {"type": "tool_call_end", "toolCallId": "call-1"}

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"}

The custom event carries a praisonai.* name. Clients that do not recognise a custom name must ignore it — see PraisonAI custom events.

GET /status

Check agent availability.

none

No parameters required.

curl http://localhost:8000/status

import requests

response = requests.get("http://localhost:8000/status")
print(response.json())

Response:

{
  "status": "available"
}

Event Types

Event	Description
`run_started`	Agent run has started
`run_finished`	Agent run completed
`run_error`	Terminal error — includes mid-stream provider failures
`text_message_start`	New text message started
`text_message_content`	Text content delta
`text_message_end`	Text message completed
`tool_call_start`	Tool call started
`tool_call_args`	Tool call arguments
`tool_call_end`	Tool call completed
`custom` (`praisonai.*`)	PraisonAI-specific events for recoverable failures and progress — see below

PraisonAI custom events

AG-UI has no first-class frames for recoverable failures or user-visible progress. PraisonAI carries these as custom events with a praisonai.* name. AG-UI clients are expected to ignore custom event names they do not recognise, so adding these is backwards-compatible.

Custom event name	When it fires	`value` shape
`praisonai.retry`	LLM call is being retried after a transient failure	`{ message, metadata }`
`praisonai.model_fallback`	Provider swapped to a fallback model	`{ message, metadata }`
`praisonai.stream_unavailable`	Streaming path failed; falling back to non-streaming	`{ message, metadata }`
`praisonai.tool_progress`	A running tool emitted progress	`{ content, tool_call, metadata }`
`praisonai.todo_updated`	The agent’s todo list changed	`{ content, tool_call, metadata }`

Recoverable events (retry, model_fallback, stream_unavailable) are deliberately not run_error — the run continues. run_error is terminal in AG-UI. Branch on event.type === 'custom' and inspect event.name for the praisonai. prefix:

function handleEvent(event) {
  if (event.type === 'custom' && event.name.startsWith('praisonai.')) {
    switch (event.name) {
      case 'praisonai.retry':
      case 'praisonai.model_fallback':
      case 'praisonai.stream_unavailable':
        console.warn(`${event.name}: ${event.value.message}`);
        break;
      case 'praisonai.tool_progress':
      case 'praisonai.todo_updated':
        console.log(`${event.name}:`, event.value.content);
        break;
      default:
        break;  // ignore unknown praisonai.* events
    }
    return;
  }
  // ...handle standard AG-UI events (text_message_*, tool_call_*, run_*)
}

Message Format

Input Message:

{
  "id": "msg-1",
  "role": "user",
  "content": "Hello!"
}

Field	Type	Description
`id`	string	Message ID
`role`	string	”user” or “assistant”
`content`	string	Message content

Error Events

A terminal error reaches the client as run_error. This now includes mid-stream provider failures — a provider-side error part-way through a response is surfaced as run_error instead of being silently swallowed.

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

For recoverable conditions where the run continues (retry, model fallback, streaming fallback), the client receives a custom praisonai.* event instead — see PraisonAI custom events.

CopilotKit Integration

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

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

AGUI Server - Deploy agents as AGUI server
A2A API - A2A protocol endpoints
Agents API - HTTP REST endpoints

​AGUI API

​Base URL + Playground

​Endpoints

​POST /agui

​GET /status

​Event Types

​PraisonAI custom events

​Message Format

​Error Events

​CopilotKit Integration

​Related

AGUI API

Base URL + Playground

Endpoints

POST /agui

GET /status

Event Types

PraisonAI custom events

Message Format

Error Events

CopilotKit Integration

Related