> ## Documentation Index
> Fetch the complete documentation index at: https://docs.praison.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# A2U API

> Agent-to-User event streaming API endpoints

# 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

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# 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.

<CodeGroup>
  ```bash curl theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
  curl http://127.0.0.1:8083/a2u/info
  ```

  ```python Python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
  import requests

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

**Response:**

```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
{
  "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.

<ParamField body="stream" type="string" default="events">
  Stream name to subscribe to
</ParamField>

<ParamField body="filters" type="array">
  Optional list of event types to filter
</ParamField>

<CodeGroup>
  ```bash curl theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
  curl -X POST http://127.0.0.1:8083/a2u/subscribe \
    -H "Content-Type: application/json" \
    -d '{"stream": "events", "filters": ["agent.response", "agent.completed"]}'
  ```

  ```python Python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
  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']}")
  ```
</CodeGroup>

**Response:**

```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
{
  "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/{stream_name}

Subscribe and stream events via SSE.

<ParamField path="stream_name" type="string" default="events">
  Stream name to subscribe to
</ParamField>

<CodeGroup>
  ```bash curl theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
  curl -N http://127.0.0.1:8083/a2u/events/events
  ```

  ```python Python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
  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())
  ```

  ```javascript JavaScript theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
  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();
  });
  ```
</CodeGroup>

**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.

<ParamField body="subscription_id" type="string" required>
  Subscription ID to unsubscribe
</ParamField>

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
curl -X POST http://127.0.0.1:8083/a2u/unsubscribe \
  -H "Content-Type: application/json" \
  -d '{"subscription_id": "sub-abc123def456"}'
```

**Response:**

```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
{
  "status": "unsubscribed"
}
```

### GET /a2u/health

A2U subsystem health check.

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
curl http://127.0.0.1:8083/a2u/health
```

**Response:**

```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
{
  "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

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Start A2U server
praisonai serve a2u --port 8083
```

## Python SDK

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
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](/docs/deploy/api/a2a-api) - Agent-to-Agent protocol
* [Agents API](/docs/deploy/api/agents-api) - Agent invocation