A2U API

Agent-to-User event streaming API endpoints

GET /a2u/info

A2U API

cURL

curl --request GET \
  --url http://127.0.0.1:8765/a2u/info \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "stream": "<string>",
  "filters": [
    {}
  ],
  "subscription_id": "<string>"
}
'

import requests

url = "http://127.0.0.1:8765/a2u/info"

payload = {
    "stream": "<string>",
    "filters": [{}],
    "subscription_id": "<string>"
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'GET',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({stream: '<string>', filters: [{}], subscription_id: '<string>'})
};

fetch('http://127.0.0.1:8765/a2u/info', 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/a2u/info",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_POSTFIELDS => json_encode([
    'stream' => '<string>',
    'filters' => [
        [
                
        ]
    ],
    'subscription_id' => '<string>'
  ]),
  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/a2u/info"

	payload := strings.NewReader("{\n  \"stream\": \"<string>\",\n  \"filters\": [\n    {}\n  ],\n  \"subscription_id\": \"<string>\"\n}")

	req, _ := http.NewRequest("GET", 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.get("http://127.0.0.1:8765/a2u/info")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"stream\": \"<string>\",\n  \"filters\": [\n    {}\n  ],\n  \"subscription_id\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("http://127.0.0.1:8765/a2u/info")

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

request = Net::HTTP::Get.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"stream\": \"<string>\",\n  \"filters\": [\n    {}\n  ],\n  \"subscription_id\": \"<string>\"\n}"

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

A2U API

The A2U (Agent-to-User) API provides Server-Sent Events (SSE) streaming for real-time agent-to-user communication.

Overview

A2U enables real-time event streaming from agents to users, including:

• Agent status updates
• Thinking/processing indicators
• Tool call notifications
• Response streaming
• Error notifications

When to Use

• Real-time UI: Update UI as agent processes
• Progress tracking: Show agent thinking/tool usage
• Streaming responses: Display responses as they’re generated

Base URL + Playground

# Start A2U server
praisonai serve a2u --host 127.0.0.1 --port 8083

Base URL: http://127.0.0.1:8083

Endpoints

GET /a2u/info

Get A2U server information and available event types.

curl

curl http://127.0.0.1:8083/a2u/info

import requests

response = requests.get("http://127.0.0.1:8083/a2u/info")
info = response.json()
print(f"Event types: {info['event_types']}")

Response:

{
  "name": "A2U Event Stream",
  "version": "1.0.0",
  "streams": ["events"],
  "event_types": [
    "agent.started",
    "agent.thinking",
    "agent.tool_call",
    "agent.response",
    "agent.completed",
    "agent.error"
  ]
}

POST /a2u/subscribe

Create a subscription to an event stream.

stream · string · default: "events"

Stream name to subscribe to

filters · array

Optional list of event types to filter

curl

curl -X POST http://127.0.0.1:8083/a2u/subscribe \
  -H "Content-Type: application/json" \
  -d '{"stream": "events", "filters": ["agent.response", "agent.completed"]}'

import requests

response = requests.post(
    "http://127.0.0.1:8083/a2u/subscribe",
    json={"stream": "events", "filters": ["agent.response"]}
)
subscription = response.json()
print(f"Stream URL: {subscription['stream_url']}")

Response:

{
  "subscription_id": "sub-abc123def456",
  "stream_name": "events",
  "stream_url": "http://127.0.0.1:8083/a2u/events/sub/sub-abc123def456",
  "created_at": "2024-01-15T10:30:00Z"
}

GET /a2u/events/

Subscribe and stream events via SSE.

stream_name · string · default: "events"

Stream name to subscribe to

curl

curl -N http://127.0.0.1:8083/a2u/events/events

import requests

response = requests.get(
    "http://127.0.0.1:8083/a2u/events/events",
    stream=True
)
for line in response.iter_lines():
    if line:
        print(line.decode())

const eventSource = new EventSource("http://127.0.0.1:8083/a2u/events/events");

eventSource.addEventListener("agent.response", (event) => {
  const data = JSON.parse(event.data);
  console.log("Response:", data.response);
});

eventSource.addEventListener("agent.completed", (event) => {
  console.log("Agent completed");
  eventSource.close();
});

SSE Events:

event: agent.started
data: {"agent_id": "agent-1", "agent_name": "Assistant"}
id: evt-001

event: agent.thinking
data: {"agent_id": "agent-1", "message": "Processing query..."}
id: evt-002

event: agent.tool_call
data: {"agent_id": "agent-1", "tool_name": "web_search", "arguments": {"query": "AI"}}
id: evt-003

event: agent.response
data: {"agent_id": "agent-1", "response": "Here are the results..."}
id: evt-004

event: agent.completed
data: {"agent_id": "agent-1", "result": "Task completed"}
id: evt-005

POST /a2u/unsubscribe

Unsubscribe from an event stream.

subscription_id · string · required

Subscription ID to unsubscribe

curl -X POST http://127.0.0.1:8083/a2u/unsubscribe \
  -H "Content-Type: application/json" \
  -d '{"subscription_id": "sub-abc123def456"}'

Response:

{
  "status": "unsubscribed"
}

GET /a2u/health

A2U subsystem health check.

curl http://127.0.0.1:8083/a2u/health

Response:

{
  "status": "healthy",
  "active_subscriptions": 3,
  "active_streams": 1
}

Event Types

Event	Description
agent.started	Agent started processing
agent.thinking	Agent is thinking/processing
agent.tool_call	Agent called a tool
agent.response	Agent generated a response
agent.completed	Agent completed task
agent.error	Agent encountered an error

Errors

Status	Description
200	Success
400	Invalid request
404	Subscription not found
500	Server error

CLI Equivalent

# Start A2U server
praisonai serve a2u --port 8083

Python SDK

from praisonai.endpoints.a2u_server import (
    emit_agent_started,
    emit_agent_response,
    emit_agent_completed
)

# Emit events from your agent code
emit_agent_started("agent-1", "Assistant")
emit_agent_response("agent-1", "Hello, how can I help?")
emit_agent_completed("agent-1", result="Done")

Notes

• Events are delivered via Server-Sent Events (SSE)
• Subscriptions auto-cleanup on disconnect
• Use filters to reduce event volume
• Events include timestamps and unique IDs

Related

• A2A API - Agent-to-Agent protocol
• Agents API - Agent invocation